@snipcodeit/mgw 0.2.2 → 0.3.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/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>