forge-workflow 0.0.3 → 0.0.5

package/lib/setup-action-log.js

@@ -0,0 +1,139 @@
+/**
+ * Centralized action log for setup operations.
+ *
+ * Collects file-level actions (created, skipped, merged, etc.) during
+ * `forge setup` so the CLI can display a structured summary at the end.
+ *
+ * @module setup-action-log
+ */
+
+/** Map of directory prefixes to human-readable agent names. */
+const AGENT_PREFIXES = {
+  '.claude/': 'Claude Code',
+  '.cursor/': 'Cursor',
+  '.windsurf/': 'Windsurf',
+  '.cline/': 'Cline',
+  '.codex/': 'Codex',
+  '.opencode/': 'OpenCode',
+  '.kilocode/': 'Kilocode',
+  '.roo/': 'Roo Code',
+  '.github/prompts/': 'GitHub Copilot'
+};
+
+/**
+ * Detect the agent name from a file path.
+ *
+ * @param {string} filePath - Relative file path (e.g. `.claude/settings.json`)
+ * @returns {string} Agent name or `'General'` if no agent prefix matches
+ */
+function detectAgent(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const [prefix, name] of Object.entries(AGENT_PREFIXES)) {
+    if (normalized.startsWith(prefix)) {
+      return name;
+    }
+  }
+  return 'General';
+}
+
+/**
+ * Strip the agent directory prefix from a file path.
+ *
+ * @param {string} filePath - Relative file path
+ * @returns {string} Path with the leading agent directory removed
+ */
+function stripAgentPrefix(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const prefix of Object.keys(AGENT_PREFIXES)) {
+    if (normalized.startsWith(prefix)) {
+      return normalized.slice(prefix.length);
+    }
+  }
+  return normalized;
+}
+
+class SetupActionLog {
+  constructor() {
+    /** @type {Array<{file: string, action: string, detail: string|null}>} */
+    this.actions = [];
+  }
+
+  /**
+   * Record a setup action.
+   *
+   * @param {string} file   - Relative file path that was acted on
+   * @param {string} action - One of: created, skipped, merged, conflict, removed, force-created
+   * @param {string|null} [detail=null] - Optional human-readable detail
+   */
+  add(file, action, detail = null) {
+    this.actions.push({ file, action, detail });
+  }
+
+  /**
+   * Get counts grouped by action type.
+   *
+   * @returns {Record<string, number>} e.g. `{ created: 4, skipped: 2 }`
+   */
+  getSummary() {
+    const counts = {};
+    for (const { action } of this.actions) {
+      counts[action] = (counts[action] || 0) + 1;
+    }
+    return counts;
+  }
+
+  /**
+   * Get the full ordered list of actions.
+   *
+   * @returns {Array<{file: string, action: string, detail: string|null}>}
+   */
+  getVerbose() {
+    return this.actions;
+  }
+
+  /**
+   * Group files by detected agent name.
+   *
+   * Each agent key maps to an object whose keys are action types and whose
+   * values are arrays of file paths (with the agent prefix stripped).
+   *
+   * @returns {Record<string, Record<string, string[]>>}
+   */
+  getAgentSummary() {
+    const agents = {};
+    for (const { file, action } of this.actions) {
+      const agent = detectAgent(file);
+      const stripped = stripAgentPrefix(file);
+
+      if (!agents[agent]) {
+        agents[agent] = {};
+      }
+      if (!agents[agent][action]) {
+        agents[agent][action] = [];
+      }
+      agents[agent][action].push(stripped);
+    }
+    return agents;
+  }
+
+  /**
+   * Filter actions by type.
+   *
+   * @param {string} action - The action type to filter on
+   * @returns {Array<{file: string, action: string, detail: string|null}>}
+   */
+  getByAction(action) {
+    return this.actions.filter(a => a.action === action);
+  }
+
+  /**
+   * Total number of recorded actions.
+   *
+   * @returns {number}
+   */
+  get length() {
+    return this.actions.length;
+  }
+}
+
+module.exports = { SetupActionLog };

package/lib/setup-summary-renderer.js

@@ -0,0 +1,106 @@
+/**
+ * Renders a clean summary from SetupActionLog data.
+ *
+ * Default mode: 3-line concise output.
+ * Verbose mode: file-by-file detail grouped by agent.
+ *
+ * @module setup-summary-renderer
+ */
+
+/**
+ * Capitalize the first letter of a string.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Render setup summary as a string.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog - The populated action log
+ * @param {string[]} agentNames - List of configured agent slugs (e.g. ['claude', 'cursor'])
+ * @param {boolean} verbose - Whether to show file-by-file detail
+ * @returns {string} The formatted summary output
+ */
+function renderSetupSummary(actionLog, agentNames, verbose) {
+  if (verbose) {
+    return renderVerbose(actionLog, agentNames);
+  }
+  return renderDefault(actionLog, agentNames);
+}
+
+/**
+ * Render the default 3-line concise summary.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog
+ * @param {string[]} agentNames
+ * @returns {string}
+ */
+function renderDefault(actionLog, agentNames) {
+  const agentCount = agentNames.length;
+  const agentLabel = agentCount === 1 ? '1 agent' : `${agentCount} agents`;
+  const agentList = agentNames.length > 0 ? ` (${agentNames.join(', ')})` : '';
+
+  const summary = actionLog.getSummary();
+
+  // Build counts line — only include non-zero actions
+  const displayOrder = ['created', 'skipped', 'merged', 'force-created', 'updated', 'conflict', 'removed'];
+  const parts = [];
+  for (const action of displayOrder) {
+    if (summary[action] && summary[action] > 0) {
+      parts.push(`${capitalize(action)}: ${summary[action]} ${summary[action] === 1 ? 'file' : 'files'}`);
+    }
+  }
+  // Include any actions not in displayOrder
+  for (const [action, count] of Object.entries(summary)) {
+    if (!displayOrder.includes(action) && count > 0) {
+      parts.push(`${capitalize(action)}: ${count} ${count === 1 ? 'file' : 'files'}`);
+    }
+  }
+
+  const lines = [];
+  lines.push(`Forge setup complete — ${agentLabel} configured${agentList}`);
+
+  if (parts.length > 0) {
+    lines.push(`  ${parts.join(' | ')}`);
+  } else {
+    lines.push('  0 files changed');
+  }
+
+  lines.push('  Run forge setup --verbose to see all files');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render verbose file-by-file output grouped by agent.
+ *
+ * @param {import('./setup-action-log').SetupActionLog} actionLog
+ * @param {string[]} _agentNames - Not used in verbose (agents come from log data)
+ * @returns {string}
+ */
+function renderVerbose(actionLog, _agentNames) {
+  const agentSummary = actionLog.getAgentSummary();
+  const lines = [];
+
+  for (const [agent, actions] of Object.entries(agentSummary)) {
+    for (const [action, files] of Object.entries(actions)) {
+      const fileCount = files.length;
+      const fileLabel = fileCount === 1 ? '1 file' : `${fileCount} files`;
+      const fileList = files.join(', ');
+      lines.push(`${agent}: ${fileList} (${fileLabel}) [${action}]`);
+    }
+  }
+
+  if (lines.length === 0) {
+    return 'No file operations recorded.';
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { renderSetupSummary };

package/lib/setup-utils.js

@@ -0,0 +1,96 @@
+/**
+ * Foundational utilities for `forge setup` command.
+ *
+ * - `ActionCollector` — collects planned/completed file actions for dry-run
+ *   summaries and normal-mode logging.
+ * - `isNonInteractive()` — detects CI environments and piped stdin so
+ *   interactive prompts can fall back to defaults.
+ *
+ * @module setup-utils
+ */
+
+/**
+ * Collects file-level actions during setup.
+ *
+ * Used by `--dry-run` to collect planned actions and by normal mode
+ * to log what was actually done.
+ */
+class ActionCollector {
+  constructor() {
+    /** @type {Array<{type: string, path: string, description: string}>} */
+    this._actions = [];
+  }
+
+  /**
+   * Record a setup action.
+   *
+   * @param {'create'|'modify'|'skip'} type - Action type
+   * @param {string} path - File path that was (or would be) acted on
+   * @param {string} description - Human-readable explanation
+   */
+  add(type, path, description) {
+    this._actions.push({ type, path, description });
+  }
+
+  /**
+   * Return a copy of all recorded actions.
+   *
+   * @returns {Array<{type: string, path: string, description: string}>}
+   */
+  list() {
+    return [...this._actions];
+  }
+
+  /**
+   * Print a formatted summary of all recorded actions to stdout.
+   */
+  print() {
+    if (this._actions.length === 0) {
+      return;
+    }
+
+    const icons = {
+      create: '+',
+      modify: '~',
+      skip: '-'
+    };
+
+    for (const { type, path, description } of this._actions) {
+      const icon = icons[type] || '?';
+      process.stdout.write(`  [${icon}] ${type.padEnd(6)} ${path} — ${description}\n`);
+    }
+  }
+}
+
+/**
+ * Detect whether the current environment is non-interactive.
+ *
+ * Returns `true` if any of:
+ * - `process.env.CI` is truthy (non-empty)
+ * - `process.env.GITHUB_ACTIONS` exists
+ * - `process.env.GITLAB_CI` exists
+ * - `process.stdin.isTTY` is falsy
+ * - `--non-interactive` flag was passed in `process.argv`
+ *
+ * @returns {boolean}
+ */
+function isNonInteractive() {
+  if (process.env.CI && process.env.CI !== '') {
+    return true;
+  }
+  if (process.env.GITHUB_ACTIONS !== undefined) {
+    return true;
+  }
+  if (process.env.GITLAB_CI !== undefined) {
+    return true;
+  }
+  if (!process.stdin.isTTY) {
+    return true;
+  }
+  if (process.argv.includes('--non-interactive')) {
+    return true;
+  }
+  return false;
+}
+
+module.exports = { ActionCollector, isNonInteractive };

package/lib/setup.js

@@ -1,118 +1,192 @@
-const fs = require('node:fs');
-const path = require('node:path');
-
-/**
- * Save setup state to .forge/setup-state.json
- * @param {string} projectPath - Path to the project root
- * @param {Object} state - Setup state object
- * @param {string} state.version - Forge version
- * @param {string[]} state.completed_steps - List of completed steps
- * @param {string[]} state.pending_steps - List of pending steps
- * @param {string} [state.last_run] - ISO timestamp of last run
- * @returns {Promise<void>}
- */
-async function saveSetupState(projectPath, state) {
-  const forgeDir = path.join(projectPath, '.forge');
-  const setupStatePath = path.join(forgeDir, 'setup-state.json');
-
-  // Ensure .forge directory exists
-  await fs.promises.mkdir(forgeDir, { recursive: true });
-
-  // Add last_run timestamp if not provided
-  if (!state.last_run) {
-    state.last_run = new Date().toISOString();
-  }
-
-  // Write state as JSON
-  await fs.promises.writeFile(setupStatePath, JSON.stringify(state, null, 2), 'utf-8');
-}
-
-/**
- * Load setup state from .forge/setup-state.json
- * @param {string} projectPath - Path to the project root
- * @returns {Promise<Object|null>} Setup state object, or null if not found or invalid
- */
-async function loadSetupState(projectPath) {
-  const setupStatePath = path.join(projectPath, '.forge', 'setup-state.json');
-
-  try {
-    const content = await fs.promises.readFile(setupStatePath, 'utf-8');
-    return JSON.parse(content);
-  } catch (_error) {
-    // File doesn't exist or invalid JSON
-    return null;
-  }
-}
-
-/**
- * Check if setup is complete (no pending steps)
- * @param {string} projectPath - Path to the project root
- * @returns {Promise<boolean>} True if setup complete, false otherwise
- */
-async function isSetupComplete(projectPath) {
-  const state = await loadSetupState(projectPath);
-
-  if (!state) {
-    return false;
-  }
-
-  // Setup is complete if pending_steps is empty
-  return state.pending_steps.length === 0;
-}
-
-/**
- * Get the next pending step
- * @param {string} projectPath - Path to the project root
- * @returns {Promise<string|null>} Next step name, or null if none
- */
-async function getNextStep(projectPath) {
-  const state = await loadSetupState(projectPath);
-
-  if (!state || !state.pending_steps || state.pending_steps.length === 0) {
-    return null;
-  }
-
-  // Return first pending step
-  return state.pending_steps[0];
-}
-
-/**
- * Mark a step as complete (move from pending to completed)
- * @param {string} projectPath - Path to the project root
- * @param {string} stepName - Name of the step to mark complete
- * @returns {Promise<void>}
- */
-async function markStepComplete(projectPath, stepName) {
-  let state = await loadSetupState(projectPath);
-
-  // If no state exists, create initial state
-  if (!state) {
-    state = {
-      version: '1.6.0',
-      completed_steps: [],
-      pending_steps: []
-    };
-  }
-
-  // Remove from pending_steps if present
-  state.pending_steps = state.pending_steps.filter(step => step !== stepName);
-
-  // Add to completed_steps if not already there
-  if (!state.completed_steps.includes(stepName)) {
-    state.completed_steps.push(stepName);
-  }
-
-  // Update last_run timestamp
-  state.last_run = new Date().toISOString();
-
-  // Save updated state
-  await saveSetupState(projectPath, state);
-}
-
-module.exports = {
-  saveSetupState,
-  loadSetupState,
-  isSetupComplete,
-  getNextStep,
-  markStepComplete
-};
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Save setup state to .forge/setup-state.json
+ * @param {string} projectPath - Path to the project root
+ * @param {Object} state - Setup state object
+ * @param {string} state.version - Forge version
+ * @param {string[]} state.completed_steps - List of completed steps
+ * @param {string[]} state.pending_steps - List of pending steps
+ * @param {string} [state.last_run] - ISO timestamp of last run
+ * @returns {Promise<void>}
+ */
+async function saveSetupState(projectPath, state) {
+  const forgeDir = path.join(projectPath, '.forge');
+  const setupStatePath = path.join(forgeDir, 'setup-state.json');
+
+  // Ensure .forge directory exists
+  await fs.promises.mkdir(forgeDir, { recursive: true });
+
+  // Add last_run timestamp if not provided
+  if (!state.last_run) {
+    state.last_run = new Date().toISOString();
+  }
+
+  // Write state as JSON
+  await fs.promises.writeFile(setupStatePath, JSON.stringify(state, null, 2), 'utf-8');
+}
+
+/**
+ * Load setup state from .forge/setup-state.json
+ * @param {string} projectPath - Path to the project root
+ * @returns {Promise<Object|null>} Setup state object, or null if not found or invalid
+ */
+async function loadSetupState(projectPath) {
+  const setupStatePath = path.join(projectPath, '.forge', 'setup-state.json');
+
+  try {
+    const content = await fs.promises.readFile(setupStatePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (_error) {
+    // File doesn't exist or invalid JSON
+    return null;
+  }
+}
+
+/**
+ * Check if setup is complete (no pending steps)
+ * @param {string} projectPath - Path to the project root
+ * @returns {Promise<boolean>} True if setup complete, false otherwise
+ */
+async function isSetupComplete(projectPath) {
+  const state = await loadSetupState(projectPath);
+
+  if (!state) {
+    return false;
+  }
+
+  // Setup is complete if pending_steps is empty
+  return state.pending_steps.length === 0;
+}
+
+/**
+ * Get the next pending step
+ * @param {string} projectPath - Path to the project root
+ * @returns {Promise<string|null>} Next step name, or null if none
+ */
+async function getNextStep(projectPath) {
+  const state = await loadSetupState(projectPath);
+
+  if (!state || !state.pending_steps || state.pending_steps.length === 0) {
+    return null;
+  }
+
+  // Return first pending step
+  return state.pending_steps[0];
+}
+
+/**
+ * Mark a step as complete (move from pending to completed)
+ * @param {string} projectPath - Path to the project root
+ * @param {string} stepName - Name of the step to mark complete
+ * @returns {Promise<void>}
+ */
+async function markStepComplete(projectPath, stepName) {
+  let state = await loadSetupState(projectPath);
+
+  // If no state exists, create initial state
+  if (!state) {
+    state = {
+      version: '1.6.0',
+      completed_steps: [],
+      pending_steps: []
+    };
+  }
+
+  // Remove from pending_steps if present
+  state.pending_steps = state.pending_steps.filter(step => step !== stepName);
+
+  // Add to completed_steps if not already there
+  if (!state.completed_steps.includes(stepName)) {
+    state.completed_steps.push(stepName);
+  }
+
+  // Update last_run timestamp
+  state.last_run = new Date().toISOString();
+
+  // Save updated state
+  await saveSetupState(projectPath, state);
+}
+
+/**
+ * Scaffold GitHub-Beads sync files into a target project.
+ * Copies workflow, config, and mapping template — never overwrites existing files.
+ *
+ * @param {string} projectPath - Target project root
+ * @param {string} pkgDir - Forge package directory (source of template files)
+ * @returns {Promise<{created: string[], skipped: string[]}>}
+ */
+async function scaffoldGithubBeadsSync(projectPath, pkgDir) {
+  const created = [];
+  const skipped = [];
+
+  // Sync script modules that workflows depend on at runtime
+  const syncScripts = [
+    'config.mjs', 'mapping.mjs', 'comment.mjs', 'github-api.mjs',
+    'sanitize.mjs', 'run-bd.mjs', 'label-mapper.mjs', 'index.mjs',
+    'reverse-sync.mjs', 'reverse-sync-cli.mjs',
+  ];
+
+  const files = [
+    // Phase 1: GitHub → Beads
+    {
+      src: path.join(pkgDir, '.github', 'workflows', 'github-to-beads.yml'),
+      dest: path.join('.github', 'workflows', 'github-to-beads.yml'),
+    },
+    // Phase 2: Beads → GitHub
+    {
+      src: path.join(pkgDir, '.github', 'workflows', 'beads-to-github.yml'),
+      dest: path.join('.github', 'workflows', 'beads-to-github.yml'),
+    },
+    {
+      src: path.join(pkgDir, 'scripts', 'github-beads-sync.config.json'),
+      dest: path.join('scripts', 'github-beads-sync.config.json'),
+    },
+    {
+      src: null, // generated in-place (empty mapping template)
+      dest: path.join('.github', 'beads-mapping.json'),
+      content: '{}',
+    },
+    // Sync script modules
+    ...syncScripts.map((name) => ({
+      src: path.join(pkgDir, 'scripts', 'github-beads-sync', name),
+      dest: path.join('scripts', 'github-beads-sync', name),
+    })),
+  ];
+
+  for (const file of files) {
+    const destPath = path.join(projectPath, file.dest);
+
+    // Never overwrite existing files — preserve user customizations
+    if (fs.existsSync(destPath)) {
+      skipped.push(file.dest);
+      continue;
+    }
+
+    // Ensure parent directory exists
+    const destDir = path.dirname(destPath);
+    await fs.promises.mkdir(destDir, { recursive: true });
+
+    if (file.src) {
+      // Copy from template
+      await fs.promises.copyFile(file.src, destPath);
+    } else {
+      // Write generated content
+      await fs.promises.writeFile(destPath, file.content, 'utf-8');
+    }
+
+    created.push(file.dest);
+  }
+
+  return { created, skipped };
+}
+
+module.exports = {
+  saveSetupState,
+  loadSetupState,
+  isSetupComplete,
+  getNextStep,
+  markStepComplete,
+  scaffoldGithubBeadsSync
+};