forge-workflow 0.0.8 → 0.0.10

package/lib/commands/issues.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { runIssueOperation } = require('../forge-issues');
+
+const SUPPORTED_SUBCOMMANDS = ['create', 'list', 'show', 'close', 'update'];
+
+function normalizeArgs(args = []) {
+  return args.filter(arg => arg !== '--');
+}
+
+function formatHelp() {
+  return [
+    'Usage: forge issues <subcommand> [...]',
+    '',
+    'Supported subcommands:',
+    '  create  Create an issue through Forge',
+    '  list    List issues through Forge',
+    '  show    Show a single issue through Forge',
+    '  close   Close an issue through Forge',
+    '  update  Update an issue through Forge',
+  ].join('\n');
+}
+
+module.exports = {
+  name: 'issues',
+  description: 'Manage issues through the Forge authority layer',
+  usage: 'forge issues <subcommand> [...]',
+  flags: {},
+  handler: async (args, _flags, projectRoot, opts = {}) => {
+    const [subcommand, ...rest] = normalizeArgs(args);
+
+    if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+      return {
+        success: true,
+        output: formatHelp(),
+      };
+    }
+
+    if (!SUPPORTED_SUBCOMMANDS.includes(subcommand)) {
+      return {
+        success: false,
+        error: `Unknown issue subcommand '${subcommand}'.\n\n${formatHelp()}`,
+      };
+    }
+
+    const runner = opts.runIssueOperation || runIssueOperation;
+    return runner(subcommand, rest, projectRoot, opts);
+  },
+};

package/lib/commands/plan.js

@@ -254,8 +254,11 @@ function createBeadsIssue(featureName, researchPath, scope) {
 			getExecOptions()
 		);
 
-		// Extract issue ID from output (format: "Created issue: forge-xxx")
-		const match = /Created issue:\s*(forge-[a-z0-9]+)/i.exec(result) || /(forge-[a-z0-9]+)/.exec(result);
+		// Extract issue ID from output (format: "Created issue: forge-xxx" or "forge-xxx.N" for dotted sub-IDs).
+		// Character class is [a-z0-9] (not [a-zA-Z0-9]) because the /i flag makes A-Z redundant.
+		const createPattern = /Created issue:\s*(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
+		const fallbackPattern = /(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
+		const match = createPattern.exec(result) || fallbackPattern.exec(result);
 
 		if (!match) {
 			return {

package/lib/commands/recommend.js

@@ -116,4 +116,25 @@ function handleRecommend(flags, projectPath) {
   return { budgetMode, recommendations };
 }
 
-module.exports = { formatRecommendations, handleRecommend };
+async function handler(_args = [], flags = {}, projectRoot) {
+  const result = handleRecommend(flags, projectRoot);
+  if (result.error) {
+    return { success: false, error: result.error };
+  }
+
+  const output = [
+    '',
+    `🔧 Forge Tool Recommendations (Budget: ${result.budgetMode})`,
+    formatRecommendations(result.recommendations),
+  ].join('\n');
+
+  return { success: true, output };
+}
+
+module.exports = {
+  name: 'recommend',
+  description: 'Show tool recommendations for the current project',
+  handler,
+  formatRecommendations,
+  handleRecommend
+};

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');
@@ -35,7 +36,7 @@ const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require(path.join(packag
 const beadsSetupLib = require(path.join(packageDir, 'lib', 'beads-setup'));
 const { beadsHealthCheck } = require(path.join(packageDir, 'lib', 'beads-health-check'));
 const { setupPAT } = require(path.join(packageDir, 'lib', 'pat-setup'));
-const { detectDefaultBranch, detectBeadsVersion, templateWorkflows, scaffoldBeadsSync } = require(path.join(packageDir, 'lib', 'beads-sync-scaffold'));
+const { DEFAULT_BEADS_VERSION, detectDefaultBranch, templateWorkflows, scaffoldBeadsSync } = require(path.join(packageDir, 'lib', 'beads-sync-scaffold'));
 
 // Load incremental setup modules
 const { detectEnvironment } = require('../detect-agent');
@@ -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;
+  }
+
+  let failed = 0;
+  for (const entry of installPlan) {
+    if (!writeManagedAbsoluteFile(entry.absolutePath, entry.content, entry.displayPath)) {
+      failed += 1;
+    }
   }
 
-  if (entries.length > 0) {
-    console.log(`  Created: Codex stage skills (${entries.length})`);
+  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 {
@@ -2523,13 +2734,15 @@ function installGitHooks() { // NOSONAR — Extracted as-is from bin/forge.js; c
         execFileSync('lefthook', ['install'], { stdio: 'inherit', cwd: projectRoot });
         console.log('  ✓ Lefthook hooks installed (global)');
       }
-    } catch (err) {
-      console.warn('Lefthook installation failed:', err.message);
-      console.log('  ℹ Lefthook not found. Install it:');
-      console.log('    bun add -d lefthook  (recommended)');
-      console.log('    OR: bun add -g lefthook  (global)');
-      console.log('    Then run: bunx lefthook install');
-    }
+  } catch (err) {
+    console.warn('Lefthook installation failed:', err.message);
+    console.warn('  ⚠ Lefthook hooks were not installed; raw git push remains unsafe in this worktree.');
+    console.log('  ℹ Lefthook not found. Install it:');
+    console.log('    bun add -d lefthook  (recommended)');
+    console.log('    OR: bun add -g lefthook  (global)');
+    console.log('    Then run: bunx lefthook install');
+    console.log(`  Run ${PKG_MANAGER} install in this worktree, then rerun setup.`);
+  }
 
     console.log('');
 
@@ -2574,7 +2787,9 @@ function repairDeclaredLefthookDependency(selectedAgents) {
     return { attempted: true, repaired: true };
   } catch (err) {
     console.warn('Lefthook install failed:', err.message);
+    console.warn('  ⚠ Lefthook repair failed; raw git push remains unsafe in this worktree.');
     console.log(`  ⚠ ${status.message}`);
+    console.log(`  Run ${PKG_MANAGER} install in this worktree, then rerun setup.`);
     console.log('');
     return { attempted: true, repaired: false, error: err };
   }
@@ -3018,7 +3233,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.');
@@ -3103,7 +3318,9 @@ function autoInstallLefthook() { // NOSONAR — Extracted as-is from bin/forge.j
       console.log('  ✓ Lefthook binary restored');
     } catch (err) {
       console.warn('Lefthook install failed:', err.message);
+      console.warn('  ⚠ Lefthook repair failed; raw git push remains unsafe in this worktree.');
       console.log(`  ⚠ ${status.message}`);
+      console.log(`  Run ${PKG_MANAGER} install in this worktree, then rerun setup.`);
     }
     console.log('');
     return;
@@ -3250,7 +3467,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 +3970,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 +4071,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('');
 }
 
@@ -3874,9 +4093,9 @@ async function handleSyncScaffold() {
       console.log(`  Skipped: ${f} (already exists)`);
     }
 
-    // Detect default branch and Beads version, then template workflows
+    // Detect default branch and pin forge-managed workflows to the repo baseline Beads version.
     const branch = detectDefaultBranch(projectRoot);
-    const beadsVersion = detectBeadsVersion();
+    const beadsVersion = DEFAULT_BEADS_VERSION;
     const workflowDir = path.join(projectRoot, '.github', 'workflows');
     templateWorkflows(workflowDir, branch, beadsVersion, result.filesCreated || []);
     console.log(`  Branch: ${branch}, Beads version: ${beadsVersion}`);
@@ -3976,7 +4195,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 +4417,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