forge-workflow 0.0.10 → 0.1.0-beta.2

package/scripts/beads-context.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# beads-context.sh — Helper script to manage Beads issue context
+# beads-context.sh — Helper script to manage issue context
 # for the Forge 7-stage workflow.
 #
 # Subcommands:
@@ -17,6 +17,9 @@ set -euo pipefail
 
 # Source shared sanitize library
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/bootstrap-windows-tools.sh" ]]; then
+  source "$SCRIPT_DIR/bootstrap-windows-tools.sh"
+fi
 source "$SCRIPT_DIR/lib/sanitize.sh"
 
 # ── Helpers ──────────────────────────────────────────────────────────────
@@ -41,8 +44,8 @@ die() {
   exit 1
 }
 
-# Resolve a Windows bd.exe installation for bash-based helper flows.
-# This covers WSL/Git Bash cases where PowerShell can run bd.exe but bash PATH
+# Resolve a Windows forge.exe installation for bash-based helper flows.
+# This covers WSL/Git Bash cases where PowerShell can run forge.exe but bash PATH
 # does not include the Windows install directory.
 convert_windows_path() {
   local raw="${1%$'\r'}"
@@ -71,7 +74,7 @@ convert_windows_path() {
   printf '/mnt/%s%s' "$drive" "$rest"
 }
 
-is_runnable_bd_candidate() {
+is_runnable_forge_candidate() {
   local candidate="${1:-}"
 
   if [[ -z "$candidate" || ! -f "$candidate" ]]; then
@@ -81,41 +84,41 @@ is_runnable_bd_candidate() {
   [[ -x "$candidate" || "$candidate" == *.exe ]]
 }
 
-resolve_bd_cmd() {
+resolve_forge_cmd() {
   local candidate=""
   local converted=""
 
-  if [[ -n "${BD_CMD:-}" ]]; then
-    if [[ "${BD_CMD}" == *"/"* || "${BD_CMD}" == *"\\"* ]]; then
-      converted="$(convert_windows_path "$BD_CMD")"
-      if is_runnable_bd_candidate "$converted"; then
+  if [[ -n "${FORGE_CMD:-}" ]]; then
+    if [[ "${FORGE_CMD}" == *"/"* || "${FORGE_CMD}" == *"\\"* ]]; then
+      converted="$(convert_windows_path "$FORGE_CMD")"
+      if is_runnable_forge_candidate "$converted"; then
         printf '%s' "$converted"
         return 0
       fi
 
-      is_runnable_bd_candidate "$BD_CMD" || return 1
+      is_runnable_forge_candidate "$FORGE_CMD" || return 1
     fi
-    printf '%s' "$BD_CMD"
+    printf '%s' "$FORGE_CMD"
     return 0
   fi
 
-  if command -v bd >/dev/null 2>&1; then
-    printf '%s' "bd"
+  if command -v forge >/dev/null 2>&1; then
+    printf '%s' "forge"
     return 0
   fi
 
-  if command -v bd.exe >/dev/null 2>&1; then
-    printf '%s' "bd.exe"
+  if command -v forge.exe >/dev/null 2>&1; then
+    printf '%s' "forge.exe"
     return 0
   fi
 
   for candidate in \
-    "$HOME/.local/bin/bd" \
-    "$HOME/.local/bin/bd.exe" \
-    "$HOME/.bun/bin/bd" \
-    "$HOME/.bun/bin/bd.exe"
+    "$HOME/.local/bin/forge" \
+    "$HOME/.local/bin/forge.exe" \
+    "$HOME/.bun/bin/forge" \
+    "$HOME/.bun/bin/forge.exe"
   do
-    if is_runnable_bd_candidate "$candidate"; then
+    if is_runnable_forge_candidate "$candidate"; then
       printf '%s' "$candidate"
       return 0
     fi
@@ -127,38 +130,38 @@ resolve_bd_cmd() {
       [[ -z "$candidate" ]] && continue
 
       converted="$(convert_windows_path "$candidate")"
-      if is_runnable_bd_candidate "$converted"; then
+      if is_runnable_forge_candidate "$converted"; then
         printf '%s' "$converted"
         return 0
       fi
 
-      if is_runnable_bd_candidate "$candidate"; then
+      if is_runnable_forge_candidate "$candidate"; then
         printf '%s' "$candidate"
         return 0
       fi
-    done < <(where.exe bd 2>/dev/null || true)
+    done < <(where.exe forge 2>/dev/null || true)
   fi
 
   return 1
 }
 
-BD=""
+FORGE=""
 
-get_bd_cmd() {
-  if [[ -z "$BD" ]]; then
-    BD="$(resolve_bd_cmd)" || die "bd is required but not found"
+get_forge_cmd() {
+  if [[ -z "$FORGE" ]]; then
+    FORGE="$(resolve_forge_cmd)" || die "forge is required but not found"
   fi
 
-  printf '%s' "$BD"
+  printf '%s' "$FORGE"
 }
 
-# Run bd update and check for errors in both exit code and output.
-# bd update exits 0 even for non-existent issues, so we check stdout too.
-bd_update() {
-  local bd_cmd
-  bd_cmd="$(get_bd_cmd)"
+# Run forge issue update and check for errors in both exit code and output.
+# The update operation exits 0 even for non-existent issues, so we check stdout too.
+forge_update() {
+  local forge_cmd
+  forge_cmd="$(get_forge_cmd)"
   local output
-  output="$("$bd_cmd" update "$@" 2>&1)"
+  output="$("$forge_cmd" issue update "$@" 2>&1)"
   local rc=$?
 
   if [[ $rc -ne 0 ]]; then
@@ -166,7 +169,7 @@ bd_update() {
     return 1
   fi
 
-  # bd prints "Error resolving/updating ..." to stdout for non-existent issues
+  # Forge prints "Error resolving/updating ..." to stdout for non-existent issues
   # Use specific patterns to avoid false positives from data containing "error"
   if printf '%s' "$output" | grep -Eqi '^Error|Error resolving|Error updating'; then
     echo "$output" >&2
@@ -177,12 +180,12 @@ bd_update() {
   return 0
 }
 
-# Run bd comments add and check for errors similarly.
-bd_comment() {
-  local bd_cmd
-  bd_cmd="$(get_bd_cmd)"
+# Run forge issue comment and check for errors similarly.
+forge_comment() {
+  local forge_cmd
+  forge_cmd="$(get_forge_cmd)"
   local output
-  output="$("$bd_cmd" comments add "$@" 2>&1)"
+  output="$("$forge_cmd" issue comment "$@" 2>&1)"
   local rc=$?
 
   if [[ $rc -ne 0 ]]; then
@@ -200,6 +203,25 @@ bd_comment() {
   return 0
 }
 
+# Extract concatenated comment text from a `forge issue show --json` payload.
+# Forge/issue show returns comments as an array of objects ({text:...}) — matching
+# the issue-state contract in lib/workflow/state-manager.js — or, defensively, a
+# raw string. jq is preferred; a grep/sed fallback captures "text" fields.
+extract_comments_text() {
+  local json="$1"
+
+  if command -v jq &>/dev/null; then
+    printf '%s' "$json" | jq -r '
+      ((if type == "array" then .[0] else . end).comments // [])
+      | if type == "array" then (map(.text? // tostring) | join("\n"))
+        else tostring end
+    ' 2>/dev/null || true
+    return 0
+  fi
+
+  printf '%s' "$json" | grep -o '"text": *"[^"]*"' | sed 's/^"text": *"//;s/"$//' || true
+}
+
 # ── Subcommands ──────────────────────────────────────────────────────────
 
 cmd_set_design() {
@@ -216,7 +238,7 @@ cmd_set_design() {
 
   local design_text="${task_count} tasks | ${task_file}"
 
-  if ! bd_update "$issue_id" --design "$design_text" > /dev/null; then
+  if ! forge_update "$issue_id" --design "$design_text" > /dev/null; then
     die "Failed to set design on issue ${issue_id}"
   fi
 
@@ -233,7 +255,7 @@ cmd_set_acceptance() {
   local criteria
   criteria="$(sanitize "$2")"
 
-  if ! bd_update "$issue_id" --acceptance "$criteria" > /dev/null; then
+  if ! forge_update "$issue_id" --acceptance "$criteria" > /dev/null; then
     die "Failed to set acceptance on issue ${issue_id}"
   fi
 
@@ -273,7 +295,7 @@ cmd_update_progress() {
 
   local note="Task ${task_num}/${total} done: ${title} | ${test_count} tests | ${commit_sha} | ${gate_count} gates"
 
-  if ! bd_update "$issue_id" --append-notes "$note" > /dev/null; then
+  if ! forge_update "$issue_id" --append-notes "$note" > /dev/null; then
     die "Failed to update progress on issue ${issue_id}"
   fi
 
@@ -287,20 +309,20 @@ cmd_parse_progress() {
   fi
 
   local issue_id="$1"
-  local bd_cmd
-  bd_cmd="$(get_bd_cmd)"
+  local forge_cmd
+  forge_cmd="$(get_forge_cmd)"
 
   # Get the issue JSON — detect non-existent issues
   local json
-  json="$("$bd_cmd" show "$issue_id" --json 2>&1)" || die "Failed to show issue ${issue_id}"
+  json="$("$forge_cmd" issue show "$issue_id" --json 2>&1)" || die "Failed to show issue ${issue_id}"
 
-  # bd show may exit 0 but print an error for non-existent issues
-  # Match specific bd error patterns, not the word "error" in data fields
+  # show may exit 0 but print an error for non-existent issues
+  # Match specific error patterns, not the word "error" in data fields
   if printf '%s' "$json" | grep -Eqi '^Error (fetching|resolving)'; then
     die "Issue not found: ${issue_id}"
   fi
 
-  # bd show returns "[]" or empty for non-existent issues
+  # show returns "[]" or empty for non-existent issues
   if [[ -z "$json" || "$json" == "[]" || "$json" == "null" ]]; then
     die "Issue not found: ${issue_id}"
   fi
@@ -308,7 +330,7 @@ cmd_parse_progress() {
   # Extract notes field from JSON — prefer jq if available, fall back to grep/sed
   local notes
   if command -v jq &>/dev/null; then
-    # Handle both array ([{...}]) and object ({...}) responses from bd show
+    # Handle both array ([{...}]) and object ({...}) show responses
     notes="$(printf '%s' "$json" | jq -r 'if type == "array" then .[0].notes else .notes end // empty' 2>/dev/null || true)"
   else
     notes="$(printf '%s' "$json" | grep -o '"notes": *"[^"]*"' | head -1 | sed 's/^"notes": *"//;s/"$//' || true)"
@@ -422,7 +444,7 @@ Next: ${flag_next}"
 WorkflowState: ${flag_workflow_state}"
   fi
 
-  if ! bd_comment "$issue_id" "$comment" > /dev/null; then
+  if ! forge_comment "$issue_id" "$comment" > /dev/null; then
     die "Failed to record stage transition on issue ${issue_id}"
   fi
 
@@ -437,17 +459,17 @@ cmd_validate() {
 
   local issue_id="$1"
   local warnings=0
-  local bd_cmd
-  bd_cmd="$(get_bd_cmd)"
+  local forge_cmd
+  forge_cmd="$(get_forge_cmd)"
 
   # Get issue JSON
   local json
-  json="$("$bd_cmd" show "$issue_id" --json 2>&1)" || {
+  json="$("$forge_cmd" issue show "$issue_id" --json 2>&1)" || {
     echo "Error: Failed to retrieve issue ${issue_id}" >&2
     exit 1
   }
 
-  # Check for bd error patterns
+  # Check for error patterns
   if printf '%s' "$json" | grep -Eqi '^Error|Error resolving|Error fetching'; then
     echo "Error: Issue not found: ${issue_id}" >&2
     exit 1
@@ -474,9 +496,11 @@ cmd_validate() {
     warnings=$((warnings + 1))
   fi
 
-  # Get comments to check for stage transitions
+  # The issue payload returned by `forge issue show --json` already includes its
+  # comment history, so the stage-transition checks read comments from that single
+  # response rather than issuing a separate comment-list query.
   local comments
-  comments="$("$bd_cmd" comments "$issue_id" 2>/dev/null || true)"
+  comments="$(extract_comments_text "$json")"
 
   # Check 2: At least one stage transition exists
   local has_transition=false

package/scripts/beads-upgrade-smoke.sh

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+_BEADS_UPGRADE_SMOKE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$_BEADS_UPGRADE_SMOKE_DIR/bootstrap-windows-tools.sh" ]]; then
+  source "$_BEADS_UPGRADE_SMOKE_DIR/bootstrap-windows-tools.sh"
+fi
+
 BD_CMD="${BD_CMD:-bd}"
 NODE_CMD="${NODE_CMD:-node}"
 PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
@@ -12,6 +17,22 @@ SMOKE_RUN_ID="${BEADS_UPGRADE_SMOKE_RUN_ID:-$(date +%s)-$$}"
 PRIMARY_ISSUE_TITLE="Beads upgrade smoke primary (${SMOKE_RUN_ID})"
 DEPENDENT_ISSUE_TITLE="Beads upgrade smoke dependent (${SMOKE_RUN_ID})"
 
+node_fs_path() {
+  case "$1" in
+    /[A-Za-z]/*)
+      _drive="$(printf '%s' "${1:1:1}" | tr '[:lower:]' '[:upper:]')"
+      printf '%s:/%s\n' "$_drive" "${1:3}"
+      ;;
+    *)
+      if command -v cygpath >/dev/null 2>&1; then
+        cygpath -m "$1"
+      else
+        printf '%s\n' "$1"
+      fi
+      ;;
+  esac
+}
+
 mkdir -p "${ARTIFACT_DIR}"
 : > "${COMMAND_LOG_PATH}"
 
@@ -77,7 +98,7 @@ append_command() {
       stderrPath,
     };
     fs.appendFileSync(logPath, JSON.stringify(entry) + "\n");
-  ' "${COMMAND_LOG_PATH}" "${step}" "${command_name}" "${command_text}" "${exit_code}" "${stdout_path}" "${stderr_path}"
+  ' "$(node_fs_path "${COMMAND_LOG_PATH}")" "${step}" "${command_name}" "${command_text}" "${exit_code}" "$(node_fs_path "${stdout_path}")" "$(node_fs_path "${stderr_path}")"
 }
 
 read_output_snippet() {
@@ -91,7 +112,7 @@ read_output_snippet() {
     const [filePath] = process.argv.slice(1);
     const text = fs.readFileSync(filePath, "utf8");
     process.stdout.write(text.slice(0, 4096));
-  ' "${file_path}"
+  ' "$(node_fs_path "${file_path}")"
 }
 
 write_summary() {
@@ -126,7 +147,7 @@ write_summary() {
       artifactDir,
     };
     fs.writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + "\n");
-  ' "${COMMAND_LOG_PATH}" "${SUMMARY_PATH}" "${ok}" "${failed_step}" "${failure_message}" "${ARTIFACT_DIR}" "$(printf '%s\n' "${created_issue_ids[@]:-}" | "${NODE_CMD}" -e 'const fs=require("node:fs"); const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).filter(Boolean); process.stdout.write(JSON.stringify(lines));')" "$(printf '%s\n' "${closed_issue_ids[@]:-}" | "${NODE_CMD}" -e 'const fs=require("node:fs"); const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).filter(Boolean); process.stdout.write(JSON.stringify(lines));')"
+  ' "$(node_fs_path "${COMMAND_LOG_PATH}")" "$(node_fs_path "${SUMMARY_PATH}")" "${ok}" "${failed_step}" "${failure_message}" "$(node_fs_path "${ARTIFACT_DIR}")" "$(printf '%s\n' "${created_issue_ids[@]:-}" | "${NODE_CMD}" -e 'const fs=require("node:fs"); const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).filter(Boolean); process.stdout.write(JSON.stringify(lines));')" "$(printf '%s\n' "${closed_issue_ids[@]:-}" | "${NODE_CMD}" -e 'const fs=require("node:fs"); const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).filter(Boolean); process.stdout.write(JSON.stringify(lines));')"
 }
 
 run_bd_step() {

package/scripts/bootstrap-windows-tools.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Shared Windows/WSL command bootstrap for bash entrypoints.
+
+if [[ -n "${_FORGE_BOOTSTRAP_WINDOWS_TOOLS_LOADED:-}" ]]; then
+  return 0 2>/dev/null || exit 0
+fi
+_FORGE_BOOTSTRAP_WINDOWS_TOOLS_LOADED=1
+
+_forge_to_unix_path() {
+  local raw="$1"
+  if command -v wslpath >/dev/null 2>&1; then
+    wslpath -u "$raw" 2>/dev/null && return 0
+  fi
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -u "$raw" 2>/dev/null && return 0
+  fi
+  printf '%s\n' "$raw"
+}
+
+_forge_resolve_tool() {
+  local name="$1"
+  local found=""
+
+  found="$(command -v "$name" 2>/dev/null || true)"
+  if [[ -n "$found" ]]; then
+    printf '%s\n' "$found"
+    return 0
+  fi
+
+  if command -v where.exe >/dev/null 2>&1; then
+    found="$(where.exe "$name" 2>/dev/null | tr -d '\r' | head -n 1 || true)"
+    if [[ -n "$found" ]]; then
+      _forge_to_unix_path "$found"
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+if [[ -z "${BD_CMD:-}" ]]; then
+  BD_CMD="$(_forge_resolve_tool bd || true)"
+fi
+if [[ -n "${BD_CMD:-}" ]]; then
+  export BD_CMD
+fi
+
+if [[ -z "${JQ_CMD:-}" ]]; then
+  JQ_CMD="$(_forge_resolve_tool jq || true)"
+fi
+if [[ -n "${JQ_CMD:-}" ]]; then
+  export JQ_CMD
+fi
+
+if [[ -z "${GH_CMD:-}" ]]; then
+  GH_CMD="$(_forge_resolve_tool gh || true)"
+fi
+if [[ -n "${GH_CMD:-}" ]]; then
+  export GH_CMD
+fi
+
+if [[ -n "${BD_CMD:-}" ]]; then
+  bd() {
+    command "$BD_CMD" "$@"
+  }
+fi
+
+if [[ -n "${JQ_CMD:-}" ]]; then
+  jq() {
+    command "$JQ_CMD" "$@"
+  }
+fi
+
+if [[ -n "${GH_CMD:-}" ]]; then
+  gh() {
+    command "$GH_CMD" "$@"
+  }
+fi

package/scripts/branch-protection.js

@@ -131,7 +131,7 @@ function main() {
   const currentBranch = getCurrentBranch();
 
   if (isProtectedBranch(currentBranch)) {
-    // Allow beads-only commits (issue tracking metadata) to push directly
+    // Beads runtime metadata is local state. Do not bypass protected branches for it.
     try {
       let upstream;
       try {
@@ -150,8 +150,7 @@ function main() {
       if (changedFiles.length === 0) {
         console.error(`${YELLOW}Note: no changed files detected — nothing to bypass${RESET}`);
       } else if (changedFiles.every(f => f.startsWith('.beads/'))) {
-        console.error(`${YELLOW}Beads-only push to '${currentBranch}' — allowed${RESET}`);
-        process.exit(0);
+        console.error(`${YELLOW}Beads metadata is local runtime state; protected branches do not accept .beads-only pushes.${RESET}`);
       }
     } catch (_e) {
       console.error(`${YELLOW}Note: could not detect beads-only push (upstream ref missing?) — blocking by default${RESET}`);