@magnusekdahl/parallix 1.0.0

package/lib/commands/repair-handoff.js

@@ -0,0 +1,227 @@
+const path = require('path');
+const { git } = require('../core/git');
+const missionUtils = require('../core/mission-utils');
+const rebase = require('./rebase');
+const fmt = require('../core/fmt');
+
+/**
+ * Check if an error message indicates a relaunchable content error (missing/empty goal-check table).
+ *
+ * @param {string} errorMsg - The error message to check
+ * @returns {boolean} True if the error is relaunchable
+ */
+function isRelaunchableError(errorMsg) {
+  if (!errorMsg || typeof errorMsg !== 'string') {
+    return false;
+  }
+  // Match the exact error message from handoff.js when final checkpoint has no evidence rows
+  return errorMsg.includes('has a "## Goal Check" section but no evidence rows') &&
+         errorMsg.includes('A goal-check table with real evidence is required before handoff');
+}
+
+/**
+ * Build a relaunch prompt for an agent to fix a relaunchable error.
+ *
+ * @param {string} errorMsg - The error message from the failed handoff
+ * @param {string} slug - Mission slug
+ * @param {string} worktree - Path to the mission worktree
+ * @returns {string} The relaunch prompt
+ */
+function buildRelaunchPrompt(errorMsg, slug, worktree) {
+  const year = missionUtils.getMissionYear(slug, worktree);
+  const missionDir = missionUtils.findMissionDir(slug, worktree) || missionUtils.missionDirForSlug(worktree, slug);
+  
+  return `Automated handoff failed for mission ${slug} with a repairable error: ${errorMsg}
+
+` +
+         `Please fix the final checkpoint document in ${missionDir} by adding a Goal Check table ` +
+         `with real evidence rows (file:line references, test names). The Goal Check table must have ` +
+         `a header row and at least one evidence row using pipe syntax (|).
+
+` +
+         `Steps:
+` +
+         `1. Open the final checkpoint document (CP-N.md) in ${missionDir}
+` +
+         `2. Add or update the "## Goal Check" section
+` +
+         `3. Create a markdown table with columns for: Goal Check description | Evidence | Status
+` +
+         `4. Add at least one evidence row with real file:line or test name references
+` +
+         `5. Commit the updated checkpoint with a descriptive commit message
+` +
+         `6. Re-run: node parallix review ${slug} --submit
+
+` +
+         `Example Goal Check table:
+` +
+         `| Goal Check | Evidence | Status |
+` +
+         `|---|---|---|
+` +
+         `| Final checkpoint has Goal Check section | docs/missions/${year}/${slug}/CP-1.md:15 | PASS |
+` +
+         `| Tests pass | npm test -- parallix/test/repair-handoff.test.js | PASS |
+
+` +
+         `Do NOT add placeholder or generic evidence. Each row must cite real, verifiable artifacts.`;
+}
+
+/**
+ * Attempt to repair a failed automated handoff by auto-committing mission
+ * artifacts or rebasing.
+ *
+ * @param {string} slug - Mission slug
+ * @param {string} worktree - Path to the mission worktree
+ * @param {string} errorMsg - The error message from the failed handoff
+ * @param {object} [options]
+ * @returns {Promise<{repaired: boolean, blocker: string|null}>} Result and optional blocker reason
+ */
+async function repairHandoff(slug, worktree, errorMsg, options = {}) {
+  const {
+    taskFile = null,
+    gitFn = git,
+    rebaseFn = rebase,
+    log = fmt.log.plain,
+    error = fmt.log.plainError
+  } = options;
+
+  const rootDir = worktree || process.cwd();
+  let repaired = false;
+  let blocker = null;
+
+  function parsePorcelainPath(line) {
+    const xy = line.slice(0, 2);
+    const rawPath = line.slice(3).trim();
+    const pathPart = rawPath.includes('->') ? rawPath.split('->').pop().trim() : rawPath;
+    const cleanPath = (pathPart.startsWith('"') && pathPart.endsWith('"')) ? pathPart.slice(1, -1) : pathPart;
+    return { xy, file: cleanPath };
+  }
+
+  // 0. Check if error is repairable
+  const isDirtyError = errorMsg && (
+    errorMsg.includes('is modified but uncommitted') ||
+    errorMsg.includes('Commit the mission contract before handoff') ||
+    errorMsg.includes('Commit the implementation evidence before handoff')
+  );
+
+  const isBehind = errorMsg && (
+    errorMsg.includes('Updates were rejected') || 
+    errorMsg.includes('fetch first') || 
+    errorMsg.includes('non-fast-forward') ||
+    errorMsg.includes('behind its remote') ||
+    // Ensure we don't match generic git push failed unless it has non-fast-forward hints
+    (errorMsg.includes('git push failed') && (
+      errorMsg.includes('rejected') || 
+      errorMsg.includes('remote contains work')
+    ))
+  );
+
+  if (!isDirtyError && !isBehind) {
+    log(`Handoff error is not automatically repairable: ${errorMsg}`);
+    return { repaired: false, blocker: null };
+  }
+
+  // 1. Auto-commit mission artifacts if uncommitted
+  if (isDirtyError || isBehind) {
+    const statusResult = gitFn(['-C', rootDir, 'status', '--porcelain']);
+    if (statusResult.status === 0 && statusResult.stdout) {
+      const dirtyLines = statusResult.stdout.split('\n')
+        .filter(line => line.trim().length > 0);
+
+      const dirtyFilesWithStatus = dirtyLines.map(parsePorcelainPath);
+
+      const unmerged = dirtyFilesWithStatus.filter(f => 
+        ['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'].includes(f.xy)
+      );
+
+      if (unmerged.length > 0) {
+        blocker = `Conflicted files detected:\n${unmerged.map(f => `       - ${f.file}`).join('\n')}`;
+        log(`Cannot auto-commit: ${blocker}`);
+        return { repaired: false, blocker };
+      }
+
+      const dirtyFiles = dirtyFilesWithStatus.map(f => f.file);
+
+      const isSafeToCommit = (file) =>
+        missionUtils.isWorkflowGeneratedArtifact(file)
+        || missionUtils.isMissionArtifact(file, slug, rootDir);
+
+      const safeFiles = dirtyFiles.filter(isSafeToCommit);
+      const unsafeFiles = dirtyFiles.filter(f => !isSafeToCommit(f));
+
+      if (unsafeFiles.length > 0) {
+        log(`Cannot auto-commit: dirty files include non-mission paths:`);
+        unsafeFiles.forEach(f => log(`       - ${f}`));
+        blocker = `dirty files include non-mission paths: ${unsafeFiles.join(', ')}`;
+        return { repaired: false, blocker };
+      } else if (safeFiles.length > 0) {
+        log(`Auto-committing mission artifacts:`);
+        const stageFailures = [];
+        safeFiles.forEach(f => {
+          log(`       - ${f}`);
+          const addResult = gitFn(['-C', rootDir, 'add', '--', f]);
+          if (addResult.status === 0) {
+            return;
+          } else {
+            const failureText = [addResult.stderr, addResult.stdout].filter(Boolean).join('\n').trim();
+            stageFailures.push(`${f}${failureText ? `: ${failureText}` : ''}`);
+          }
+        });
+        if (stageFailures.length > 0) {
+          blocker = `failed to stage mission artifacts: ${stageFailures.join(', ')}`;
+          error(fmt.status('FAIL', blocker));
+          return { repaired: false, blocker };
+        }
+        const commitRes = gitFn(['-C', rootDir, 'commit', '-m', `workflow(${slug}): auto-commit mission artifacts before handoff`]);
+        if (commitRes.status === 0) {
+          log(fmt.status('PASS', 'Mission artifacts committed.'));
+          repaired = true;
+        } else {
+          error(fmt.status('WARN', `Failed to commit mission artifacts: ${commitRes.stderr}`));
+          blocker = `failed to commit mission artifacts: ${commitRes.stderr}`;
+          return { repaired: false, blocker };
+        }
+      }
+    }
+  }
+
+  // 2. Auto-rebase if branch is behind
+  if (isBehind) {
+    log('Branch appears behind primary branch. Calling rebase...');
+    let rebaseSuccess = false;
+    let rebaseError = null;
+    try {
+      const { getCurrentBranch } = require('../core/git');
+      await rebaseFn([slug], {
+        gitFn: (args, opts) => gitFn(args, { ...opts, cwd: rootDir }),
+        getCurrentBranchFn: () => getCurrentBranch(rootDir),
+        exitFn: (code) => {
+          if (code === 0) {
+            rebaseSuccess = true;
+          } else {
+            rebaseError = `rebase exited with code ${code}`;
+          }
+        }
+      });
+    } catch (err) {
+      rebaseError = err.message;
+    }
+
+    if (!rebaseSuccess) {
+      const msg = rebaseError || 'unknown rebase failure';
+      error(fmt.status('WARN', `Auto-rebase failed: ${msg}`));
+      blocker = `Auto-rebase failed: ${msg}`;
+      repaired = false; // Reset repaired if rebase fails, even if auto-commit succeeded
+    } else {
+      repaired = true;
+    }
+  }
+
+  return { repaired, blocker };
+}
+
+module.exports = repairHandoff;
+module.exports.isRelaunchableError = isRelaunchableError;
+module.exports.buildRelaunchPrompt = buildRelaunchPrompt;

package/lib/commands/resolve-conflict.js

@@ -0,0 +1,109 @@
+const { resolveConflictsForMission } = require('./integrate');
+const { findMissionDir, findMissionArea, inferSlug, getPrimaryBranch } = require('../core/mission-utils');
+const { startAgent } = require('../agents/agents');
+const fmt = require('../core/fmt');
+const { formatVerificationCommand } = require('../core/verification');
+
+function shellQuote(value) {
+  return `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+function buildAgentResolutionPrompt({ slug, area, worktreePath, missionSpecificFiles }) {
+  const fileCommands = missionSpecificFiles
+    .map(f => `  git checkout --theirs "${f}" && git add "${f}"`)
+    .join('\n');
+  const quotedWorktreePath = shellQuote(worktreePath);
+
+  return [
+    'Mode: conflict-resolution.',
+    '',
+    `Mission: ${slug}`,
+    `Mission worktree: ${worktreePath}`,
+    '',
+    `Conflicts detected between the mission branch and ${getPrimaryBranch()}.`,
+    'All conflicts are in mission-specific files that can be resolved by keeping',
+    'the mission branch version (--theirs). Execute these steps in order:',
+    '',
+    `  cd ${quotedWorktreePath}`,
+    `  git rebase ${getPrimaryBranch()}`,
+    '  # When the rebase pauses on conflicts, run for each file:',
+    fileCommands,
+    '  git rebase --continue',
+    `  ${formatVerificationCommand(area, worktreePath)}`,
+    `  px integrate ${slug} --dry-run`,
+    '',
+    'Rules:',
+    '- Take --theirs for every file listed above. Do not inspect or edit conflict content.',
+    '- If the rebase pauses on a file NOT in the list above, stop immediately and',
+    '  report the unexpected file. Do not guess the resolution.',
+    '- If any command fails, stop immediately and report the failure.',
+    '  Do not continue to the next step.',
+  ].join('\n');
+}
+
+async function resolveConflict(args, {
+  resolveConflictsFn = resolveConflictsForMission,
+  startAgentFn = startAgent,
+  exitFn = (code) => process.exit(code),
+} = {}) {
+  const explicitSlug = args[0];
+  const slug = inferSlug(explicitSlug);
+  if (!slug) {
+    fmt.log.fail('Usage: px resolve-conflict [<slug>]');
+    exitFn(1);
+    return;
+  }
+
+  const missionDir = findMissionDir(slug);
+  const area = missionDir ? findMissionArea(missionDir) : 'docs';
+
+  const result = resolveConflictsFn(slug, area);
+
+  // No conflicts — nothing to resolve.
+  if (result.ok && result.conflictFiles.length === 0) {
+    exitFn(0);
+    return;
+  }
+
+  // Shared-file conflicts: the agent cannot guess the correct resolution.
+  // Stop and require human intervention.
+  if (!result.ok && result.error === 'shared-file-conflicts') {
+    fmt.log.fail('Shared-file conflicts require human resolution. Agent cannot guess the correct merge outcome.');
+    fmt.log.info(`Shared files: ${result.sharedFiles.map(f => fmt.path(f)).join(', ')}`);
+    fmt.log.info(`Resolve manually, then re-run: ${fmt.command(`px integrate ${slug} --dry-run`)}`);
+    exitFn(1);
+    return;
+  }
+
+  // Other errors (worktree missing, merge-failed, etc.) — already logged by resolveConflictsFn.
+  if (!result.ok) {
+    exitFn(1);
+    return;
+  }
+
+  // All conflicts are mission-specific: launch an agent to execute the --theirs rebase.
+  const prompt = buildAgentResolutionPrompt({
+    slug,
+    area,
+    worktreePath: result.worktreePath,
+    missionSpecificFiles: result.missionSpecificFiles,
+  });
+
+  fmt.log.info('Launching agent to execute mission-specific conflict resolution...');
+  const { agent, result: agentResult } = await startAgentFn('conflict-resolution', {
+    prompt,
+    worktree: result.worktreePath,
+  });
+
+  if (agentResult.status !== 0) {
+    fmt.log.fail(`Agent (${fmt.agent(agent)}) exited with status ${agentResult.status}.`);
+    exitFn(agentResult.status || 1);
+    return;
+  }
+
+  fmt.log.pass(`Agent (${fmt.agent(agent)}) completed conflict resolution.`);
+  exitFn(0);
+}
+
+module.exports = resolveConflict;
+module.exports.buildAgentResolutionPrompt = buildAgentResolutionPrompt;

package/lib/commands/review.js

@@ -0,0 +1,13 @@
+const review = require('../review/review-commands').review;
+
+/**
+ * Workflow command entry point for `review`.
+ * Delegates to the review subsystem (review-commands.js).
+ *
+ * Usage: node parallix review [<slug>] [--verify] [--submit] [--push] ...
+ */
+async function reviewCommand(args) {
+  await review(args);
+}
+
+module.exports = reviewCommand;

package/lib/commands/setup-review.js

@@ -0,0 +1,13 @@
+const setupReview = require('../tools/setup-review');
+
+/**
+ * Workflow command entry point for `setup-review`.
+ * Delegates to the Forgejo bootstrap tool (tools/setup-review.js).
+ *
+ * Usage: node parallix setup-review
+ */
+async function setupReviewCommand(args, options) {
+  await setupReview(args, options);
+}
+
+module.exports = setupReviewCommand;

package/lib/commands/setup.js

@@ -0,0 +1,3 @@
+const { setupWizard } = require('../tools/setup-review');
+
+module.exports = setupWizard;