@magnusekdahl/parallix 1.0.0

package/lib/tools/gatekeeper.js

@@ -0,0 +1,106 @@
+const fs = require('fs');
+const path = require('path');
+const fmt = require('../core/fmt');
+
+const { findMissionDir, findCheckpoints, missionDirForSlug, missionBranchName } = require('../core/mission-utils');
+const { resolveTaskFile } = require('./backlog');
+const { readToken, postReview } = require('./forgejo');
+
+const DEFAULT_GATEKEEPER_USER = 'forgejo-gatekeeper';
+
+// Pre-review pushback bot. Runs after performHandoff has created/updated the
+// PR and before the human/agent reviewer engages, so missing mandatory
+// artifacts surface as a request-changes review instead of consuming a
+// reviewer cycle. Returns { ok, missing, skipped, posted } so callers can
+// surface a clear log line without needing to re-derive state.
+
+function checkMandatoryFiles(slug, options = {}) {
+  const {
+    rootDir = process.cwd(),
+    findMissionDirFn = findMissionDir,
+    findCheckpointsFn = findCheckpoints,
+    resolveTaskFileFn = resolveTaskFile
+  } = options;
+
+  const missing = [];
+  const expectedMissionDir = missionDirForSlug(rootDir, slug);
+  const expectedMissionRel = path.relative(rootDir, expectedMissionDir).split(path.sep).join('/');
+
+  const missionDir = findMissionDirFn(slug, rootDir);
+  const missionPath = missionDir ? path.join(missionDir, 'MISSION.md') : null;
+  if (!missionPath || !fs.existsSync(missionPath)) {
+    missing.push(`${expectedMissionRel}/MISSION.md`);
+  }
+
+  if (missionDir) {
+    const checkpoints = findCheckpointsFn(missionDir);
+    if (!checkpoints || checkpoints.length === 0) {
+      missing.push(`${expectedMissionRel}/CP-*.md (at least one checkpoint document)`);
+    }
+  } else {
+    missing.push(`${expectedMissionRel}/CP-*.md (at least one checkpoint document)`);
+  }
+
+  const taskResolution = resolveTaskFileFn(slug, rootDir);
+  if (!taskResolution || !taskResolution.ok) {
+    missing.push('backlog/tasks/' + slug + ' - *.md');
+  }
+
+  return { ok: missing.length === 0, missing };
+}
+
+function buildPushbackBody(slug, missing) {
+  const bullets = missing.map(item => `- ${item}`).join('\n');
+  return [
+    `**Pre-review gatekeeper: missing mandatory artifacts for \`${slug}\`.**`,
+    '',
+    'The following files are required before a reviewer engages but were not found on this branch:',
+    '',
+    bullets,
+    '',
+    'Push the missing artifacts and re-request review. This comment is automated; once the artifacts are present the gatekeeper will not block again.'
+  ].join('\n');
+}
+
+function runGatekeeper(slug, options = {}) {
+  const {
+    rootDir = process.cwd(),
+    user = process.env.FORGEJO_GATEKEEPER_USER || DEFAULT_GATEKEEPER_USER,
+    log = fmt.log.plain,
+    readTokenFn = readToken,
+    postReviewFn = postReview,
+    checkFn = checkMandatoryFiles
+  } = options;
+  const branch = options.branch || missionBranchName(slug, rootDir);
+
+  const check = checkFn(slug, { rootDir });
+  if (check.ok) {
+    log(fmt.status('INFO', `Gatekeeper: all mandatory artifacts present for ${fmt.slug(slug)}.`));
+    return { ok: true, missing: [], skipped: false, posted: false };
+  }
+
+  const token = readTokenFn(user);
+  if (!token) {
+    log(fmt.status('WARN', `Gatekeeper: no Forgejo token for "${fmt.agent(user)}"; skipping pushback for ${fmt.slug(slug)}. Missing: ${check.missing.join(', ')}.`));
+    return { ok: false, missing: check.missing, skipped: true, posted: false };
+  }
+
+  const body = buildPushbackBody(slug, check.missing);
+  log(fmt.status('INFO', `Gatekeeper: posting request-changes pushback on ${fmt.branch(branch)} as ${fmt.agent(user)}. Missing: ${check.missing.join(', ')}.`));
+  const result = postReviewFn(branch, token, 'request-changes', body);
+
+  if (!result || !result.ok) {
+    const detail = result && result.error ? result.error : 'unknown postReview failure';
+    log(fmt.status('WARN', `Gatekeeper: pushback post failed for ${fmt.slug(slug)}: ${detail}.`));
+    return { ok: false, missing: check.missing, skipped: false, posted: false };
+  }
+
+  return { ok: false, missing: check.missing, skipped: false, posted: true };
+}
+
+module.exports = {
+  DEFAULT_GATEKEEPER_USER,
+  checkMandatoryFiles,
+  buildPushbackBody,
+  runGatekeeper
+};

package/lib/tools/sessions.js

@@ -0,0 +1,74 @@
+const fs = require('fs');
+const path = require('path');
+
+// Per-worktree session markers used by startAgent to decide whether to launch
+// an agent fresh or with its family-specific resume flag. Stored under
+// .workflow/sessions/ which is already gitignored, so markers live with the
+// mission worktree and survive harness restarts but never travel through git.
+
+function sessionsDir(worktree) {
+  return path.join(worktree, '.workflow', 'sessions');
+}
+
+function sessionFile(worktree, slug, role) {
+  return path.join(sessionsDir(worktree), `${slug}-${role}.json`);
+}
+
+function readSession(worktree, slug, role) {
+  if (!worktree || !slug || !role) return null;
+  const file = sessionFile(worktree, slug, role);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed && typeof parsed.agent === 'string') return parsed;
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeSession(worktree, slug, role, payload) {
+  if (!worktree || !slug || !role || !payload || typeof payload.agent !== 'string') {
+    return false;
+  }
+  fs.mkdirSync(sessionsDir(worktree), { recursive: true });
+  const body = {
+    agent: payload.agent,
+    lastLaunched: payload.lastLaunched || new Date().toISOString(),
+    sessionId: payload.sessionId || null
+  };
+  fs.writeFileSync(sessionFile(worktree, slug, role), JSON.stringify(body, null, 2) + '\n', 'utf8');
+  return true;
+}
+
+// Resume only when the previous launch in this (slug, role) used the same
+// agent family. A fallback to a different family invalidates the marker —
+// the new family has no prior session to continue.
+function shouldResume(worktree, slug, role, agent) {
+  const prev = readSession(worktree, slug, role);
+  return Boolean(prev && prev.agent === agent);
+}
+
+// Return the session ID from the marker, if one was persisted.
+function getSessionId(worktree, slug, role) {
+  const prev = readSession(worktree, slug, role);
+  return prev && prev.sessionId ? prev.sessionId : null;
+}
+
+function clearSession(worktree, slug, role) {
+  if (!worktree || !slug || !role) return false;
+  const file = sessionFile(worktree, slug, role);
+  if (!fs.existsSync(file)) return false;
+  fs.unlinkSync(file);
+  return true;
+}
+
+module.exports = {
+  sessionsDir,
+  sessionFile,
+  readSession,
+  writeSession,
+  shouldResume,
+  getSessionId,
+  clearSession
+};