forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/beads-sync-scaffold.js

@@ -1,189 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { execFileSync } = require('node:child_process');
-const { cleanupDeprecatedSyncFiles } = require('./deprecated-sync-cleanup');
-
-const DEFAULT_BEADS_VERSION = '1.0.0';
-
-/**
- * Detect the default branch of the repository.
- *
- * Strategy (in order):
- *   1. `git symbolic-ref refs/remotes/origin/HEAD` -> parse branch name
- *   2. `git remote show origin` -> parse "HEAD branch:" line
- *   3. Fall back to `'main'`
- *
- * @param {string} projectRoot - Absolute path to the project root.
- * @param {object} [options] - Options object.
- * @param {Function} [options._exec] - Injected execFileSync for testing.
- * @returns {string} The default branch name.
- */
-function detectDefaultBranch(projectRoot, options = {}) {
-  const exec = options._exec || execFileSync;
-
-  // Strategy 1: symbolic-ref
-  try {
-    const out = exec('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
-      cwd: projectRoot,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const ref = out.toString().trim();
-    // refs/remotes/origin/main -> main
-    const parts = ref.split('/');
-    if (parts.length > 0) {
-      return parts[parts.length - 1];
-    }
-  } catch (_e) {
-    // Expected: symbolic-ref fails when origin/HEAD is not set — fall through to strategy 2
-  }
-
-  // Strategy 2: remote show origin
-  try {
-    const out = exec('git', ['remote', 'show', 'origin'], {
-      cwd: projectRoot,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const text = out.toString();
-    const match = text.match(/HEAD branch:\s*(.+)/);
-    if (match) {
-      return match[1].trim();
-    }
-  } catch (_e) {
-    // Expected: 'git remote show origin' fails when no remote is configured — fall through to fallback
-  }
-
-  // Strategy 3: fallback
-  return 'main';
-}
-
-/**
- * Detect the installed Beads version.
- *
- * Strategy (in order):
- *   1. `bd --version` -> parse version string (e.g. "beads version 0.52.0" -> "0.52.0")
- *   2. Fall back to the current repo baseline release
- *
- * @param {object} [options] - Options object.
- * @param {Function} [options._exec] - Injected execFileSync for testing.
- * @returns {string} The Beads version string.
- */
-function detectBeadsVersion(options = {}) {
-  const exec = options._exec || execFileSync;
-
-  try {
-    const out = exec('bd', ['--version'], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const text = out.toString().trim();
-    // "beads version 0.52.0" -> "0.52.0"
-    const match = text.match(/(\d{1,4}\.\d{1,4}\.\d{1,4})/);
-    if (match) {
-      return match[1];
-    }
-  } catch (_e) {
-    // Expected: 'bd --version' fails when bd CLI is not installed — fall through to default version
-  }
-
-  return DEFAULT_BEADS_VERSION;
-}
-
-/**
- * Template workflow YAML files by replacing the default branch and Beads version.
- *
- * Templates only forge-created workflow files by replacing the default branch
- * and Beads version. Skips user-owned workflows to avoid overwriting legitimate
- * branch targets.
- *
- * @param {string} workflowDir - Absolute path to the directory containing YAML files.
- * @param {string} branch - The default branch name to substitute.
- * @param {string} beadsVersion - The Beads version to substitute.
- * @param {string[]} [createdFiles=[]] - List of file paths created by scaffoldBeadsSync. Only these are templated.
- */
-function templateWorkflows(workflowDir, branch, beadsVersion, createdFiles = []) {
-  if (!fs.existsSync(workflowDir)) return;
-
-  const targetNames = new Set(createdFiles.map(f => path.basename(f)));
-
-  const entries = fs.readdirSync(workflowDir);
-
-  for (const entry of entries) {
-    // Only template forge-created files; skip user-owned workflows
-    if (targetNames.size > 0 && !targetNames.has(entry)) continue;
-
-    const ext = path.extname(entry).toLowerCase();
-    if (ext !== '.yml' && ext !== '.yaml') {
-      continue;
-    }
-
-    const filePath = path.join(workflowDir, entry);
-    const stat = fs.statSync(filePath);
-    if (!stat.isFile()) {
-      continue;
-    }
-
-    const original = fs.readFileSync(filePath, 'utf8');
-    let content = original;
-    content = content.replaceAll(
-      /branches:\s*\[master\]/g,
-      `branches: [${branch}]`
-    );
-    for (const version of ['0.49.1', DEFAULT_BEADS_VERSION, '__FORGE_BEADS_VERSION__']) {
-      content = content.replaceAll(
-        `BD_VERSION="${version}"`,
-        `BD_VERSION="${beadsVersion}"`
-      );
-    }
-    // Only write if content actually changed
-    if (content !== original) {
-      fs.writeFileSync(filePath, content);
-    }
-  }
-}
-
-function cleanupDeprecatedBeadsSync(projectRoot, options = {}) {
-  return cleanupDeprecatedSyncFiles(projectRoot, options);
-}
-
-/**
- * @typedef {Object} ScaffoldResult
- * @property {string[]} filesCreated - Always empty; retained for deprecated API compatibility.
- * @property {string[]} filesSkipped - Always empty; retained for deprecated API compatibility.
- * @property {string[]} filesRemoved - Relative paths of deprecated generated sync files removed.
- * @property {boolean} deprecated - Indicates the legacy scaffold path is deprecated.
- * @property {string} message - Deprecation guidance for future sync direction.
- */
-
-/**
- * Deprecated compatibility shim for removed Beads/GitHub sync scaffolding.
- *
- * Performs cleanup of generated legacy sync artifacts only. User-owned files
- * at matching paths are preserved unless their content matches known generated
- * templates.
- *
- * @param {string} projectRoot - Absolute path to the user's project root
- * @param {string} packageDir - Absolute path to the forge package install location
- * @param {Object} [_options={}] - Reserved for future options
- * @returns {ScaffoldResult} Deprecated cleanup result.
- */
-function scaffoldBeadsSync(projectRoot, packageDir, _options = {}) {
-  const cleanup = cleanupDeprecatedBeadsSync(projectRoot, { packageDir });
-
-  return {
-    filesCreated: [],
-    filesSkipped: [],
-    filesRemoved: cleanup.removed,
-    deprecated: true,
-    message: 'Beads GitHub sync scaffolding is deprecated; future GitHub issue sync must use Forge Kernel/server authority.'
-  };
-}
-
-module.exports = {
-  DEFAULT_BEADS_VERSION,
-  detectDefaultBranch,
-  detectBeadsVersion,
-  templateWorkflows,
-  cleanupDeprecatedBeadsSync,
-  scaffoldBeadsSync,
-};

package/lib/pat-setup.js

@@ -1,207 +0,0 @@
-/**
- * Guided PAT (Personal Access Token) setup for Beads GitHub sync.
- *
- * Walks the user through creating a fine-grained PAT and saving it
- * as a repository secret via the `gh` CLI. Token values are never
- * printed to stdout — they are piped to `gh secret set` via stdin.
- *
- * @module pat-setup
- */
-
-const { execFileSync: defaultExecFileSync } = require('node:child_process');
-
-// ---------------------------------------------------------------------------
-// checkGhAuth
-// ---------------------------------------------------------------------------
-
-/**
- * Check whether the user is authenticated to GitHub via `gh auth status`.
- *
- * @param {object} [options={}]
- * @param {Function} [options._exec] - DI override for execFileSync
- * @returns {{ authenticated: boolean, user: string|null }}
- */
-function checkGhAuth(options = {}) {
-  const exec = options._exec || defaultExecFileSync;
-  try {
-    const output = exec('gh', ['auth', 'status'], { encoding: 'utf8' });
-    const str = typeof output === 'string' ? output : output.toString('utf8');
-    const match = str.match(/account\s+(\S+)/);
-    return {
-      authenticated: true,
-      user: match ? match[1] : null
-    };
-  } catch (_err) {
-    // Expected: 'gh auth status' fails when user is not authenticated — report as unauthenticated
-    return { authenticated: false, user: null };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// validateToken
-// ---------------------------------------------------------------------------
-
-/**
- * Validate that a string looks like a GitHub PAT.
- *
- * Accepts tokens starting with `ghp_` or `github_pat_` followed by at
- * least one additional character.
- *
- * @param {string|undefined} token
- * @returns {{ valid: boolean, reason?: string }}
- */
-function validateToken(token) {
-  if (!token || typeof token !== 'string' || token.trim() === '') {
-    return { valid: false, reason: 'Token is empty or not provided.' };
-  }
-
-  const trimmed = token.trim();
-
-  // Must start with a known prefix AND have content after the prefix
-  const ghpValid = trimmed.startsWith('ghp_') && trimmed.length > 'ghp_'.length;
-  const patValid = trimmed.startsWith('github_pat_') && trimmed.length > 'github_pat_'.length;
-
-  if (!ghpValid && !patValid) {
-    return {
-      valid: false,
-      reason: 'Token must start with "ghp_" or "github_pat_" followed by additional characters.'
-    };
-  }
-
-  return { valid: true };
-}
-
-// ---------------------------------------------------------------------------
-// saveSecret
-// ---------------------------------------------------------------------------
-
-/**
- * Save a token as a GitHub repository secret via `gh secret set`.
- *
- * The token is piped to stdin (via the `input` option of execFileSync)
- * so that it never appears in process arguments or stdout.
- *
- * @param {string} secretName - Name of the repository secret
- * @param {string} token - The PAT value (piped via stdin, never logged)
- * @param {object} [options={}]
- * @param {Function} [options._exec] - DI override for execFileSync
- * @returns {{ success: boolean, error: string|null }}
- */
-function saveSecret(secretName, token, options = {}) {
-  const exec = options._exec || defaultExecFileSync;
-  try {
-    exec('gh', ['secret', 'set', secretName], {
-      input: token,
-      encoding: 'utf8'
-    });
-    return { success: true, error: null };
-  } catch (err) {
-    let msg;
-    if (err.stderr) {
-      msg = typeof err.stderr === 'string' ? err.stderr : err.stderr.toString('utf8');
-    } else {
-      msg = err.message;
-    }
-    return { success: false, error: msg };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// setupPAT
-// ---------------------------------------------------------------------------
-
-/**
- * Orchestrate the full PAT setup flow.
- *
- * In non-interactive mode the step is skipped entirely. When `gh` is not
- * authenticated the user receives manual instructions. Otherwise the
- * function prompts for a token, validates it, and saves it as the
- * `BEADS_SYNC_TOKEN` repository secret.
- *
- * @param {string} _projectRoot - Absolute path to the project root
- * @param {object} [options={}]
- * @param {boolean} [options.interactive=true] - Whether prompts are allowed
- * @param {Function} [options._exec] - DI override for execFileSync
- * @param {Function} [options._prompt] - DI override for user input prompt
- * @returns {{ success: boolean, method: string, error?: string, reminder?: string, instructions?: string }}
- */
-function setupPAT(_projectRoot, options = {}) {
-  const { interactive = true, _prompt } = options;
-
-  // Non-interactive: skip entirely
-  if (!interactive) {
-    return {
-      success: false,
-      method: 'skipped',
-      reminder: 'Run "forge setup" interactively to configure the Beads sync PAT, or manually set the BEADS_SYNC_TOKEN repository secret.'
-    };
-  }
-
-  // Check gh authentication
-  const auth = checkGhAuth(options);
-
-  if (!auth.authenticated) {
-    const instructions = [
-      'GitHub CLI is not authenticated. To set up the Beads sync token manually:',
-      '1. Go to https://github.com/settings/tokens?type=beta',
-      '2. Create a fine-grained PAT with "repo" scope',
-      '3. Run: gh secret set BEADS_SYNC_TOKEN',
-      '   (or add it via your repo Settings > Secrets > Actions)'
-    ].join('\n');
-    console.log(`  ${instructions.replaceAll('\n', '\n  ')}`);
-    return {
-      success: false,
-      method: 'manual',
-      instructions
-    };
-  }
-
-  // Prompt for token
-  if (!_prompt) {
-    console.log('  No prompt function provided — skipping PAT setup.');
-    console.log('  Run "gh secret set BEADS_SYNC_TOKEN" manually to configure.');
-    return {
-      success: false,
-      method: 'manual',
-      error: 'No prompt function available for interactive token input'
-    };
-  }
-
-  const token = _prompt();
-
-  // Validate
-  const validation = validateToken(token);
-  if (!validation.valid) {
-    console.log(`  Invalid token: ${validation.reason}`);
-    return {
-      success: false,
-      method: 'automated',
-      error: validation.reason
-    };
-  }
-
-  // Save the secret — token is piped via stdin, never logged
-  const saveResult = saveSecret('BEADS_SYNC_TOKEN', token, options);
-
-  if (!saveResult.success) {
-    console.log(`  Failed to save secret: ${saveResult.error}`);
-    return {
-      success: false,
-      method: 'automated',
-      error: saveResult.error
-    };
-  }
-
-  console.log('  PAT saved as BEADS_SYNC_TOKEN repository secret.');
-  return {
-    success: true,
-    method: 'automated'
-  };
-}
-
-module.exports = {
-  checkGhAuth,
-  validateToken,
-  saveSecret,
-  setupPAT
-};

package/lib/pr-monitor/render-sticky.js

@@ -1,206 +0,0 @@
-'use strict';
-
-/**
- * PR-monitor sticky-comment renderer — turn ONE read-only `gatherPrBundle`
- * result (lib/pr-bundle.js) into the Markdown body of the single sticky PR
- * comment the pr-monitor GitHub workflow keeps up to date.
- *
- * This is the SURFACE half of the monitor: it leads with the one-line actionable
- * verdict (mirroring the `pr-verdict:*` label the workflow lands), then lists the
- * unresolved review threads (grouped by author, ANY author) plus the failing and
- * pending checks so async review-bot / human feedback in a window nobody is
- * watching cannot rot. The verdict LABELS state (check-failed / threads-open /
- * mergeable / …); it is NOT a merge action — it never merges, never resolves
- * threads, never blocks, and is fail-closed (`unknown` on unreadable signals).
- *
- * Pure and deterministic: same bundle + same injected clock → same body, which
- * is what lets the workflow rewrite the sticky comment in place without churn.
- *
- * @module pr-monitor/render-sticky
- */
-
-/**
- * Presentation-only headline for each canonical merge verdict (lib/pr-pull.js).
- * The verdict VALUE is computed once by pr-pull (`forge shepherd --pull --json`)
- * and passed in — this map only decides how to DISPLAY it, so there is no second
- * verdict ladder to drift.
- */
-const VERDICT_HEADLINE = {
-  UNKNOWN: '⚪ **Verdict: `unknown`** — a signal was unreadable; state unconfirmed (fail-closed).',
-  'BLOCKED-CONFLICT': '🔀 **Verdict: `blocked-conflict`** — branch conflicts with base; rebase/merge and resolve.',
-  BEHIND: '⬇️ **Verdict: `behind`** — branch is behind base; update/rebase (protection requires up-to-date).',
-  'BLOCKED-CHECKS': '🔴 **Verdict: `blocked-checks`** — a required check is failing/missing; fix it.',
-  'BLOCKED-THREADS': '🟠 **Verdict: `blocked-threads`** — unresolved review threads need addressing.',
-  'REVIEW-PENDING': '🟡 **Verdict: `review-pending`** — awaiting review / settle window; not ready yet.',
-  'CLEAN-MERGEABLE': '🟢 **Verdict: `clean-mergeable`** — green + zero unresolved threads; ready for a human to merge.',
-};
-
-/**
- * Render the one-line verdict headline for a canonical verdict string. Unknown or
- * missing input falls closed to the `unknown` headline.
- *
- * @param {string} verdict
- * @returns {string}
- */
-function verdictHeadline(verdict) {
-  return VERDICT_HEADLINE[String(verdict || '').toUpperCase()] || VERDICT_HEADLINE.UNKNOWN;
-}
-
-/** Hidden HTML marker: the workflow finds its prior comment by this string and
- * UPDATES it in place, so the monitor never spams a PR with new comments. */
-const STICKY_MARKER = '<!-- forge-pr-monitor -->';
-
-/** Cap threads listed per author so a noisy PR can't produce an enormous body. */
-const MAX_THREADS_PER_AUTHOR = 8;
-
-/** Group unresolved review-thread comments by author → ordered [author, threads]. */
-function groupByAuthor(comments) {
-  const byAuthor = new Map();
-  for (const c of (Array.isArray(comments) ? comments : [])) {
-    const author = String(c.author || 'unknown');
-    if (!byAuthor.has(author)) byAuthor.set(author, []);
-    byAuthor.get(author).push(c);
-  }
-  // Sort authors by descending thread count, then name — stable + deterministic.
-  return [...byAuthor.entries()].sort((a, b) => (b[1].length - a[1].length) || a[0].localeCompare(b[0]));
-}
-
-/** One-line locator for a thread: `path:line` when known, else the threadId. */
-function threadLocator(t) {
-  if (t.path) return t.line != null ? `${t.path}:${t.line}` : t.path;
-  return t.threadId || '(thread)';
-}
-
-/** Render the unresolved-review-threads section (author-agnostic + fail-closed). */
-function renderThreads(bundle, lines) {
-  // Fail-closed: if the thread read was not available for ANY reason — it threw
-  // (error set) OR the adapter cannot read comments at all (capability absent,
-  // error null) — NEVER render "zero / clean". Only a genuine available:true read
-  // may report "no unresolved threads". Guard on `!== true` (not `=== false`) so a
-  // producer that omits the flag is also treated as unread, never as clean.
-  if (bundle.unresolvedCommentsAvailable !== true) {
-    const why = bundle.unresolvedCommentsError || 'thread read unavailable (capability absent)';
-    lines.push('### Review threads');
-    lines.push(`⚠️ Review threads were **unreadable** this pass (\`${why}\`) — not treated as zero. Re-run once the read recovers.`);
-    lines.push('');
-    return;
-  }
-
-  const comments = Array.isArray(bundle.unresolvedComments) ? bundle.unresolvedComments : [];
-  if (comments.length === 0) {
-    lines.push('### Review threads');
-    lines.push('✅ No unresolved review threads.');
-    lines.push('');
-    return;
-  }
-
-  const groups = groupByAuthor(comments);
-  lines.push(`### Unresolved review threads (${comments.length})`);
-  lines.push('');
-  for (const [author, threads] of groups) {
-    lines.push(`- **${author}** — ${threads.length}`);
-    for (const t of threads.slice(0, MAX_THREADS_PER_AUTHOR)) {
-      lines.push(`  - \`${threadLocator(t)}\``);
-    }
-    if (threads.length > MAX_THREADS_PER_AUTHOR) {
-      lines.push(`  - …and ${threads.length - MAX_THREADS_PER_AUTHOR} more`);
-    }
-  }
-  lines.push('');
-}
-
-/** Render the failing / pending check sections (author-agnostic + fail-closed). */
-function renderChecks(bundle, lines) {
-  // Fail-closed, mirroring renderThreads: empty ci arrays are AMBIGUOUS — they
-  // mean either "read, genuinely all-clear" or "never read (gather outage)". Only
-  // an explicit ciAvailable === true lets us render the summary; anything else
-  // ("!== true": false or missing) surfaces as unreadable, so the monitor never
-  // prints a false "no failing checks" for CI it did not actually read.
-  if (bundle.ciAvailable !== true) {
-    lines.push('### Checks');
-    lines.push('⚠️ Checks were **unreadable** this pass — not treated as green. Re-run once the read recovers.');
-    lines.push('');
-    return;
-  }
-
-  const ci = bundle.ci || {};
-  const failing = Array.isArray(ci.failing) ? ci.failing : [];
-  const pending = Array.isArray(ci.pending) ? ci.pending : [];
-
-  lines.push('### Checks');
-  if (failing.length === 0 && pending.length === 0) {
-    lines.push('✅ No failing or pending checks.');
-  } else {
-    if (failing.length > 0) {
-      lines.push(`- ❌ **Failing (${failing.length}):** ${failing.map((c) => `\`${c.name || '?'}\``).join(', ')}`);
-    }
-    if (pending.length > 0) {
-      lines.push(`- ⏳ **Pending (${pending.length}):** ${pending.map((c) => `\`${c.name || '?'}\``).join(', ')}`);
-    }
-  }
-  lines.push('');
-}
-
-/**
- * Render the sticky monitor comment for a PR-state bundle.
- *
- * @param {object} bundle - a `gatherPrBundle` result (lib/pr-bundle.js).
- * @param {object} [opts]
- * @param {Date}   [opts.now] - injected clock for deterministic output.
- * @param {string} [opts.verdict] - the canonical `--pull` verdict.
- * @param {string[]} [opts.unreadable] - unreadable signal names (from the `--pull`
- *   evidence). Surfaced when the verdict is UNKNOWN so the sticky always says WHICH
- *   signal could not be read, not just a bare `unknown`.
- * @returns {{ marker: string, body: string }}
- */
-function renderStickyComment(bundle = {}, opts = {}) {
-  const now = opts.now instanceof Date ? opts.now : new Date();
-  const lines = [];
-
-  // The marker MUST be the very first bytes so the workflow's substring match
-  // finds the prior comment regardless of any rendering below it.
-  lines.push(STICKY_MARKER);
-  lines.push('## 🔭 Forge PR Monitor');
-  lines.push('');
-  // Lead with the actionable verdict — the SAME value as the pr-verdict:* label
-  // and `forge shepherd --pull --json` (passed in via opts.verdict, computed once
-  // by pr-pull). Surface only: it labels state; this monitor **does not merge**
-  // and never resolves review threads.
-  lines.push(verdictHeadline(opts.verdict));
-  // An `unknown` verdict is useless without the WHY — name the unreadable
-  // signal(s) so a human/agent knows what to fix (e.g. `requiredChecks` when both
-  // branch-protection AND the rollup fallback could not be read).
-  const verdictUpper = String(opts.verdict || '').toUpperCase();
-  const isUnknown = verdictUpper === 'UNKNOWN' || !VERDICT_HEADLINE[verdictUpper];
-  const unreadable = Array.isArray(opts.unreadable) ? opts.unreadable.filter(Boolean) : [];
-  if (isUnknown && unreadable.length > 0) {
-    lines.push('');
-    lines.push(`> Unreadable signal(s): ${unreadable.map((s) => `\`${s}\``).join(', ')}.`);
-  }
-  lines.push('');
-  lines.push('_Surfaces open review + check state so async feedback never rots. This monitor **does not merge** and never resolves review threads — a human merges in the GitHub UI._');
-  lines.push('');
-
-  renderThreads(bundle, lines);
-  renderChecks(bundle, lines);
-
-  const branch = bundle.branch || {};
-  if ((branch.behind || 0) > 0) {
-    lines.push(`> Branch is **${branch.behind}** commit(s) behind base.`);
-    lines.push('');
-  }
-
-  lines.push('---');
-  lines.push(`<sub>Updated ${now.toISOString()} · surface-only monitor · labels state, never merges, never resolves threads.</sub>`);
-
-  return { marker: STICKY_MARKER, body: lines.join('\n') };
-}
-
-module.exports = {
-  renderStickyComment,
-  verdictHeadline,
-  groupByAuthor,
-  threadLocator,
-  STICKY_MARKER,
-  MAX_THREADS_PER_AUTHOR,
-};