forge-workflow 0.0.4 → 0.0.6

package/scripts/check-agents.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * @module check-agents
+ *
+ * CLI command that validates all agent configs are complete and in sync.
+ *
+ * 1. Runs syncCommands({ check: true }) to verify agent command files match canonical source
+ * 2. Reads lib/agents/*.plugin.json to verify each agent with capabilities.commands: true
+ *    has its command directory populated with expected files
+ * 3. Reports: missing files, out-of-sync files, stale files
+ * 4. Exits 0 if all clean, exits non-zero if issues found
+ *
+ * Usage:
+ *   node scripts/check-agents.js
+ *
+ * Exports:
+ *   checkAgents(repoRoot) -> { errors: string[], warnings: string[] }
+ */
+
+const { syncCommands } = require('./sync-commands');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Validate all agent configs are complete and in sync.
+ *
+ * @param {string} repoRoot - Absolute path to the repository root
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function checkAgents(repoRoot) {
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+
+  // ---- 1. Run sync check ----
+  let syncResult;
+  try {
+    syncResult = syncCommands({ check: true, dryRun: false, repoRoot });
+  } catch (err) {
+    errors.push(`Sync check failed: ${err.message}`);
+    return { errors, warnings };
+  }
+
+  if (syncResult.empty) {
+    errors.push('No command files found in .claude/commands/ — cannot verify sync.');
+    return { errors, warnings };
+  } else {
+    if (syncResult.manifestMissing) {
+      warnings.push(
+        'Sync manifest (.forge/sync-manifest.json) not found — stale file detection skipped. ' +
+        'Run "node scripts/sync-commands.js" to generate it.'
+      );
+    }
+
+    if (syncResult.outOfSync && syncResult.outOfSync.length > 0) {
+      for (const entry of syncResult.outOfSync) {
+        const relPath = path.join(entry.dir, entry.filename);
+        const exists = fs.existsSync(entry.filePath);
+        const status = exists ? 'modified' : 'missing';
+        errors.push(`Out of sync [${entry.agent}]: ${relPath} (${status})`);
+      }
+    }
+
+    if (syncResult.staleFiles && syncResult.staleFiles.length > 0) {
+      for (const filePath of syncResult.staleFiles) {
+        const relPath = path.relative(repoRoot, filePath);
+        errors.push(`Stale file (no longer generated, should be removed): ${relPath}`);
+      }
+    }
+  }
+
+  // ---- 2. Validate plugin catalog ----
+  const pluginDir = path.join(repoRoot, 'lib', 'agents');
+  /** @type {object[]} */
+  const plugins = [];
+
+  if (!fs.existsSync(pluginDir)) {
+    warnings.push('No plugin directory found at lib/agents/ — plugin catalog validation skipped.');
+  } else {
+    const pluginFiles = fs.readdirSync(pluginDir).filter((f) => f.endsWith('.plugin.json'));
+
+    if (pluginFiles.length === 0) {
+      warnings.push('No plugin.json files found in lib/agents/ — plugin catalog validation skipped.');
+    }
+
+    for (const file of pluginFiles) {
+      try {
+        const plugin = JSON.parse(fs.readFileSync(path.join(pluginDir, file), 'utf8'));
+        plugins.push(plugin);
+      } catch (_err) {
+        errors.push(`Failed to parse plugin file: lib/agents/${file}`);
+      }
+    }
+
+    // For each plugin with commands: true, verify its command directory has files
+    for (const plugin of plugins) {
+      if (!plugin.capabilities || !plugin.capabilities.commands) {
+        continue;
+      }
+
+      // Find the command directory from the plugin's directories config
+      const dirs = plugin.directories || {};
+      // Plugins use different keys: commands, workflows, prompts, skills
+      const commandDir = dirs.commands || dirs.workflows || dirs.prompts;
+
+      if (!commandDir) {
+        // Plugin declares commands: true but has no command directory configured
+        // Codex is the only agent that uses skills as its command mechanism
+        if (plugin.id === 'codex' && dirs.skills) {
+          // Codex CLI: commands live in .codex/skills/<name>/SKILL.md — skip standard check
+          continue;
+        }
+        warnings.push(
+          `Plugin "${plugin.name}" (${plugin.id}) has commands: true but no command directory configured.`
+        );
+        continue;
+      }
+
+      const absCmdDir = path.join(repoRoot, commandDir);
+
+      if (!fs.existsSync(absCmdDir)) {
+        errors.push(
+          `Plugin "${plugin.name}" (${plugin.id}) has commands: true but directory "${commandDir}" does not exist.`
+        );
+        continue;
+      }
+
+      // Check the directory has at least one file
+      const files = fs.readdirSync(absCmdDir).filter((f) => !f.startsWith('.'));
+      if (files.length === 0) {
+        errors.push(
+          `Plugin "${plugin.name}" (${plugin.id}) has commands: true but directory "${commandDir}" is empty.`
+        );
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+// ---- CLI entry point ----
+
+if (require.main === module) {
+  const repoRoot = path.resolve(__dirname, '..');
+  const result = checkAgents(repoRoot);
+
+  // Print warnings
+  for (const warning of result.warnings) {
+    console.warn(`Warning: ${warning}`);
+  }
+
+  // Print errors
+  for (const error of result.errors) {
+    console.error(`Error: ${error}`);
+  }
+
+  // Summary
+  if (result.errors.length === 0 && result.warnings.length === 0) {
+    console.log('All agent checks passed.');
+    process.exit(0);
+  } else if (result.errors.length === 0) {
+    console.log(`\nAll agent checks passed with ${result.warnings.length} warning(s).`);
+    process.exit(0);
+  } else {
+    console.error(`\n${result.errors.length} error(s), ${result.warnings.length} warning(s) found.`);
+    process.exit(1);
+  }
+}
+
+module.exports = { checkAgents };

package/scripts/check-forge-token.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const path = require('node:path');
+
+const TOKEN_FILENAME = '.forge-push-token';
+const MAX_AGE_MS = 30000; // 30 seconds
+
+/**
+ * Get the absolute path to the token file.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string} Token file path
+ */
+function tokenPath(projectRoot) {
+  return path.join(projectRoot, TOKEN_FILENAME);
+}
+
+/**
+ * Write a one-time nonce token to disk.
+ * Called by `forge push` right before `git push` so lefthook hooks
+ * can detect that checks already passed and skip re-running them.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{nonce: string, timestamp: number}} The written token data
+ */
+function write(projectRoot) {
+  const data = {
+    nonce: crypto.randomUUID(),
+    timestamp: Date.now(),
+  };
+  fs.writeFileSync(tokenPath(projectRoot), JSON.stringify(data), 'utf-8');
+  return data;
+}
+
+/**
+ * Check if a valid (fresh, well-formed) forge push token exists.
+ * Does NOT delete the token — use `consume()` for one-time validation.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} True if a valid, fresh token exists
+ */
+function isValid(projectRoot) {
+  try {
+    const raw = fs.readFileSync(tokenPath(projectRoot), 'utf-8');
+    const content = JSON.parse(raw);
+    if (!content.nonce || typeof content.timestamp !== 'number') {
+      return false;
+    }
+    const age = Date.now() - content.timestamp;
+    return age < MAX_AGE_MS;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Validate and delete the token in one atomic operation (one-time use).
+ * Always attempts to delete the file, even if the token is stale or invalid.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} True if the token was valid before deletion
+ */
+function consume(projectRoot) {
+  const tp = tokenPath(projectRoot);
+  try {
+    const raw = fs.readFileSync(tp, 'utf-8');
+    // Always delete after reading — whether valid or not
+    try { fs.unlinkSync(tp); } catch (_e) { /* already gone */ }
+
+    const content = JSON.parse(raw);
+    if (!content.nonce || typeof content.timestamp !== 'number') {
+      return false;
+    }
+    const age = Date.now() - content.timestamp;
+    return age < MAX_AGE_MS;
+  } catch (_err) {
+    // File doesn't exist or isn't readable — try cleanup anyway
+    try { fs.unlinkSync(tp); } catch (_e) { /* nothing to clean */ }
+    return false;
+  }
+}
+
+module.exports = { write, isValid, consume };
+
+// When run directly as a script (e.g., from lefthook skip check):
+// Exit 0 = token valid (skip hooks), Exit 1 = run hooks normally.
+// Uses isValid() (non-destructive) so multiple lefthook commands can
+// each check the same token. The token expires after 30s automatically.
+if (require.main === module) {
+  const projectRoot = process.cwd();
+  if (isValid(projectRoot)) {
+    console.log('forge push token valid — skipping pre-push hooks');
+    process.exit(0);
+  }
+  process.exit(1);
+}

package/scripts/commitlint.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Cross-platform commitlint runner for lefthook commit-msg hook.
+ * Replaces direct npx invocation which fails on Windows without shell: true.
+ * Works on Windows CMD, PowerShell, macOS, Linux.
+ */
+
+const { spawnSync } = require('node:child_process');
+
+// On Windows, npx is npx.cmd — shell: true resolves .cmd extensions
+const isWindows = process.platform === 'win32';
+
+const commitMsgFile = process.argv[2];
+if (!commitMsgFile) {
+  console.error('❌ No commit message file provided');
+  process.exit(1);
+}
+
+// Detect package manager: prefer bun (fast, works with bun.lock), fall back to npx
+// npx fails on Windows when npm 11's arborist encounters bun.lock instead of package-lock.json
+const hasBunLock = require('node:fs').existsSync(
+  require('node:path').join(__dirname, '../bun.lock')
+);
+const runner = hasBunLock ? 'bunx' : 'npx';
+
+const result = spawnSync(
+  runner,
+  ['commitlint', '--edit', commitMsgFile],
+  { stdio: 'inherit', shell: isWindows }
+);
+
+if (result.error) {
+  console.error('');
+  console.error(`❌ Failed to run commitlint: ${result.error.message}`);
+  console.error('   Is Node.js/npm installed and on PATH?');
+  console.error('');
+  process.exit(1);
+}
+
+if (result.status !== 0) {
+  process.exit(result.status);
+}

package/scripts/conflict-detect.sh

@@ -0,0 +1,323 @@
+#!/usr/bin/env bash
+# conflict-detect.sh — Detect file/module overlaps between in-progress issues.
+#
+# Usage:
+#   conflict-detect.sh --issue <id>              Check overlaps for a given issue
+#   conflict-detect.sh --files <file1,file2,...>  Check arbitrary files against index
+#   conflict-detect.sh --issue <id> --detail      Drill down to file-level overlap
+#   conflict-detect.sh --files <f1,f2> --detail   Drill down to file-level overlap
+#
+# Exit codes:
+#   0 = no conflicts found
+#   1 = conflicts found
+#   2 = usage/validation error (malformed input)
+#
+# OWASP A03: All inputs validated; shell variables quoted; jq --arg used.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source file-index helpers (file_index_read, file_index_get)
+source "$SCRIPT_DIR/file-index.sh" || { echo "FATAL: failed to source file-index.sh" >&2; exit 2; }
+
+# Source sync-utils (get_session_identity, sanitize_config_value)
+# Only source if available (tests may not need all utils)
+if [[ -f "$SCRIPT_DIR/sync-utils.sh" ]]; then
+  source "$SCRIPT_DIR/sync-utils.sh" || { echo "FATAL: failed to source sync-utils.sh" >&2; exit 2; }
+fi
+
+# ── Input Validation ─────────────────────────────────────────────────────
+
+# Validate issue_id: alphanumeric + hyphens only
+_validate_issue_id_arg() {
+  local id="$1"
+  if [[ ! "$id" =~ ^[a-zA-Z0-9-]+$ ]]; then
+    echo "Error: invalid issue_id format: must be alphanumeric + hyphens only" >&2
+    return 1
+  fi
+}
+
+# Validate a file path: no shell injection patterns
+# Allows: alphanumeric, dots, hyphens, underscores, forward slashes
+_validate_file_path() {
+  local path="$1"
+  if [[ ! "$path" =~ ^[a-zA-Z0-9./_@[:space:]-]+$ ]]; then
+    echo "Error: invalid file path — contains disallowed characters: $path" >&2
+    return 1
+  fi
+}
+
+# ── Stale Sync Check ─────────────────────────────────────────────────────
+
+# Check if .beads/.last-sync is older than 15 minutes (900 seconds).
+# Prints a warning to stderr if stale.
+_check_stale_sync() {
+  local root="${FILE_INDEX_ROOT:-.}"
+  local last_sync_file="$root/.beads/.last-sync"
+
+  if [[ ! -f "$last_sync_file" ]]; then
+    # No sync file — skip warning (first run)
+    return 0
+  fi
+
+  local last_sync_ts
+  last_sync_ts="$(cat "$last_sync_file" 2>/dev/null | tr -d '[:space:]')"
+
+  if [[ -z "$last_sync_ts" ]]; then
+    return 0
+  fi
+
+  # .last-sync stores Unix epoch seconds (written by sync-utils.sh)
+  local last_epoch now_epoch
+  if [[ "$last_sync_ts" =~ ^[0-9]+$ ]]; then
+    last_epoch="$last_sync_ts"
+  else
+    # Fallback: try parsing as ISO 8601 (GNU date, then BSD date)
+    last_epoch="$(date -d "$last_sync_ts" +%s 2>/dev/null || date -jf "%Y-%m-%dT%H:%M:%SZ" "$last_sync_ts" +%s 2>/dev/null || echo 0)"
+  fi
+  now_epoch="$(date +%s)"
+
+  local diff=$(( now_epoch - last_epoch ))
+
+  if [[ "$diff" -gt 900 ]]; then
+    echo "WARNING: File index may be stale (last sync: ${last_sync_ts}, ${diff}s ago > 900s threshold)" >&2
+  fi
+}
+
+# ── Module Extraction ────────────────────────────────────────────────────
+
+# Given a file path, derive its module directory (parent directory + /).
+# e.g., "src/lib/status.ts" -> "src/lib/"
+_derive_module() {
+  local filepath="$1"
+  local dir
+  dir="$(dirname "$filepath")"
+  # Ensure trailing slash
+  if [[ "$dir" == "." ]]; then
+    printf '%s' "./"
+  else
+    printf '%s/' "$dir"
+  fi
+}
+
+# ── Core Conflict Detection ──────────────────────────────────────────────
+
+# Check for conflicts between a set of modules/files and all entries in the index.
+# Arguments:
+#   $1 — JSON array of modules to check
+#   $2 — JSON array of files to check
+#   $3 — issue_id to exclude from comparison (empty string for --files mode)
+#   $4 — "true" or "false" for detail mode
+# Outputs conflict report to stdout.
+# Returns 0 if no conflicts, 1 if conflicts found.
+_detect_conflicts() {
+  local check_modules="$1"
+  local check_files="$2"
+  local exclude_issue="$3"
+  local detail="$4"
+
+  # Read all active entries from file index, filter out stale entries (>48 hours)
+  local all_entries
+  local now_epoch
+  now_epoch="$(date +%s)"
+  all_entries="$(file_index_read 2>/dev/null | jq -c --arg now "$now_epoch" '
+    [.[] | select(
+      if .updated_at then
+        ((.updated_at[:19] + "Z") | fromdateiso8601) as $ts |
+        (($now | tonumber) - $ts) < 172800
+      else true end
+    )]
+  ' 2>/dev/null)" || all_entries="[]"
+
+  if [[ "$all_entries" == "[]" ]] || [[ -z "$all_entries" ]]; then
+    echo "No conflicts found. File index is empty."
+    return 0
+  fi
+
+  local conflicts_found=0
+  local output=""
+
+  # Iterate over each entry in the index
+  local entry_count
+  entry_count="$(printf '%s' "$all_entries" | jq '. | length')"
+
+  local i=0
+  while [[ "$i" -lt "$entry_count" ]]; do
+    local entry
+    entry="$(printf '%s' "$all_entries" | jq -c ".[$i]")"
+
+    local entry_issue_id
+    entry_issue_id="$(printf '%s' "$entry" | jq -r '.issue_id')"
+
+    # Skip the issue we're checking (don't conflict with yourself)
+    if [[ -n "$exclude_issue" ]] && [[ "$entry_issue_id" == "$exclude_issue" ]]; then
+      i=$((i + 1))
+      continue
+    fi
+
+    local entry_developer
+    entry_developer="$(printf '%s' "$entry" | jq -r '.developer')"
+
+    local entry_modules
+    entry_modules="$(printf '%s' "$entry" | jq -c '.modules')"
+
+    local entry_files
+    entry_files="$(printf '%s' "$entry" | jq -c '.files')"
+
+    # Check module overlap
+    local module_overlaps
+    module_overlaps="$(jq -n -c \
+      --argjson a "$check_modules" \
+      --argjson b "$entry_modules" \
+      '[$a[] as $m | $b[] | select(. == $m)] | unique')"
+
+    local module_overlap_count
+    module_overlap_count="$(printf '%s' "$module_overlaps" | jq '. | length')"
+
+    if [[ "$module_overlap_count" -gt 0 ]]; then
+      conflicts_found=1
+      local overlapping_modules_str
+      overlapping_modules_str="$(printf '%s' "$module_overlaps" | jq -r '.[]' | tr '\n' ', ' | sed 's/,$//')"
+
+      output+="CONFLICT: Issue ${entry_issue_id} (developer: ${entry_developer})"$'\n'
+      output+="  Overlapping modules: ${overlapping_modules_str}"$'\n'
+
+      # Detail mode: show file-level overlap
+      if [[ "$detail" == "true" ]]; then
+        local file_overlaps
+        file_overlaps="$(jq -n -c \
+          --argjson a "$check_files" \
+          --argjson b "$entry_files" \
+          '[$a[] as $f | $b[] | select(. == $f)] | unique')"
+
+        local file_overlap_count
+        file_overlap_count="$(printf '%s' "$file_overlaps" | jq '. | length')"
+
+        if [[ "$file_overlap_count" -gt 0 ]]; then
+          local overlapping_files_str
+          overlapping_files_str="$(printf '%s' "$file_overlaps" | jq -r '.[]' | tr '\n' ', ' | sed 's/,$//')"
+          output+="  Overlapping files: ${overlapping_files_str}"$'\n'
+        else
+          output+="  No exact file overlaps (module-level only)"$'\n'
+        fi
+      fi
+    fi
+
+    i=$((i + 1))
+  done
+
+  if [[ "$conflicts_found" -eq 1 ]]; then
+    printf '%s' "$output"
+    return 1
+  else
+    echo "No conflicts found."
+    return 0
+  fi
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────
+
+main() {
+  local mode=""        # "issue" or "files"
+  local issue_id=""
+  local files_arg=""
+  local detail="false"
+
+  # Parse arguments
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --issue)
+        mode="issue"
+        shift
+        if [[ $# -eq 0 ]]; then
+          echo "Error: --issue requires an argument" >&2
+          exit 1
+        fi
+        issue_id="$1"
+        shift
+        ;;
+      --files)
+        mode="files"
+        shift
+        if [[ $# -eq 0 ]]; then
+          echo "Error: --files requires an argument" >&2
+          exit 1
+        fi
+        files_arg="$1"
+        shift
+        ;;
+      --detail)
+        detail="true"
+        shift
+        ;;
+      *)
+        echo "Error: unknown argument '$1'" >&2
+        echo "Usage: conflict-detect.sh --issue <id> [--detail]" >&2
+        echo "       conflict-detect.sh --files <file1,file2,...> [--detail]" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  # Require at least one mode
+  if [[ -z "$mode" ]]; then
+    echo "Usage: conflict-detect.sh --issue <id> [--detail]" >&2
+    echo "       conflict-detect.sh --files <file1,file2,...> [--detail]" >&2
+    exit 1
+  fi
+
+  # Check for stale sync
+  _check_stale_sync
+
+  if [[ "$mode" == "issue" ]]; then
+    # Validate issue_id
+    _validate_issue_id_arg "$issue_id" || exit 2
+
+    # Get the issue's entry from the file index
+    local entry
+    entry="$(file_index_get "$issue_id")"
+
+    if [[ "$entry" == "null" ]]; then
+      echo "Info: issue '$issue_id' not yet in file index — no conflicts possible." >&2
+      exit 0
+    fi
+
+    local check_modules check_files
+    check_modules="$(printf '%s' "$entry" | jq -c '.modules')"
+    check_files="$(printf '%s' "$entry" | jq -c '.files')"
+
+    _detect_conflicts "$check_modules" "$check_files" "$issue_id" "$detail"
+
+  elif [[ "$mode" == "files" ]]; then
+    # Parse comma-separated file list
+    local IFS=','
+    local -a file_list
+    read -ra file_list <<< "$files_arg"
+
+    # Validate each file path
+    local -a valid_files=()
+    local -a derived_modules=()
+    for f in "${file_list[@]}"; do
+      # Trim whitespace
+      f="$(printf '%s' "$f" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+      _validate_file_path "$f" || exit 2
+      valid_files+=("$f")
+
+      # Derive module from file path
+      local mod
+      mod="$(_derive_module "$f")"
+      derived_modules+=("$mod")
+    done
+
+    # Build JSON arrays using jq
+    local files_json modules_json
+    files_json="$(printf '%s\n' "${valid_files[@]}" | jq -R '.' | jq -s -c '.')"
+    # Deduplicate modules
+    modules_json="$(printf '%s\n' "${derived_modules[@]}" | jq -R '.' | jq -s -c 'unique')"
+
+    _detect_conflicts "$modules_json" "$files_json" "" "$detail"
+  fi
+}
+
+main "$@"