@snipcodeit/mgw 0.2.2 → 0.4.0

package/README.md

@@ -1,6 +1,7 @@
 # MGW — My GSD Workflow
 
 [![npm version](https://img.shields.io/npm/v/@snipcodeit/mgw)](https://www.npmjs.com/package/@snipcodeit/mgw)
+[![CI](https://github.com/snipcodeit/mgw/actions/workflows/ci.yml/badge.svg)](https://github.com/snipcodeit/mgw/actions/workflows/ci.yml)
 [![npm downloads](https://img.shields.io/npm/dm/@snipcodeit/mgw)](https://www.npmjs.com/package/@snipcodeit/mgw)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![node](https://img.shields.io/node/v/@snipcodeit/mgw)](https://nodejs.org)
@@ -341,18 +342,23 @@ bin/
 lib/
   index.cjs               Barrel export
   claude.cjs              Claude Code invocation helpers
-  github.cjs              GitHub CLI wrappers (issues, PRs, milestones, Projects v2)
+  errors.cjs              Typed error hierarchy (MgwError, GitHubApiError, TimeoutError, etc.)
+  github.cjs              Async GitHub CLI wrappers with retry/timeout (issues, PRs, milestones, Projects v2)
   gsd.cjs                 GSD integration
   gsd-adapter.cjs         GSD route adapter (maps triage results to GSD spawn args)
-  state.cjs               .mgw/ state management (migrateProjectState, resolveActiveMilestoneIndex)
+  logger.cjs              Structured JSON-lines execution logging (.mgw/logs/)
+  pipeline.cjs            Pipeline stage constants, valid transitions, and transition hooks
+  state.cjs               .mgw/ state management, cross-refs validation, dependency parsing
   output.cjs              Logging and formatting
-  retry.cjs               Retry logic for GitHub API calls
+  progress.cjs            Milestone progress display
+  retry.cjs               Retry/backoff logic with failure classification
   templates.cjs           Template system
   template-loader.cjs     Output validation (JSON Schema) + parseRoadmap()
 commands/                  Slash command source files (deployed to ~/.claude/commands/mgw/ at install time)
   ask.md                  Contextual question routing during milestone execution
   assign.md               Claim/reassign issues; resolves GitHub noreply co-author tag
-  board.md                GitHub Projects v2 board management
+  board.md                GitHub Projects v2 board dispatcher
+  board/                   Board subcommands (create, show, configure, views, sync)
   help.md                 Command reference display
   init.md                 One-time repo bootstrap (state, templates, labels)
   project.md              State-aware project init (Vision Cycle, alignment, drift, extend)
@@ -361,7 +367,8 @@ commands/                  Slash command source files (deployed to ~/.claude/com
   next.md                 Next unblocked issue picker (surfaces failed issues as advisory)
   review.md               Comment review and classification since last triage
   roadmap.md              Milestone roadmap table; optional GitHub due-date setter and Discussion post
-  run.md                  Autonomous pipeline orchestrator (cross-milestone enforcement)
+  run.md                  Autonomous pipeline orchestrator (dispatches to run/ stages)
+  run/                     Pipeline stage files (triage, worktree, execute, pr-create)
   milestone.md            Milestone execution with dependency ordering and failed-issue recovery
   update.md               Structured GitHub comment templates
   pr.md                   PR creation from GSD artifacts with phase context + plan traceability
@@ -381,6 +388,49 @@ templates/
 
 For a detailed walkthrough of the directory structure, slash command anatomy, and CLI architecture, see the [Architecture Guide](docs/ARCHITECTURE.md#directory-structure).
 
+## Post-install Behavior
+
+When you `npm install` MGW (globally or locally), the `postinstall` script (`bin/mgw-install.cjs`) copies all slash command `.md` files from `commands/` to `~/.claude/commands/mgw/`. This makes `/mgw:*` commands available in Claude Code.
+
+To skip this behavior (e.g., in CI or Docker):
+
+```bash
+npm install -g @snipcodeit/mgw --ignore-scripts
+```
+
+To re-run manually:
+
+```bash
+node ./bin/mgw-install.cjs
+```
+
+## CLI Commands
+
+In addition to slash commands (used inside Claude Code), MGW provides standalone CLI commands:
+
+```bash
+mgw issues                        # Browse GitHub issues
+mgw sync                          # Reconcile .mgw/ state with GitHub
+mgw link 42 43                    # Cross-reference two issues
+mgw log                           # View execution logs
+mgw log --since 7d --metrics      # Aggregated metrics for the last 7 days
+mgw metrics                       # Pipeline metrics dashboard
+mgw metrics --since 30d           # Metrics over the last 30 days
+```
+
+The `log` and `metrics` commands read from structured JSON-lines logs in `.mgw/logs/` that are written automatically during command execution.
+
+## Development
+
+```bash
+git clone https://github.com/snipcodeit/mgw.git
+cd mgw
+npm install
+npm test          # 365 tests across 71 suites (Node.js built-in test runner)
+npm run lint      # ESLint
+npm run build     # pkgroll → dist/
+```
+
 ## Documentation
 
 | Document | Description |

package/bin/mgw-install.cjs

@@ -2,45 +2,84 @@
 'use strict';
 
 /**
- * bin/mgw-install.cjs — Idempotent slash command installer
+ * bin/mgw-install.cjs — Multi-CLI-aware idempotent slash command installer
  *
- * Runs automatically via npm postinstall. Copies the commands/ source tree
- * into ~/.claude/commands/mgw/ so Claude Code slash commands are available
- * without any manual copy step.
+ * Runs automatically via npm postinstall. Detects the active AI CLI
+ * (claude, gemini, or opencode — in priority order) and copies the
+ * commands/ source tree into the correct provider-specific commands
+ * directory so slash commands are available without any manual copy step.
  *
  * Behavior:
- * - If ~/.claude/ does not exist: prints a skip message and exits 0 (non-fatal)
- * - If ~/.claude/ exists: creates ~/.claude/commands/mgw/ and recursively
- *   copies commands/ into it (overwriting existing files — idempotent)
- * - Exits 0 in both cases
+ * - Auto-detects first available CLI binary (claude > gemini > opencode)
+ * - --provider=<id> flag overrides auto-detection
+ * - If no AI CLI is found on PATH: prints skip message and exits 0 (non-fatal)
+ * - If provider's base dir does not exist: prints skip message and exits 0
+ * - If previously installed provider differs: removes old install dir first
+ * - Idempotent: running twice for the same provider is safe
+ * - Tracks installed provider in ~/.mgw-install-state.json
  *
- * Dependencies: Node.js built-ins only (path, fs, os)
+ * Dependencies: Node.js built-ins only (path, fs, os, child_process)
  */
 
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const { execSync } = require('child_process');
 
 // Source: commands/ directory relative to this script (bin/ → ../commands/)
 const sourceDir = path.join(__dirname, '..', 'commands');
 
-// Target: ~/.claude/commands/mgw/
-const claudeDir = path.join(os.homedir(), '.claude');
-const targetDir = path.join(claudeDir, 'commands', 'mgw');
+// State file for tracking installed provider across runs
+const statePath = path.join(os.homedir(), '.mgw-install-state.json');
 
-// Guard: if ~/.claude/ does not exist, skip silently with a clear message
-if (!fs.existsSync(claudeDir)) {
-  console.log(
-    'mgw: ~/.claude/ not found — skipping slash command install ' +
-    '(run `node ./bin/mgw-install.cjs` after installing Claude Code)'
-  );
-  process.exit(0);
+// Provider target directories — where each CLI expects slash commands
+const PROVIDER_TARGETS = {
+  claude:   path.join(os.homedir(), '.claude', 'commands', 'mgw'),
+  gemini:   path.join(os.homedir(), '.gemini', 'commands', 'mgw'),
+  opencode: path.join(os.homedir(), '.opencode', 'commands', 'mgw'),
+};
+
+// Valid provider IDs (order is also detection priority)
+const VALID_PROVIDERS = ['claude', 'gemini', 'opencode'];
+
+/**
+ * Parse --provider flag from process.argv.
+ * Handles both --provider=claude and --provider claude forms.
+ * @returns {string|null} provider ID string or null if not specified
+ */
+function parseProviderFlag() {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--provider=')) {
+      return args[i].split('=')[1] || null;
+    }
+    if (args[i] === '--provider' && i + 1 < args.length) {
+      return args[i + 1];
+    }
+  }
+  return null;
 }
 
-// Guard: ensure commands/ source exists in this package
-if (!fs.existsSync(sourceDir)) {
-  console.log('mgw: commands/ source not found — skipping slash command install');
-  process.exit(0);
+/**
+ * Detect the active AI CLI by trying binaries in priority order.
+ * @param {string|null} forcedProvider - If set, skip detection and return this value.
+ * @returns {string|null} Provider ID of the first found binary, or null if none found.
+ */
+function detectProvider(forcedProvider) {
+  if (forcedProvider) {
+    return forcedProvider;
+  }
+
+  for (const id of VALID_PROVIDERS) {
+    try {
+      execSync(id + ' --version', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+      return id;
+    } catch (_) {
+      // Binary not found or not working — try next
+    }
+  }
+
+  return null;
 }
 
 /**
@@ -76,6 +115,64 @@ function copyDirRecursive(src, dest) {
   return count;
 }
 
+// --- Main ---
+
+// Guard: ensure commands/ source exists in this package
+if (!fs.existsSync(sourceDir)) {
+  console.log('mgw: commands/ source not found — skipping slash command install');
+  process.exit(0);
+}
+
+// Parse and validate --provider flag
+const flagProvider = parseProviderFlag();
+if (flagProvider !== null && !VALID_PROVIDERS.includes(flagProvider)) {
+  console.error(
+    'mgw: unknown provider "' + flagProvider + '" — valid options: ' + VALID_PROVIDERS.join(', ')
+  );
+  process.exit(1);
+}
+
+// Detect or use forced provider
+const detectedProvider = detectProvider(flagProvider);
+
+if (detectedProvider === null) {
+  console.log('mgw: no AI CLI found (claude/gemini/opencode) — skipping slash command install');
+  process.exit(0);
+}
+
+// Parent dir guard: provider's base config directory must already exist
+// (i.e. the user has run the CLI at least once to initialize it).
+// This MUST run before old-dir cleanup — otherwise switching to a provider
+// whose home dir doesn't exist would delete old commands and install nothing.
+const targetDir = PROVIDER_TARGETS[detectedProvider];
+const providerHomeDir = path.join(os.homedir(), '.' + detectedProvider);
+
+if (!fs.existsSync(providerHomeDir)) {
+  console.log(
+    'mgw: ~/.' + detectedProvider + '/ not found — skipping slash command install ' +
+    '(run the CLI once to initialize it)'
+  );
+  process.exit(0);
+}
+
+// Old-dir cleanup: if previously installed provider differs, remove old install.
+// Safe to run here — we've already confirmed the new provider's home dir exists.
+if (fs.existsSync(statePath)) {
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    if (state.provider && state.provider !== detectedProvider && PROVIDER_TARGETS[state.provider]) {
+      const oldDir = PROVIDER_TARGETS[state.provider];
+      fs.rmSync(oldDir, { recursive: true, force: true });
+    }
+  } catch (_) {
+    // Corrupt or unreadable state file — ignore and continue
+  }
+}
+
 // Perform the install
 const fileCount = copyDirRecursive(sourceDir, targetDir);
-console.log(`mgw: installed ${fileCount} slash commands to ${targetDir}`);
+
+// Write state file
+fs.writeFileSync(statePath, JSON.stringify({ provider: detectedProvider }, null, 2));
+
+console.log('mgw: detected ' + detectedProvider + ' CLI — installed ' + fileCount + ' slash commands to ' + targetDir);

package/commands/board/configure.md

@@ -0,0 +1,205 @@
+---
+name: board:configure
+description: Update board field options by comparing current state against canonical schema
+---
+
+<step name="subcommand_configure">
+**Execute 'configure' subcommand:**
+
+Only run if `$SUBCOMMAND = "configure"`.
+
+Reads current field options from GitHub and compares to the canonical schema in
+docs/BOARD-SCHEMA.md / .mgw/board-schema.json. Adds any missing options.
+
+```bash
+if [ "$SUBCOMMAND" = "configure" ]; then
+  if [ "$BOARD_CONFIGURED" = "false" ]; then
+    echo "No board configured. Run /mgw:board create first."
+    exit 1
+  fi
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo " MGW ► BOARD CONFIGURE: ${PROJECT_NAME}"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Board: #${BOARD_NUMBER} — ${BOARD_URL}"
+  echo ""
+```
+
+**Fetch current field state from GitHub:**
+
+```bash
+  FIELDS_STATE=$(gh api graphql -f query='
+    query($owner: String!, $number: Int!) {
+      user(login: $owner) {
+        projectV2(number: $number) {
+          fields(first: 20) {
+            nodes {
+              ... on ProjectV2SingleSelectField {
+                id
+                name
+                options { id name color description }
+              }
+              ... on ProjectV2Field {
+                id
+                name
+                dataType
+              }
+            }
+          }
+        }
+      }
+    }
+  ' -f owner="$OWNER" -F number="$BOARD_NUMBER" 2>/dev/null)
+
+  # Try org if user fails
+  if ! echo "$FIELDS_STATE" | python3 -c "import json,sys; d=json.load(sys.stdin); _ = d['data']['user']['projectV2']" 2>/dev/null; then
+    FIELDS_STATE=$(gh api graphql -f query='
+      query($owner: String!, $number: Int!) {
+        organization(login: $owner) {
+          projectV2(number: $number) {
+            fields(first: 20) {
+              nodes {
+                ... on ProjectV2SingleSelectField {
+                  id
+                  name
+                  options { id name color description }
+                }
+                ... on ProjectV2Field {
+                  id
+                  name
+                  dataType
+                }
+              }
+            }
+          }
+        }
+      }
+    ' -f owner="$OWNER" -F number="$BOARD_NUMBER" 2>/dev/null)
+  fi
+
+  echo "Current fields on board:"
+  echo "$FIELDS_STATE" | python3 -c "
+import json,sys
+d = json.load(sys.stdin)
+data = d.get('data', {})
+proj = (data.get('user') or data.get('organization', {})).get('projectV2', {})
+nodes = proj.get('fields', {}).get('nodes', [])
+for node in nodes:
+    name = node.get('name', 'unknown')
+    nid = node.get('id', 'unknown')
+    opts = node.get('options')
+    if opts is not None:
+        print(f'  {name} (SINGLE_SELECT, {len(opts)} options): {nid}')
+        for opt in opts:
+            print(f'    - {opt[\"name\"]} ({opt[\"color\"]}) [{opt[\"id\"]}]')
+    else:
+        dtype = node.get('dataType', 'TEXT')
+        print(f'  {name} ({dtype}): {nid}')
+" 2>/dev/null || echo "  (could not fetch field details)"
+
+  echo ""
+```
+
+**Compare with canonical schema and identify missing options:**
+
+```bash
+  # Canonical Status options from BOARD-SCHEMA.md
+  CANONICAL_STATUS_OPTIONS='["New","Triaged","Needs Info","Needs Security Review","Discussing","Approved","Planning","Executing","Verifying","PR Created","Done","Failed","Blocked"]'
+
+  # Get current Status option names
+  CURRENT_STATUS_OPTIONS=$(echo "$FIELDS_STATE" | python3 -c "
+import json,sys
+d = json.load(sys.stdin)
+data = d.get('data', {})
+proj = (data.get('user') or data.get('organization', {})).get('projectV2', {})
+nodes = proj.get('fields', {}).get('nodes', [])
+for node in nodes:
+    if node.get('name') == 'Status' and 'options' in node:
+        print(json.dumps([o['name'] for o in node['options']]))
+        sys.exit(0)
+print('[]')
+" 2>/dev/null || echo "[]")
+
+  MISSING_STATUS=$(python3 -c "
+import json
+canonical = json.loads('${CANONICAL_STATUS_OPTIONS}')
+current = json.loads('''${CURRENT_STATUS_OPTIONS}''')
+missing = [o for o in canonical if o not in current]
+if missing:
+    print('Missing Status options: ' + ', '.join(missing))
+else:
+    print('Status field: all options present')
+" 2>/dev/null)
+
+  echo "Schema comparison:"
+  echo "  ${MISSING_STATUS}"
+
+  # Canonical GSD Route options
+  CANONICAL_GSD_OPTIONS='["quick","quick --full","plan-phase","new-milestone"]'
+
+  CURRENT_GSD_OPTIONS=$(echo "$FIELDS_STATE" | python3 -c "
+import json,sys
+d = json.load(sys.stdin)
+data = d.get('data', {})
+proj = (data.get('user') or data.get('organization', {})).get('projectV2', {})
+nodes = proj.get('fields', {}).get('nodes', [])
+for node in nodes:
+    if node.get('name') == 'GSD Route' and 'options' in node:
+        print(json.dumps([o['name'] for o in node['options']]))
+        sys.exit(0)
+print('[]')
+" 2>/dev/null || echo "[]")
+
+  MISSING_GSD=$(python3 -c "
+import json
+canonical = json.loads('${CANONICAL_GSD_OPTIONS}')
+current = json.loads('''${CURRENT_GSD_OPTIONS}''')
+missing = [o for o in canonical if o not in current]
+if missing:
+    print('Missing GSD Route options: ' + ', '.join(missing))
+else:
+    print('GSD Route field: all options present')
+" 2>/dev/null)
+
+  echo "  ${MISSING_GSD}"
+  echo ""
+
+  # Check for missing text fields
+  CURRENT_FIELD_NAMES=$(echo "$FIELDS_STATE" | python3 -c "
+import json,sys
+d = json.load(sys.stdin)
+data = d.get('data', {})
+proj = (data.get('user') or data.get('organization', {})).get('projectV2', {})
+nodes = proj.get('fields', {}).get('nodes', [])
+print(json.dumps([n.get('name') for n in nodes]))
+" 2>/dev/null || echo "[]")
+
+  REQUIRED_TEXT_FIELDS='["AI Agent State","Milestone","Phase"]'
+  MISSING_TEXT=$(python3 -c "
+import json
+required = json.loads('${REQUIRED_TEXT_FIELDS}')
+current = json.loads('''${CURRENT_FIELD_NAMES}''')
+missing = [f for f in required if f not in current]
+if missing:
+    print('Missing text fields: ' + ', '.join(missing))
+else:
+    print('Text fields: all present')
+" 2>/dev/null)
+
+  echo "  ${MISSING_TEXT}"
+  echo ""
+
+  # Report: no automated field addition (GitHub Projects v2 API does not support
+  # updating existing single-select field options — must delete and recreate)
+  echo "Note: GitHub Projects v2 GraphQL does not support adding options to an"
+  echo "existing single-select field. To add new pipeline stages:"
+  echo "  1. Delete the existing Status field on the board UI"
+  echo "  2. Run /mgw:board create (idempotency check will be skipped for fields)"
+  echo "  Or: manually add options via GitHub Projects UI at ${BOARD_URL}"
+  echo ""
+  echo "For missing text fields, run /mgw:board create (it will create missing fields)."
+
+fi  # end configure subcommand
+```
+</step>