forge-workflow 0.0.8 → 0.0.9

package/lib/commands/setup.js

@@ -10,6 +10,7 @@
  */
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const { execSync, execFileSync } = require('node:child_process');
@@ -46,7 +47,11 @@ const { renderSetupSummary } = require('../setup-summary-renderer');
 const { smartMergeAgentsMd } = require('../smart-merge');
 const { checkLefthookStatus } = require('../lefthook-check');
 const { resolveShellRuntime } = require('../runtime-health');
-const { listCodexSkillEntries } = require('../codex-skills');
+const {
+  buildCodexSkillInstallPlan,
+  formatCodexSkillsInstallDir,
+  listCodexSkillEntries,
+} = require('../codex-skills');
 const {
   generateCopilotConfig,
   generateCursorConfig,
@@ -69,6 +74,8 @@ let SYMLINK_ONLY = false;
 let SYNC_ENABLED = false;
 let actionLog = new SetupActionLog();
 let PKG_MANAGER = 'npm';
+let SETUP_NOTES = [];
+let CODEX_SETUP_REPORT = null;
 
 /**
  * Load agent definitions from plugin architecture
@@ -81,7 +88,7 @@ function loadAgentsFromPlugins() {
     agents[id] = {
       name: plugin.name,
       description: plugin.description || '',
-      dirs: Object.values(plugin.directories || {}),
+      dirs: getRepoRelativePluginDirectories(plugin),
       hasCommands: plugin.capabilities?.commands || plugin.setup?.copyCommands || false,
       hasSkill: plugin.capabilities?.skills || plugin.setup?.createSkill || false,
       linkFile: plugin.files?.rootConfig || '',
@@ -95,6 +102,17 @@ function loadAgentsFromPlugins() {
   return agents;
 }
 
+function isRepoRelativePluginPath(candidate) {
+  return typeof candidate === 'string'
+    && candidate.length > 0
+    && !path.isAbsolute(candidate)
+    && !/^[~$%]/.test(candidate);
+}
+
+function getRepoRelativePluginDirectories(plugin) {
+  return Object.values(plugin.directories || {}).filter(isRepoRelativePluginPath);
+}
+
 const AGENTS = loadAgentsFromPlugins();
 Object.freeze(AGENTS);
 Object.values(AGENTS).forEach(agent => Object.freeze(agent));
@@ -187,11 +205,112 @@ function validateAgents(agentList) {
   return valid;
 }
 
+function parseDoltRemoteNames(remoteListOutput) {
+  const output = String(remoteListOutput || '').trim();
+  if (!output || /^No remotes configured\.?$/i.test(output)) {
+    return [];
+  }
+
+  return output
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => line.split(/\s+/)[0])
+    .filter(Boolean);
+}
+
+function readBeadsSyncRemoteConfig(projectDir = projectRoot) {
+  const jsonConfigPath = path.join(projectDir, '.beads', 'config.json');
+  if (fs.existsSync(jsonConfigPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(jsonConfigPath, 'utf8'));
+      if (typeof parsed.sync_remote === 'string' && parsed.sync_remote.trim()) {
+        return parsed.sync_remote.trim();
+      }
+    } catch (_error) {
+      // Ignore malformed config and fall back to other sources.
+    }
+  }
+
+  const yamlConfigPath = path.join(projectDir, '.beads', 'config.yaml');
+  if (fs.existsSync(yamlConfigPath)) {
+    const configuredRemote = parseBeadsYamlSyncRemote(fs.readFileSync(yamlConfigPath, 'utf8'));
+    if (configuredRemote) {
+      return configuredRemote;
+    }
+  }
+
+  return '';
+}
+
+function parseBeadsYamlSyncRemote(content) {
+  for (const rawLine of String(content || '').split(/\r?\n/)) {
+    const trimmedLine = rawLine.trimStart();
+    if (!trimmedLine.startsWith('sync-remote:')) {
+      continue;
+    }
+
+    const rawValue = trimmedLine.slice('sync-remote:'.length).trim();
+    if (!rawValue) {
+      return '';
+    }
+
+    const quote = rawValue[0];
+    if ((quote === '"' || quote === '\'') && rawValue.length > 1) {
+      const closingQuoteIndex = rawValue.indexOf(quote, 1);
+      if (closingQuoteIndex > 1) {
+        return rawValue.slice(1, closingQuoteIndex).trim();
+      }
+    }
+
+    const commentIndex = rawValue.indexOf('#');
+    const unquotedValue = commentIndex === -1 ? rawValue : rawValue.slice(0, commentIndex);
+    return unquotedValue.trim();
+  }
+
+  return '';
+}
+
+function resolveExpectedBeadsRemote(options = {}) {
+  const projectDir = options.projectDir || projectRoot;
+  const env = options.env || process.env;
+  const configuredRemote = readBeadsSyncRemoteConfig(projectDir);
+  if (configuredRemote) {
+    return configuredRemote;
+  }
+
+  if (typeof env.BD_SYNC_REMOTE === 'string' && env.BD_SYNC_REMOTE.trim()) {
+    return env.BD_SYNC_REMOTE.trim();
+  }
+
+  const gitRemoteProbe = options.gitRemoteProbe
+    || ((remoteName) => safeExec(`git -C "${projectDir}" remote get-url ${remoteName}`));
+  if (gitRemoteProbe('upstream')) {
+    return 'upstream';
+  }
+
+  return 'origin';
+}
+
+function hasBeadsDoltRemote(commandRunner, remoteName = 'origin') {
+  const output = commandRunner('bd dolt remote list');
+  if (!output) {
+    return null;
+  }
+
+  return parseDoltRemoteNames(output).includes(remoteName);
+}
+
 // Prerequisite check function
 function checkPrerequisites(options = {}) {
   const requireGithubCli = options.requireGithubCli !== false;
   const requireBeadsCli = options.requireBeadsCli === true;
   const requireJq = options.requireJq === true;
+  const expectedBeadsRemote = options.expectedBeadsRemote || resolveExpectedBeadsRemote({
+    env: options.env,
+    gitRemoteProbe: options.gitRemoteProbe,
+    projectDir: options.projectDir,
+  });
   const commandRunner = options.commandRunner || safeExec;
   const errors = [];
   const warnings = [];
@@ -230,6 +349,20 @@ function checkPrerequisites(options = {}) {
   const bdVersion = commandRunner('bd --version');
   if (bdVersion) {
     console.log(`  ✓ ${bdVersion.split('\n')[0]}`);
+    if (requireBeadsCli) {
+      const hasRemote = hasBeadsDoltRemote(commandRunner, expectedBeadsRemote);
+      if (hasRemote === false) {
+        warnings.push(
+          `Beads Dolt remote '${expectedBeadsRemote}' is not configured. ` +
+          `Sync will remain local until you run: bd dolt remote add ${expectedBeadsRemote} <url>`
+        );
+      } else if (hasRemote === null) {
+        warnings.push(
+          `Unable to inspect Beads Dolt remotes. ` +
+          `Sync may remain local until '${expectedBeadsRemote}' is configured and bd dolt remote list succeeds.`
+        );
+      }
+    }
   } else if (requireBeadsCli) {
     errors.push('bd (Beads CLI) - Install from https://github.com/steveyegge/beads');
   }
@@ -343,12 +476,60 @@ function writeFile(filePath, content) {
   return fileUtils.writeFile(filePath, content, projectRoot);
 }
 
+function writeManagedAbsoluteFile(absolutePath, content, displayPath) {
+  try {
+    if (!FORCE_MODE && fileMatchesContent(absolutePath, content)) {
+      actionLog.add(displayPath, 'skipped', 'identical content');
+      return true;
+    }
+
+    const dir = path.dirname(absolutePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const existed = fs.existsSync(absolutePath);
+    fs.writeFileSync(absolutePath, content, { mode: 0o644 });
+    actionLog.add(displayPath, FORCE_MODE ? 'force-created' : (existed ? 'updated' : 'created'));
+    return true;
+  } catch (err) {
+    console.error(`  × Failed to write ${displayPath}: ${err.message}`);
+    return false;
+  }
+}
+
 
 
 function readFile(filePath) {
   return fileUtils.readFile(filePath);
 }
 
+function resetSetupNotes() {
+  SETUP_NOTES = [];
+  CODEX_SETUP_REPORT = null;
+}
+
+function addSetupNote(message) {
+  if (!message || SETUP_NOTES.includes(message)) {
+    return;
+  }
+  SETUP_NOTES.push(message);
+}
+
+function getSetupSummaryStatus() {
+  return SETUP_NOTES.length > 0 ? 'partial' : 'complete';
+}
+
+function printSetupNotes() {
+  if (SETUP_NOTES.length === 0) {
+    return;
+  }
+
+  for (const note of SETUP_NOTES) {
+    console.log(`  Warning: ${note}`);
+  }
+}
+
 
 
 function copyFile(src, dest) { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
@@ -1741,15 +1922,42 @@ function createAgentSkill(agent, agentKey) {
 
 // Helper: Create Codex per-stage skills from canonical commands
 function createCodexSkills() {
-  const entries = listCodexSkillEntries(packageDir);
+  const installPlan = buildCodexSkillInstallPlan(packageDir, { env: process.env, homeDir: os.homedir() });
+  const installRoot = formatCodexSkillsInstallDir({ env: process.env, homeDir: os.homedir() });
+
+  CODEX_SETUP_REPORT = {
+    installRoot,
+    skillCount: installPlan.length,
+    status: 'complete',
+    message: '',
+  };
 
-  for (const entry of entries) {
-    writeFile(path.join(entry.dir, entry.filename), entry.content);
+  if (installPlan.length === 0) {
+    CODEX_SETUP_REPORT.status = 'partial';
+    CODEX_SETUP_REPORT.message = 'Codex setup could not find the packaged stage skill templates.';
+    addSetupNote(CODEX_SETUP_REPORT.message);
+    console.log('  Warning: Codex stage skill templates were not found in the Forge package');
+    return CODEX_SETUP_REPORT;
   }
 
-  if (entries.length > 0) {
-    console.log(`  Created: Codex stage skills (${entries.length})`);
+  let failed = 0;
+  for (const entry of installPlan) {
+    if (!writeManagedAbsoluteFile(entry.absolutePath, entry.content, entry.displayPath)) {
+      failed += 1;
+    }
+  }
+
+  if (failed > 0) {
+    CODEX_SETUP_REPORT.status = 'partial';
+    CODEX_SETUP_REPORT.message = `Codex repo instructions installed, but skills are not discoverable in this environment. Forge could not install ${failed}/${installPlan.length} Codex skills into ${installRoot}. Use \`bunx forge status\`, \`bunx forge plan\`, and the other Forge CLI stages until global Codex skills can be installed.`;
+    addSetupNote(CODEX_SETUP_REPORT.message);
+    console.log(`  Warning: Codex skill install incomplete (${installPlan.length - failed}/${installPlan.length}) -> ${installRoot}`);
+    return CODEX_SETUP_REPORT;
   }
+
+  CODEX_SETUP_REPORT.message = `Codex setup complete — installed ${installPlan.length} stage skills to ${installRoot}`;
+  console.log(`  Installed: Codex stage skills (${installPlan.length}) -> ${installRoot}`);
+  return CODEX_SETUP_REPORT;
 }
 
 // Helper: Setup MCP config for Claude
@@ -2210,9 +2418,10 @@ async function setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles
  * Display final setup summary
  */
 function displaySetupSummary(selectedAgents) {
+  const partial = getSetupSummaryStatus() === 'partial';
   console.log('');
   console.log('==============================================');
-  console.log(`  Forge v${VERSION} Setup Complete!`);
+  console.log(`  Forge v${VERSION} Setup ${partial ? 'Partially Complete' : 'Complete'}!`);
   console.log('==============================================');
   console.log('');
   console.log('What\'s installed:');
@@ -2230,8 +2439,9 @@ function displaySetupSummary(selectedAgents) {
       console.log(`  - ${agent.dirs[0]}/ (${workflowCount} workflow commands)`);
     }
     if (key === 'codex') {
-      const skillCount = listCodexSkillEntries(packageDir).length;
-      console.log(`  - .codex/skills/<stage>/SKILL.md (${skillCount} stage skills)`);
+      const skillCount = CODEX_SETUP_REPORT?.skillCount ?? listCodexSkillEntries(packageDir).length;
+      const codexRoot = CODEX_SETUP_REPORT?.installRoot || formatCodexSkillsInstallDir({ env: process.env, homeDir: os.homedir() });
+      console.log(`  - ${codexRoot}/<stage>/SKILL.md (${skillCount} stage skills)`);
     } else if (agent.hasSkill) {
       const skillDir = agent.dirs.find(d => d.includes('/skills/'));
       if (skillDir) {
@@ -2263,10 +2473,11 @@ function displaySetupSummary(selectedAgents) {
   console.log('');
   console.log('Project Tools Status:');
   console.log('');
+  printSetupNotes();
 
   // Beads status
   if (isBeadsInitialized()) {
-    console.log('  ✓ Beads initialized - Track work: bd ready');
+    console.log('  ✓ Beads initialized - Track work: forge ready');
   } else if (checkForBeads()) {
     console.log('  ! Beads available - Run: bd init');
   } else {
@@ -3018,7 +3229,7 @@ async function setupProjectTools(rl, question) {
   console.log('');
   console.log('• Beads - Git-backed issue tracking');
   console.log('  Persists tasks across sessions, tracks dependencies.');
-  console.log('  Command: bd ready, bd create, bd close');
+  console.log('  Command: forge ready, forge create, forge close');
   console.log('');
   console.log('• Skills - Universal SKILL.md management');
   console.log('  Manage AI agent skills across all agents.');
@@ -3250,7 +3461,8 @@ async function quickSetup(selectedAgents, skipExternal) {
 
   // Progressive setup summary
   console.log('');
-  console.log(renderSetupSummary(actionLog, selectedAgents, VERBOSE_MODE));
+  console.log(renderSetupSummary(actionLog, selectedAgents, VERBOSE_MODE, { status: getSetupSummaryStatus() }));
+  printSetupNotes();
   console.log('');
 }
 
@@ -3752,9 +3964,9 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
 
     // Agent skill
     if (agentKey === 'codex') {
-      const skillEntries = listCodexSkillEntries(packageDir);
+      const skillEntries = buildCodexSkillInstallPlan(packageDir, { env: process.env, homeDir: os.homedir() });
       for (const entry of skillEntries) {
-        addFileAction(path.join(entry.dir, entry.filename), 'Codex stage skill');
+        addFileAction(entry.displayPath, 'Codex stage skill');
       }
     } else if (agent.hasSkill) {
       const skillDir = agent.dirs.find(d => d.includes('/skills/'));
@@ -3853,7 +4065,8 @@ async function executeSetup(config) {
 
   // Progressive setup summary
   console.log('');
-  console.log(renderSetupSummary(actionLog, agents, VERBOSE_MODE));
+  console.log(renderSetupSummary(actionLog, agents, VERBOSE_MODE, { status: getSetupSummaryStatus() }));
+  printSetupNotes();
   console.log('');
 }
 
@@ -3976,7 +4189,7 @@ function detectConfiguredAgents(dir) {
   };
 
   pluginManager.getAllPlugins().forEach((plugin, id) => {
-    const dirs = Object.values(plugin.directories || {});
+    const dirs = getRepoRelativePluginDirectories(plugin);
     const files = Object.values(plugin.files || {});
     const markers = [...dirs, ...files].filter(Boolean);
     const isConfigured = markers.some((marker) => fs.existsSync(path.join(dir, marker)));
@@ -4198,6 +4411,7 @@ module.exports = {
     if (flags.symlink) SYMLINK_ONLY = true;
     if (flags.sync) SYNC_ENABLED = true;
     actionLog = new SetupActionLog();
+    resetSetupNotes();
     PKG_MANAGER = detectPackageManager();
 
     // Determine agents to install

package/lib/commands/ship.js

@@ -29,6 +29,178 @@ function isCommandNotFound(error) {
 	return error.message.includes('ENOENT') || error.message.includes('not found');
 }
 
+function getGitExecOptions(cwd = process.cwd()) {
+	return { ...getExecOptions(), cwd };
+}
+
+function getQuietGitExecOptions(cwd = process.cwd()) {
+	return { ...getGitExecOptions(cwd), stdio: 'pipe' };
+}
+
+function resolveRemoteHeadTarget(exec = execFileSync, cwd = process.cwd(), remoteName) {
+	try {
+		const symbolicRef = exec('git', ['symbolic-ref', `refs/remotes/${remoteName}/HEAD`], getQuietGitExecOptions(cwd)).trim();
+		if (!symbolicRef) {
+			return null;
+		}
+		exec('git', ['rev-parse', '--verify', symbolicRef], getQuietGitExecOptions(cwd));
+		return symbolicRef;
+	} catch (_error) {
+		return null;
+	}
+}
+
+function remoteHasTrackingBase(exec = execFileSync, cwd = process.cwd(), remoteName) {
+	if (resolveRemoteHeadTarget(exec, cwd, remoteName)) {
+		return true;
+	}
+
+	for (const candidate of ['main', 'master']) {
+		try {
+			exec('git', ['rev-parse', '--verify', `refs/remotes/${remoteName}/${candidate}`], getQuietGitExecOptions(cwd));
+			return true;
+		} catch (_error) {
+			// Probe next candidate.
+		}
+	}
+
+	return false;
+}
+
+function resolveBaseRemote(exec = execFileSync, cwd = process.cwd()) {
+	for (const candidate of ['upstream', 'origin']) {
+		try {
+			exec('git', ['remote', 'get-url', candidate], getQuietGitExecOptions(cwd));
+			if (remoteHasTrackingBase(exec, cwd, candidate)) {
+				return candidate;
+			}
+		} catch (_error) {
+			// Probe next candidate.
+		}
+	}
+
+	return 'origin';
+}
+
+function resolveBaseBranch(exec = execFileSync, cwd = process.cwd(), remoteName = resolveBaseRemote(exec, cwd)) {
+	const symbolicRef = resolveRemoteHeadTarget(exec, cwd, remoteName);
+	if (symbolicRef) {
+		const match = new RegExp(`^refs/remotes/${remoteName}/(.+)$`).exec(symbolicRef);
+		if (match && match[1]) {
+			return match[1];
+		}
+	}
+
+	for (const candidate of ['main', 'master']) {
+		try {
+			exec('git', ['rev-parse', '--verify', `refs/remotes/${remoteName}/${candidate}`], getQuietGitExecOptions(cwd));
+			return candidate;
+		} catch (_error) {
+			// Probe next candidate.
+		}
+	}
+
+	return 'master';
+}
+
+function refreshBaseReference(exec = execFileSync, cwd = process.cwd(), remoteName, baseBranch) {
+	exec(
+		'git',
+		['fetch', '--quiet', '--no-tags', remoteName, `refs/heads/${baseBranch}:refs/remotes/${remoteName}/${baseBranch}`],
+		getQuietGitExecOptions(cwd),
+	);
+}
+
+function getBranchReadiness(options = {}) {
+	const exec = options.exec || execFileSync;
+	const cwd = options.cwd || process.cwd();
+	const baseRemote = options.baseRemote || resolveBaseRemote(exec, cwd);
+	const baseBranch = options.baseBranch || resolveBaseBranch(exec, cwd, baseRemote);
+	const baseRef = `${baseRemote}/${baseBranch}`;
+	const branchName = exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], getGitExecOptions(cwd)).trim();
+
+	if (!branchName || branchName === 'HEAD') {
+		return {
+			ready: false,
+			branchName: branchName || 'HEAD',
+			baseRemote,
+			baseBranch,
+			error: 'Current HEAD is detached. Check out a feature branch before running /ship.',
+		};
+	}
+
+	try {
+		refreshBaseReference(exec, cwd, baseRemote, baseBranch);
+	} catch (error) {
+		return {
+			ready: false,
+			branchName,
+			baseRemote,
+			baseBranch,
+			error: `Unable to refresh ${baseRef} before comparing branch readiness. Verify that remote '${baseRemote}' and branch '${baseBranch}' can be fetched. Git said: ${error.message}`,
+		};
+	}
+
+	let counts;
+	try {
+		counts = exec('git', ['rev-list', '--left-right', '--count', `${baseRef}...HEAD`], getGitExecOptions(cwd)).trim();
+	} catch (error) {
+		return {
+			ready: false,
+			branchName,
+			baseRemote,
+			baseBranch,
+			error: `Unable to compare the current branch against ${baseRef}. Verify that remote '${baseRemote}' and branch '${baseBranch}' exist. Git said: ${error.message}`,
+		};
+	}
+
+	const [behindRaw = '0', aheadRaw = '0'] = counts.split(/\s+/);
+	const behind = Number.parseInt(behindRaw, 10) || 0;
+	const ahead = Number.parseInt(aheadRaw, 10) || 0;
+
+	let hasDiff = false;
+	try {
+		exec('git', ['diff', '--quiet', `${baseRef}...HEAD`, '--'], getGitExecOptions(cwd));
+	} catch (error) {
+		if (error.status === 1) {
+			hasDiff = true;
+		} else {
+			return {
+				ready: false,
+				branchName,
+				baseRemote,
+				baseBranch,
+				ahead,
+				behind,
+				error: `Unable to inspect the tree diff against ${baseRef}. Git said: ${error.message}`,
+			};
+		}
+	}
+
+	if (!hasDiff) {
+		return {
+			ready: false,
+			branchName,
+			baseRemote,
+			baseBranch,
+			ahead,
+			behind,
+			error:
+				`Current branch ${branchName} has no diff against ${baseRef}. ` +
+				'It is not PR-ready because all changes are already upstream or the branch collapsed onto the base during rebase.',
+		};
+	}
+
+	return {
+		ready: true,
+		branchName,
+		baseRemote,
+		baseBranch,
+		ahead,
+		behind,
+	};
+}
+
 /**
  * Validate feature slug format
  * Ensures slug matches expected pattern and doesn't contain path traversal
@@ -256,11 +428,11 @@ function validatePRTitle(title) {
 }
 
 async function createPR(options) { // NOSONAR S3776
-	const { title, body, dryRun = false } = options;
+	const { title, body, dryRun = false, exec = execFileSync, cwd = process.cwd() } = options;
 	const titleValidation = validatePRTitle(title);
 	if (!titleValidation.valid) return { success: false, error: titleValidation.error };
 	try {
-		execFileSync('gh', ['--version'], getGhCheckOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		exec('gh', ['--version'], { ...getGhCheckOptions(), cwd });  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 	} catch (error) {
 		if (isCommandNotFound(error)) {
 			return { success: false, error: 'GitHub CLI (gh) not found. Install from: https://cli.github.com/' };
@@ -272,22 +444,30 @@ async function createPR(options) { // NOSONAR S3776
 		return { success: false, error: `GitHub CLI check failed: ${error.message}` };
 	}
 	try {
-		execFileSync('git', ['rev-parse', '--git-dir'], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		exec('git', ['rev-parse', '--git-dir'], getGitExecOptions(cwd));  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 	} catch (error_) { // NOSONAR S2486 - intentional: not-a-git-repo is the expected failure signal
 		void error_;
 		return { success: false, error: 'Not in a git repository. Initialize with: git init' };
 	}
 	try {
-		execFileSync('git', ['remote', 'get-url', 'origin'], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		exec('git', ['remote', 'get-url', 'origin'], getGitExecOptions(cwd));  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 	} catch (error_) { // NOSONAR S2486 - intentional: no-remote is the expected failure signal
 		void error_;
 		return { success: false, error: 'No git remote configured. Add with: git remote add origin <url>' };
 	}
+	try {
+		const readiness = getBranchReadiness({ exec, cwd });
+		if (!readiness.ready) {
+			return { success: false, error: readiness.error };
+		}
+	} catch (error) {
+		return { success: false, error: `Failed to verify branch readiness: ${error.message}` };
+	}
 	if (dryRun) {
 		return { success: true, message: '[DRY RUN] Would create PR with title: ' + title, prUrl: 'https://github.com/owner/repo/pull/1' };
 	}
 	try {
-		const result = execFileSync('gh', ['pr', 'create', '--title', title, '--body', body], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		const result = exec('gh', ['pr', 'create', '--title', title, '--body', body], getGitExecOptions(cwd));  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 		const urlMatch = /https:\/\/github\.com\/[^\s]+/.exec(result);
 		const prUrl = urlMatch ? urlMatch[0] : null;
 		const numberMatch = /\/pull\/(\d+)/.exec(result);
@@ -394,4 +574,7 @@ module.exports = {
 	validatePRTitle,
 	createPR,
 	executeShip,
+	getBranchReadiness,
+	resolveBaseRemote,
+	resolveBaseBranch,
 };