@imdeadpool/guardex 7.0.43 → 7.1.0

package/src/pr-review.js

@@ -153,6 +153,12 @@ function runProviderReview(provider, diff, repoRoot, timeoutMs, runner = run) {
   if (result.status !== 0) {
     throw new Error(`${provider} review failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
   }
+  // A compliant provider always emits the findings JSON object (empty array when
+  // nothing is wrong). Empty stdout means the review did NOT run — fail closed so
+  // a silent no-op is never mistaken for "clean" by the merge gate.
+  if (!(result.stdout || '').trim()) {
+    throw new Error(`${provider} review returned no output (review did not run)`);
+  }
   return normalizeFindings(result.stdout || '');
 }
 
@@ -218,6 +224,22 @@ function runPrReview(options, deps = {}) {
   return { posted: true, artifactPath: '', findings };
 }
 
+/**
+ * Decide whether a set of review findings clears the merge gate. Blocks on any
+ * finding whose severity is in `blockSeverities` (high + critical by default;
+ * low/medium are advisory). Pure + synchronous so it is trivially testable.
+ *
+ * Fail-closed semantics live in the CALLER: an absent/empty `findings` here is
+ * treated as clean, so the caller must independently treat a review that did
+ * NOT run (provider threw / timed out) as a block, never as clean.
+ */
+function evaluateReviewGate(findings, { blockSeverities = ['high', 'critical'] } = {}) {
+  const block = new Set(blockSeverities.map((s) => String(s).toLowerCase()));
+  const list = Array.isArray(findings) ? findings : [];
+  const blocking = list.filter((f) => f && block.has(String(f.severity).toLowerCase()));
+  return { clean: blocking.length === 0, blocking };
+}
+
 function printPrReviewResult(result) {
   if (result.posted) {
     console.log(`${TOOL_PREFIX} Posted PR review with ${result.findings.length} finding(s).`);
@@ -237,5 +259,6 @@ module.exports = {
   normalizeFindings,
   renderMarkdownReview,
   runPrReview,
+  evaluateReviewGate,
   printPrReviewResult,
 };

package/src/pr.js

@@ -0,0 +1,381 @@
+// PR-from-worktree helpers.
+//
+// Centralizes the operations that the agent + worktree flow needs to drive a
+// pull request: detecting the PR for the current branch, opening one
+// idempotently, pushing + syncing, enabling auto-merge, and polling CI / merge
+// state. The agent-branch-finish.sh script historically owned most of this;
+// these helpers expose the same primitives to the JS CLI so `gx pr ...` can be
+// driven without invoking the shell flow.
+
+const { GH_BIN } = require('./context');
+const { run } = require('./core/runtime');
+const {
+  resolveRepoRoot,
+  currentBranchName,
+  hasOriginRemote,
+  detectDefaultBaseBranch,
+} = require('./git');
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+
+class PrError extends Error {
+  constructor(message, { code = 'pr-error', cause = null } = {}) {
+    super(message);
+    this.name = 'PrError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+function ghAvailable() {
+  const result = run(GH_BIN, ['--version'], { allowFailure: true });
+  return result.status === 0;
+}
+
+function ghAuthStatus() {
+  const result = run(GH_BIN, ['auth', 'status'], { allowFailure: true });
+  return {
+    authenticated: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+function ghJson(repoRoot, args) {
+  const result = run(GH_BIN, args, { cwd: repoRoot, allowFailure: true });
+  if (result.status !== 0) {
+    return { ok: false, error: (result.stderr || result.stdout || '').trim(), data: null };
+  }
+  const raw = (result.stdout || '').trim();
+  if (!raw) return { ok: true, data: null, error: null };
+  try {
+    return { ok: true, data: JSON.parse(raw), error: null };
+  } catch (error) {
+    return { ok: false, data: null, error: `gh JSON parse: ${error.message}` };
+  }
+}
+
+/**
+ * Resolve the PR for `branch` if any exists on the origin remote.
+ * Returns null when no PR is open (or any are merged / closed only).
+ */
+function findOpenPrForBranch(repoRoot, branch) {
+  const result = ghJson(repoRoot, [
+    'pr', 'list',
+    '--head', branch,
+    '--state', 'open',
+    '--json', 'number,url,state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,title,statusCheckRollup',
+    '--limit', '5',
+  ]);
+  if (!result.ok) {
+    throw new PrError(`gh pr list failed: ${result.error}`, { code: 'gh-list-failed' });
+  }
+  const items = Array.isArray(result.data) ? result.data : [];
+  if (items.length === 0) return null;
+  return items[0];
+}
+
+/**
+ * Resolve the most recent PR for `branch` regardless of state. Useful when
+ * the agent has already merged a previous PR for this branch.
+ */
+function findLatestPrForBranch(repoRoot, branch) {
+  const result = ghJson(repoRoot, [
+    'pr', 'list',
+    '--head', branch,
+    '--state', 'all',
+    '--json', 'number,url,state,isDraft,mergedAt,headRefName,baseRefName,title',
+    '--limit', '5',
+  ]);
+  if (!result.ok) {
+    throw new PrError(`gh pr list failed: ${result.error}`, { code: 'gh-list-failed' });
+  }
+  const items = Array.isArray(result.data) ? result.data : [];
+  if (items.length === 0) return null;
+  return items[0];
+}
+
+/**
+ * List ALL open PRs for the repo on origin in a single gh call, so callers can
+ * correlate many branches to their PRs without one gh round-trip per branch.
+ * Best-effort: never throws. Returns `{ prs, error }` so callers can tell a
+ * genuine "no open PRs" (`error: null`) from a failed lookup (gh missing /
+ * unauthenticated / offline → `error` set, `prs: []`).
+ * NB: `limit` (default 100) bounds correlation COVERAGE, not just payload size —
+ * a repo with more than `limit` open PRs may leave some lanes showing pr:null.
+ */
+function listOpenPrsForRepo(repoRoot, { limit = 100 } = {}) {
+  const result = ghJson(repoRoot, [
+    'pr', 'list',
+    '--state', 'open',
+    '--json', 'number,url,state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,title',
+    '--limit', String(limit),
+  ]);
+  if (!result.ok) return { prs: [], error: result.error || 'gh pr list failed' };
+  if (!Array.isArray(result.data)) return { prs: [], error: null };
+  return { prs: result.data, error: null };
+}
+
+function pushBranch(repoRoot, branch, { setUpstream = true } = {}) {
+  const args = ['push'];
+  if (setUpstream) args.push('-u');
+  args.push('origin', branch);
+  const result = run('git', args, { cwd: repoRoot, allowFailure: true });
+  return {
+    ok: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+function defaultPrTitleFromCommit(repoRoot, branch) {
+  const result = run('git', ['log', '-1', '--pretty=%s', branch], {
+    cwd: repoRoot, allowFailure: true,
+  });
+  if (result.status !== 0) return branch;
+  const subject = (result.stdout || '').trim();
+  return subject || branch;
+}
+
+function defaultPrBodyFromCommits(repoRoot, branch, baseBranch) {
+  const result = run('git', [
+    'log',
+    `${baseBranch}..${branch}`,
+    '--pretty=format:- %s',
+  ], { cwd: repoRoot, allowFailure: true });
+  const list = (result.stdout || '').trim();
+  return [
+    '## Summary',
+    list || '- (no commits between base and branch yet)',
+    '',
+    '## Test plan',
+    '- [ ] verified locally',
+  ].join('\n');
+}
+
+/**
+ * Create (or fetch existing) PR for the current worktree branch. Idempotent:
+ * if an open PR is already associated with the branch, returns it without
+ * creating a duplicate.
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot
+ * @param {string} options.branch
+ * @param {string} [options.base]
+ * @param {string} [options.title]
+ * @param {string} [options.body]
+ * @param {boolean} [options.draft]
+ * @param {boolean} [options.push]
+ */
+function openPullRequest(options) {
+  const repoRoot = options.repoRoot;
+  const branch = options.branch;
+  if (!repoRoot) throw new PrError('repoRoot required', { code: 'bad-arg' });
+  if (!branch) throw new PrError('branch required', { code: 'bad-arg' });
+
+  if (!ghAvailable()) {
+    throw new PrError('gh CLI not installed. Install from https://cli.github.com/', {
+      code: 'gh-missing',
+    });
+  }
+  const auth = ghAuthStatus();
+  if (!auth.authenticated) {
+    throw new PrError(
+      `GitHub CLI is not authenticated. Run 'gh auth login' or set GITHUB_TOKEN.\n${auth.output}`,
+      { code: 'gh-unauthenticated' },
+    );
+  }
+  if (!hasOriginRemote(repoRoot)) {
+    throw new PrError('No `origin` remote configured for this repo', {
+      code: 'no-origin',
+    });
+  }
+
+  // Try to find an existing open PR first.
+  const existing = findOpenPrForBranch(repoRoot, branch);
+  if (existing) {
+    return { created: false, pr: existing };
+  }
+
+  if (options.push !== false) {
+    const push = pushBranch(repoRoot, branch);
+    if (!push.ok) {
+      throw new PrError(`git push failed:\n${push.output}`, { code: 'push-failed' });
+    }
+  }
+
+  const base = options.base || detectDefaultBaseBranch(repoRoot);
+  const title = options.title || defaultPrTitleFromCommit(repoRoot, branch);
+  const body = options.body || defaultPrBodyFromCommits(repoRoot, branch, base);
+
+  const args = [
+    'pr', 'create',
+    '--base', base,
+    '--head', branch,
+    '--title', title,
+    '--body', body,
+  ];
+  if (options.draft !== false) args.push('--draft');
+
+  const result = run(GH_BIN, args, { cwd: repoRoot, allowFailure: true });
+  if (result.status !== 0) {
+    throw new PrError(
+      `gh pr create failed:\n${(result.stderr || result.stdout || '').trim()}`,
+      { code: 'gh-create-failed' },
+    );
+  }
+
+  const created = findOpenPrForBranch(repoRoot, branch);
+  if (!created) {
+    throw new PrError('PR appears to have been created but could not be located on origin', {
+      code: 'pr-lookup-failed',
+    });
+  }
+  return { created: true, pr: created };
+}
+
+/**
+ * Fetch the live status of the PR for `branch`. Returns null when no open PR
+ * exists. Status checks are summarized.
+ */
+function getPullRequestStatus(repoRoot, branch) {
+  const pr = findOpenPrForBranch(repoRoot, branch);
+  if (!pr) return null;
+
+  const checks = Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : [];
+  const summary = checks.reduce(
+    (acc, check) => {
+      const state = String(check?.conclusion || check?.status || '').toUpperCase();
+      if (state === 'SUCCESS') acc.success += 1;
+      else if (state === 'FAILURE' || state === 'ERROR' || state === 'TIMED_OUT') acc.failed += 1;
+      else if (state === 'PENDING' || state === 'IN_PROGRESS' || state === 'QUEUED') acc.pending += 1;
+      else if (state === 'CANCELLED') acc.cancelled += 1;
+      else acc.other += 1;
+      return acc;
+    },
+    { success: 0, failed: 0, pending: 0, cancelled: 0, other: 0, total: checks.length },
+  );
+
+  return {
+    number: pr.number,
+    url: pr.url,
+    state: pr.state,
+    isDraft: pr.isDraft,
+    mergeable: pr.mergeable,
+    mergeStateStatus: pr.mergeStateStatus,
+    reviewDecision: pr.reviewDecision,
+    title: pr.title,
+    head: pr.headRefName,
+    base: pr.baseRefName,
+    checks: summary,
+  };
+}
+
+function enableAutoMerge(repoRoot, prNumber, { strategy = 'squash' } = {}) {
+  const flag = strategy === 'merge'
+    ? '--merge'
+    : strategy === 'rebase' ? '--rebase' : '--squash';
+  const result = run(GH_BIN, [
+    'pr', 'merge', String(prNumber),
+    '--auto', flag, '--delete-branch',
+  ], { cwd: repoRoot, allowFailure: true });
+  return {
+    ok: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+function markPullRequestReady(repoRoot, prNumber) {
+  const result = run(GH_BIN, ['pr', 'ready', String(prNumber)], {
+    cwd: repoRoot, allowFailure: true,
+  });
+  return {
+    ok: result.status === 0,
+    output: ((result.stdout || '') + (result.stderr || '')).trim(),
+  };
+}
+
+/**
+ * Watch a PR's CI + merge state until it merges, fails, or times out.
+ *
+ * Returns a structured result; does not throw on non-success states. Used by
+ * `gx pr watch`. `onEvent` is called for every poll tick with the current
+ * status snapshot, so callers can render progress.
+ */
+async function watchPullRequest(options) {
+  const {
+    repoRoot,
+    branch,
+    intervalMs = DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+    onEvent = () => {},
+  } = options;
+
+  const deadline = Date.now() + timeoutMs;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    // Check open PRs first.
+    const open = findOpenPrForBranch(repoRoot, branch);
+    if (!open) {
+      const latest = findLatestPrForBranch(repoRoot, branch);
+      if (latest && latest.state === 'MERGED') {
+        onEvent({ phase: 'merged', pr: latest });
+        return { status: 'merged', pr: latest };
+      }
+      if (latest && latest.state === 'CLOSED') {
+        onEvent({ phase: 'closed', pr: latest });
+        return { status: 'closed', pr: latest };
+      }
+      onEvent({ phase: 'no-pr', pr: null });
+      return { status: 'no-pr', pr: null };
+    }
+
+    const snapshot = getPullRequestStatus(repoRoot, branch);
+    onEvent({ phase: 'polling', pr: snapshot });
+
+    if (snapshot && snapshot.checks.failed > 0) {
+      return { status: 'checks-failed', pr: snapshot };
+    }
+    if (
+      snapshot
+      && !snapshot.isDraft
+      && snapshot.mergeable === 'MERGEABLE'
+      && snapshot.checks.pending === 0
+      && snapshot.checks.failed === 0
+      && snapshot.checks.total > 0
+    ) {
+      // CI is green and PR is non-draft + mergeable; the merge itself will be
+      // driven by auto-merge or a separate `gh pr merge` invocation.
+      onEvent({ phase: 'ready', pr: snapshot });
+    }
+
+    if (Date.now() >= deadline) {
+      return { status: 'timeout', pr: snapshot };
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+function resolveRepoAndBranch(target) {
+  const repoRoot = resolveRepoRoot(target || process.cwd());
+  const branch = currentBranchName(repoRoot);
+  return { repoRoot, branch };
+}
+
+module.exports = {
+  PrError,
+  ghAvailable,
+  ghAuthStatus,
+  findOpenPrForBranch,
+  findLatestPrForBranch,
+  listOpenPrsForRepo,
+  pushBranch,
+  openPullRequest,
+  getPullRequestStatus,
+  enableAutoMerge,
+  markPullRequestReady,
+  watchPullRequest,
+  resolveRepoAndBranch,
+  defaultPrTitleFromCommit,
+  defaultPrBodyFromCommits,
+};

package/src/sandbox/index.js

@@ -13,6 +13,14 @@ const {
   gitRefExists,
   ensureRepoBranch,
 } = require('../git');
+const { prepareAgentWorktree } = require('../scaffold/agent-worktree-prep');
+
+function formatWorktreePrepOps(operations) {
+  if (!operations || operations.length === 0) return '';
+  return operations
+    .map((op) => `[agent-branch-start] worktree-prep ${op.status} ${op.file}${op.note ? ' — ' + op.note : ''}`)
+    .join('\n') + '\n';
+}
 
 function hasGuardexBootstrapFiles(repoRoot) {
   const required = [
@@ -195,6 +203,7 @@ function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
     }
   }
 
+  const prepOps = prepareAgentWorktree(blocked.repoRoot, selectedWorktreePath);
   return {
     metadata: {
       branch: selectedBranch,
@@ -202,7 +211,8 @@ function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
     },
     stdout:
       `[agent-branch-start] Created branch: ${selectedBranch}\n` +
-      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n`,
+      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n` +
+      formatWorktreePrepOps(prepOps),
     stderr: addResult.stderr || '',
   };
 }
@@ -246,9 +256,10 @@ function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
     return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
+  const prepOps = prepareAgentWorktree(blocked.repoRoot, worktreePath);
   return {
     metadata,
-    stdout: startResult.stdout || '',
+    stdout: (startResult.stdout || '') + formatWorktreePrepOps(prepOps),
     stderr: startResult.stderr || '',
   };
 }

package/src/scaffold/agent-worktree-prep.js

@@ -0,0 +1,213 @@
+'use strict';
+
+// Prepares a freshly-created agent worktree for monorepos that have `apps/*`
+// packages. Two jobs:
+//
+//   1. Symlink the root's `apps/<pkg>/.env` (and friends) into the worktree
+//      so backend / storefront / etc. can boot with the same secrets without
+//      asking the user to copy gitignored env files manually.
+//
+//   2. Pick a free port per app and write it into the worktree's
+//      `apps/<pkg>/.env.local` (which both Vite and Medusa's loadEnv read with
+//      higher precedence than `.env`). This stops agent dev servers from
+//      colliding with whatever's running in the root worktree on the default
+//      port.
+//
+// Both jobs are best-effort: if `apps/` doesn't exist, or there are no env
+// files / no package.json in a subfolder, we silently skip — non-monorepo
+// repos see no change.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ENV_FILE_CANDIDATES = [
+  '.env',
+  '.env.local',
+  '.env.development',
+  '.env.development.local',
+  '.env.production',
+  '.env.production.local',
+];
+
+// Port pool by detected app role. Storefronts get the Vite/Next range,
+// backends get the Medusa range, everything else gets a generic mid-range.
+const PORT_POOLS = {
+  storefront: 5174,
+  backend: 9101,
+  default: 8100,
+};
+
+function detectAppPackages(repoRoot) {
+  const appsRoot = path.join(repoRoot, 'apps');
+  let stat;
+  try {
+    stat = fs.statSync(appsRoot);
+  } catch {
+    return [];
+  }
+  if (!stat.isDirectory()) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(appsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => fs.existsSync(path.join(appsRoot, name, 'package.json')));
+}
+
+function inferAppRole(appName) {
+  const n = appName.toLowerCase();
+  if (n.includes('storefront') || n.includes('frontend') || n.includes('web')) {
+    return 'storefront';
+  }
+  if (n.includes('backend') || n.includes('api') || n.includes('server')) {
+    return 'backend';
+  }
+  return 'default';
+}
+
+function isPortFree(port) {
+  // Use `lsof` if available — it's on macOS and most Linux distros. Fall
+  // back to assuming free when lsof isn't installed (e.g. minimal Alpine
+  // CI image); the dev server will fail loudly if it isn't.
+  const probe = spawnSync('lsof', ['-iTCP:' + port, '-sTCP:LISTEN', '-t'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 2000,
+  });
+  if (probe.error) return true;
+  const out = (probe.stdout && probe.stdout.toString().trim()) || '';
+  return out === '';
+}
+
+function pickFreePort(start) {
+  for (let p = start; p < start + 200; p++) {
+    if (isPortFree(p)) return p;
+  }
+  return null;
+}
+
+function symlinkAppEnvFiles(repoRoot, worktreePath, appName) {
+  const operations = [];
+  const rootAppDir = path.join(repoRoot, 'apps', appName);
+  const wtAppDir = path.join(worktreePath, 'apps', appName);
+  if (!fs.existsSync(wtAppDir)) {
+    return operations;
+  }
+  for (const candidate of ENV_FILE_CANDIDATES) {
+    const rootEnv = path.join(rootAppDir, candidate);
+    const wtEnv = path.join(wtAppDir, candidate);
+    if (!fs.existsSync(rootEnv)) continue;
+    // Don't overwrite an existing file/symlink in the worktree.
+    let alreadyExists = false;
+    try {
+      fs.lstatSync(wtEnv);
+      alreadyExists = true;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+    if (alreadyExists) {
+      operations.push({
+        status: 'unchanged',
+        file: `apps/${appName}/${candidate}`,
+        note: 'already present in worktree',
+      });
+      continue;
+    }
+    try {
+      fs.symlinkSync(rootEnv, wtEnv);
+      operations.push({
+        status: 'linked',
+        file: `apps/${appName}/${candidate}`,
+        note: `→ ${path.relative(worktreePath, rootEnv)}`,
+      });
+    } catch (err) {
+      operations.push({
+        status: 'failed',
+        file: `apps/${appName}/${candidate}`,
+        note: `symlink failed: ${err.message}`,
+      });
+    }
+  }
+  return operations;
+}
+
+function assignAgentPort(repoRoot, worktreePath, appName, takenPorts) {
+  const wtAppDir = path.join(worktreePath, 'apps', appName);
+  if (!fs.existsSync(wtAppDir)) {
+    return { status: 'skipped', file: `apps/${appName}`, note: 'no app dir in worktree' };
+  }
+  const role = inferAppRole(appName);
+  const base = PORT_POOLS[role] || PORT_POOLS.default;
+  let port = pickFreePort(base);
+  // Bump past anything we've already assigned this run.
+  while (port !== null && takenPorts.has(port)) {
+    port = pickFreePort(port + 1);
+  }
+  if (port === null) {
+    return {
+      status: 'failed',
+      file: `apps/${appName}/.env.local`,
+      note: 'no free port found in pool',
+    };
+  }
+  takenPorts.add(port);
+
+  const envLocalPath = path.join(wtAppDir, '.env.local');
+  let existing = '';
+  try {
+    existing = fs.readFileSync(envLocalPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  // If a .env.local already exists, replace the PORT= line if present,
+  // otherwise append. Keep everything else the user might have added.
+  const portLine = `PORT=${port}`;
+  let next;
+  if (/^PORT=/m.test(existing)) {
+    next = existing.replace(/^PORT=.*$/m, portLine);
+  } else {
+    const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+    next = `${existing}${sep}${portLine}\n`;
+    // Header on fresh files so the user knows what wrote this.
+    if (existing.length === 0) {
+      next = `# Written by gitguardex on worktree creation — agent dev server port.\n${portLine}\n`;
+    }
+  }
+  fs.writeFileSync(envLocalPath, next, 'utf8');
+  return {
+    status: 'wrote',
+    file: `apps/${appName}/.env.local`,
+    note: `PORT=${port} (${role} pool)`,
+  };
+}
+
+function prepareAgentWorktree(repoRoot, worktreePath) {
+  if (!repoRoot || !worktreePath) return [];
+  if (repoRoot === worktreePath) return [];
+  if (!fs.existsSync(worktreePath)) return [];
+  const apps = detectAppPackages(repoRoot);
+  if (apps.length === 0) return [];
+
+  const operations = [];
+  const takenPorts = new Set();
+  for (const appName of apps) {
+    operations.push(...symlinkAppEnvFiles(repoRoot, worktreePath, appName));
+    operations.push(assignAgentPort(repoRoot, worktreePath, appName, takenPorts));
+  }
+  return operations;
+}
+
+module.exports = {
+  detectAppPackages,
+  inferAppRole,
+  isPortFree,
+  pickFreePort,
+  symlinkAppEnvFiles,
+  assignAgentPort,
+  prepareAgentWorktree,
+};