forge-workflow 0.0.7 → 0.0.9

package/lib/commands/_issue.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const SUBCOMMANDS = {
+  create: {
+    description: 'Create a Beads issue via Forge',
+    usage: 'forge create [title] [bd-create-flags]',
+    helpCommand: 'create',
+    buildBdArgs: (args) => ['create', ...args],
+  },
+  update: {
+    description: 'Update a Beads issue via Forge',
+    usage: 'forge update <id...> [bd-update-flags]',
+    helpCommand: 'update',
+    buildBdArgs: (args) => ['update', ...args],
+  },
+  claim: {
+    description: 'Claim a Beads issue via Forge',
+    usage: 'forge claim <id> [bd-update-flags]',
+    helpCommand: 'update',
+    buildBdArgs: (args) => {
+      const [issueId, ...rest] = args;
+      if (!issueId) {
+        return { error: 'Missing issue id. Usage: forge claim <id> [bd-update-flags]' };
+      }
+      return ['update', issueId, '--claim', ...rest];
+    },
+  },
+  close: {
+    description: 'Close a Beads issue via Forge',
+    usage: 'forge close <id...> [bd-close-flags]',
+    helpCommand: 'close',
+    buildBdArgs: (args) => ['close', ...args],
+  },
+  show: {
+    description: 'Show a Beads issue via Forge',
+    usage: 'forge show <id> [bd-show-flags]',
+    helpCommand: 'show',
+    buildBdArgs: (args) => ['show', ...args],
+  },
+  list: {
+    description: 'List Beads issues via Forge',
+    usage: 'forge list [bd-list-flags]',
+    helpCommand: 'list',
+    buildBdArgs: (args) => ['list', ...args],
+  },
+  ready: {
+    description: 'Show ready Beads issues via Forge',
+    usage: 'forge ready [bd-ready-flags]',
+    helpCommand: 'ready',
+    buildBdArgs: (args) => ['ready', ...args],
+  },
+};
+
+function normalizeArgs(args = []) {
+  return args.filter(arg => arg !== '--');
+}
+
+function getExecOptions(projectRoot) {
+  return {
+    cwd: projectRoot,
+    stdio: 'inherit',
+  };
+}
+
+function formatIssueHelp() {
+  const lines = [
+    'Usage: forge issue <subcommand> [...]',
+    '',
+    'Supported subcommands:',
+  ];
+
+  for (const [name, spec] of Object.entries(SUBCOMMANDS)) {
+    lines.push(`  ${name.padEnd(6)} ${spec.description}`);
+  }
+
+  lines.push('');
+  lines.push('Examples:');
+  lines.push('  forge create --title "Add feature" --type feature');
+  lines.push('  forge claim forge-abc');
+  lines.push('  forge update forge-abc --priority 1');
+  lines.push('  forge close forge-abc --reason "Done"');
+  lines.push('  forge issue show forge-abc --json');
+
+  return lines.join('\n');
+}
+
+function extractErrorMessage(error) {
+  if (error?.code === 'ENOENT') {
+    return 'Beads (bd) command not found. Install or initialize Beads before using Forge issue commands.';
+  }
+
+  // With stdio: 'inherit', error.stderr and error.stdout are always null.
+  // Only error.message is available for diagnostics.
+  return error?.message?.trim() || 'Beads command failed';
+}
+
+function buildBdArgs(subcommand, rawArgs) {
+  const spec = SUBCOMMANDS[subcommand];
+  if (!spec) {
+    return { error: `Unknown issue subcommand '${subcommand}'.\n\n${formatIssueHelp()}` };
+  }
+
+  const args = normalizeArgs(rawArgs);
+  if (args.includes('--help') || args.includes('-h')) {
+    return [spec.helpCommand, '--help'];
+  }
+
+  return spec.buildBdArgs(args);
+}
+
+async function runIssueSubcommand(subcommand, args, projectRoot, opts = {}) {
+  const exec = opts._exec || execFileSync;
+  const bdArgs = buildBdArgs(subcommand, args);
+
+  if (!Array.isArray(bdArgs)) {
+    return { success: false, error: bdArgs.error };
+  }
+
+  try {
+    exec('bd', bdArgs, getExecOptions(projectRoot));
+    return { success: true, subcommand };
+  } catch (error) {
+    return {
+      success: false,
+      error: extractErrorMessage(error),
+    };
+  }
+}
+
+function makeAliasCommand(subcommand) {
+  const spec = SUBCOMMANDS[subcommand];
+  if (!spec) {
+    throw new Error(`Unknown issue subcommand '${subcommand}'`);
+  }
+
+  return {
+    name: subcommand,
+    description: spec.description,
+    usage: spec.usage,
+    flags: {},
+    handler: async (args, _flags, projectRoot, opts = {}) =>
+      runIssueSubcommand(subcommand, args, projectRoot, opts),
+  };
+}
+
+function createIssueCommand() {
+  return {
+    name: 'issue',
+    description: 'Manage Beads issues through the Forge command surface',
+    usage: 'forge issue <create|update|claim|close|show|list|ready> [...]',
+    flags: {},
+    handler: async (args, _flags, projectRoot, opts = {}) => {
+      const [subcommand, ...rest] = normalizeArgs(args);
+
+      if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+        return { success: true, output: formatIssueHelp() };
+      }
+
+      return runIssueSubcommand(subcommand, rest, projectRoot, opts);
+    },
+  };
+}
+
+module.exports = {
+  SUBCOMMANDS,
+  buildBdArgs,
+  createIssueCommand,
+  makeAliasCommand,
+  runIssueSubcommand,
+};

package/lib/commands/claim.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('claim');

package/lib/commands/close.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('close');

package/lib/commands/create.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('create');

package/lib/commands/issue.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { createIssueCommand } = require('./_issue');
+
+module.exports = createIssueCommand();

package/lib/commands/list.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('list');

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/ready.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { makeAliasCommand } = require('./_issue');
+
+module.exports = makeAliasCommand('ready');

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