moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.github/workflows/spec-issue-sync.yml

@@ -25,33 +25,62 @@ jobs:
 
       - name: Find and parse SPEC file
         id: spec
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -x  # Enable debug mode
 
-          # Debug: Show current directory and files
-          echo "=== Debug: Current directory ==="
-          pwd
-          ls -la
+          echo "=== STEP 1: Get PR branch name ==="
+          branch_name="${{ github.head_ref }}"
+          echo "Branch: $branch_name"
 
-          echo "=== Debug: Looking for .moai/specs ==="
-          ls -la .moai/ 2>&1 || echo ".moai/ directory not found"
+          echo ""
+          echo "=== STEP 2: Get changed files from PR ==="
+          # Get list of changed files from PR
+          changed_files=$(gh pr view ${{ github.event.pull_request.number }} --json files --jq '.files[].path' 2>&1)
+
+          if [ $? -ne 0 ]; then
+            echo "⚠️  Failed to fetch PR files, falling back to git diff"
+            changed_files=$(git diff --name-only origin/main HEAD 2>&1)
+          fi
 
-          # Find SPEC files in the PR
-          echo "=== Debug: Searching for SPEC files ==="
-          find . -name "spec.md" -type f 2>&1 || echo "find command failed"
+          echo "Changed files:"
+          echo "$changed_files"
 
-          spec_file=$(find .moai/specs -name "spec.md" -type f 2>&1 | head -1)
-          echo "Found spec_file: [$spec_file]"
+          echo ""
+          echo "=== STEP 3: Find SPEC files that were actually changed ==="
+          # Find spec files that were actually modified in this PR
+          spec_files=$(echo "$changed_files" | grep -E '\.moai/specs/SPEC-.*/spec\.md$' || true)
 
-          if [ -z "$spec_file" ]; then
-            echo "⚠️  No SPEC file found in .moai/specs"
+          if [ -z "$spec_files" ]; then
+            echo "⚠️  No SPEC file changes detected in this PR"
             echo "Exiting gracefully (this is expected if no SPEC files changed)"
             exit 0
           fi
 
-          echo "✅ Found SPEC file: $spec_file"
+          echo "Found SPEC files:"
+          echo "$spec_files"
+
+          # Count SPEC files
+          spec_file_count=$(echo "$spec_files" | wc -l)
+          echo "Count: $spec_file_count"
+
+          if [ "$spec_file_count" -gt 1 ]; then
+            echo ""
+            echo "⚠️  WARNING: Multiple SPEC files detected in this PR"
+            echo "   This is unusual. Using first SPEC file."
+            echo "   Files:"
+            echo "$spec_files" | sed 's/^/     /'
+          fi
+
+          # Select first SPEC file
+          spec_file=$(echo "$spec_files" | head -1)
+          echo ""
+          echo "✅ Selected SPEC file: $spec_file"
           echo "spec_file=$spec_file" >> $GITHUB_OUTPUT
 
+          echo ""
+          echo "=== STEP 4: Extract YAML metadata ==="
           # Extract YAML metadata using grep
           spec_id=$(grep "^id:" "$spec_file" | sed 's/^id: *//' | tr -d ' "')
           spec_version=$(grep "^version:" "$spec_file" | sed 's/^version: *//' | tr -d ' "')
@@ -59,7 +88,6 @@ jobs:
           spec_priority=$(grep "^priority:" "$spec_file" | sed 's/^priority: *//' | tr -d ' "')
 
           # Extract title from H1 heading
-          spec_title=$(grep "^# @SPEC:" "$spec_file" | sed 's/^# @SPEC:[^:]*: //')
 
           echo "✅ Extracted SPEC metadata:"
           echo "  ID: $spec_id"
@@ -68,13 +96,93 @@ jobs:
           echo "  Status: $spec_status"
           echo "  Priority: $spec_priority"
 
+          echo ""
+          echo "=== STEP 5: Validate SPEC status ==="
+          # Skip if SPEC is already completed (historical document)
+          if [ "$spec_status" = "completed" ]; then
+            echo "⚠️  SPEC status is 'completed' (historical document)"
+            echo "   Skipping issue creation for completed SPEC"
+            exit 0
+          fi
+
+          echo "✅ SPEC status is valid (not completed)"
+
+          echo ""
+          echo "=== STEP 6: Validate branch name matches SPEC ID ==="
+          # Extract SPEC ID from branch name (feature/SPEC-UPDATE-REFACTOR-002 -> UPDATE-REFACTOR-002)
+          branch_spec_id=$(echo "$branch_name" | grep -oE 'SPEC-[A-Z0-9_-]+' | sed 's/^SPEC-//' || true)
+
+          if [ -n "$branch_spec_id" ]; then
+            if [ "$branch_spec_id" != "$spec_id" ]; then
+              echo "⚠️  WARNING: Branch name mismatch!"
+              echo "   Branch SPEC ID: $branch_spec_id"
+              echo "   File SPEC ID:   $spec_id"
+              echo "   Continuing anyway (might be intentional)"
+            else
+              echo "✅ Branch name matches SPEC ID"
+            fi
+          else
+            echo "⚠️  Could not extract SPEC ID from branch name"
+            echo "   Branch: $branch_name"
+            echo "   Continuing anyway"
+          fi
+
+          echo ""
+          echo "=== STEP 7: Output all variables ==="
           echo "spec_id=$spec_id" >> $GITHUB_OUTPUT
           echo "spec_version=$spec_version" >> $GITHUB_OUTPUT
           echo "spec_status=$spec_status" >> $GITHUB_OUTPUT
           echo "spec_priority=$spec_priority" >> $GITHUB_OUTPUT
           echo "spec_title=$spec_title" >> $GITHUB_OUTPUT
 
-      - name: Create GitHub Issue
+      - name: Check for existing issue
+        if: steps.spec.outputs.spec_id
+        id: check-issue
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          spec_id="${{ steps.spec.outputs.spec_id }}"
+
+          echo "=== Checking for existing issue ==="
+          echo "Searching for existing GitHub issue with SPEC-$spec_id..."
+
+          # PRIMARY: Search with label filter (efficient)
+          echo "  Attempt 1: Searching with 'spec' label filter..."
+          existing_issue=$(gh issue list \
+            --label "spec" \
+            --state all \
+            --search "[SPEC-$spec_id]" \
+            --json number,title,state \
+            --jq '.[] | select(.title | contains("[SPEC-'$spec_id']")) | .number' \
+            2>/dev/null | head -1)
+
+          # FALLBACK: Search without label filter (in case labels missing)
+          if [ -z "$existing_issue" ]; then
+            echo "  Attempt 2: Searching WITHOUT label filter (fallback for missing labels)..."
+            existing_issue=$(gh issue list \
+              --state all \
+              --search "[SPEC-$spec_id]" \
+              --json number,title,state,labels \
+              --jq '.[] | select(.title | contains("[SPEC-'$spec_id']")) | .number' \
+              2>/dev/null | head -1)
+
+            if [ -n "$existing_issue" ]; then
+              echo "  ⚠️  Found issue without 'spec' label, adding labels..."
+              # Add missing labels to existing issue
+              gh issue edit "$existing_issue" --add-label "spec,planning" 2>/dev/null || true
+            fi
+          fi
+
+          if [ -n "$existing_issue" ]; then
+            echo "✅ Found existing issue: #$existing_issue"
+            echo "issue_exists=true" >> $GITHUB_OUTPUT
+            echo "issue_number=$existing_issue" >> $GITHUB_OUTPUT
+          else
+            echo "📋 No existing issue found for SPEC-$spec_id"
+            echo "issue_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create or Update GitHub Issue
         if: steps.spec.outputs.spec_id
         id: create-issue
         env:
@@ -86,6 +194,8 @@ jobs:
           spec_status="${{ steps.spec.outputs.spec_status }}"
           spec_priority="${{ steps.spec.outputs.spec_priority }}"
           spec_file="${{ steps.spec.outputs.spec_file }}"
+          issue_exists="${{ steps.check-issue.outputs.issue_exists }}"
+          existing_issue="${{ steps.check-issue.outputs.issue_number }}"
 
           # Read SPEC content (skip YAML frontmatter: 9 lines + 1 blank = 10 lines total)
           # Start reading from line 11
@@ -114,33 +224,93 @@ jobs:
             echo "📝 **Auto-synced**: This issue is automatically synchronized from the SPEC document"
           } > /tmp/issue_body.txt
 
-          echo "📋 Creating GitHub Issue..."
-          echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
-          echo "  Body file: /tmp/issue_body.txt"
-          wc -l /tmp/issue_body.txt
+          if [ "$issue_exists" = "true" ]; then
+            echo "📝 Updating existing issue #$existing_issue..."
+            echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
+            echo "  Labels: spec, planning, $spec_priority"
 
-          # Create issue with labels using body-file
-          issue_output=$(gh issue create \
-            --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
-            --body-file /tmp/issue_body.txt \
-            --label "spec" \
-            --label "planning" \
-            --label "$spec_priority" 2>&1)
+            # Update existing issue with new content and ensure proper labels
+            gh issue edit "$existing_issue" \
+              --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
+              --body-file /tmp/issue_body.txt \
+              --add-label "spec,planning,$spec_priority" \
+              --state open
+
+            issue_num=$existing_issue
+            echo "✅ Updated issue #$issue_num with latest SPEC version"
+          else
+            echo "📋 Creating new GitHub Issue..."
+            echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
+            echo "  Body file: /tmp/issue_body.txt"
+            wc -l /tmp/issue_body.txt
+
+            # Create issue with labels using body-file
+            issue_output=$(gh issue create \
+              --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
+              --body-file /tmp/issue_body.txt \
+              --label "spec" \
+              --label "planning" \
+              --label "$spec_priority" 2>&1)
 
-          echo "$issue_output" | tee /tmp/issue_output.txt
+            echo "$issue_output" | tee /tmp/issue_output.txt
 
-          # Extract issue number from output
-          issue_num=$(echo "$issue_output" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+' | head -1)
+            # Extract issue number from output
+            issue_num=$(echo "$issue_output" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+' | head -1)
 
-          if [ -z "$issue_num" ]; then
-            echo "⚠️  Could not extract issue number from output"
-            echo "Full output:"
-            cat /tmp/issue_output.txt
-            exit 1
+            if [ -z "$issue_num" ]; then
+              echo "⚠️  Could not extract issue number from output"
+              echo "Full output:"
+              cat /tmp/issue_output.txt
+              exit 1
+            fi
+
+            echo "✅ Created issue #$issue_num"
           fi
 
           echo "issue_number=$issue_num" >> $GITHUB_OUTPUT
-          echo "✅ Created issue #$issue_num"
+
+      - name: Validate SPEC issue labels
+        if: steps.create-issue.outputs.issue_number
+        id: validate-labels
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          issue_num="${{ steps.create-issue.outputs.issue_number }}"
+          spec_priority="${{ steps.spec.outputs.spec_priority }}"
+
+          echo "🔍 Validating SPEC issue #$issue_num labels..."
+
+          # Get current labels
+          current_labels=$(gh issue view $issue_num --json labels --jq '.labels[].name' | tr '\n' ',' | sed 's/,$//')
+          echo "Current labels: $current_labels"
+
+          # Check for mandatory labels
+          needs_update=false
+
+          if [[ ! "$current_labels" =~ "spec" ]]; then
+            echo "⚠️  Missing 'spec' label, adding..."
+            gh issue edit $issue_num --add-label "spec"
+            needs_update=true
+          fi
+
+          if [[ ! "$current_labels" =~ "planning" ]]; then
+            echo "⚠️  Missing 'planning' label, adding..."
+            gh issue edit $issue_num --add-label "planning"
+            needs_update=true
+          fi
+
+          # Check for priority label
+          if [[ ! "$current_labels" =~ (critical|high|medium|low) ]]; then
+            echo "⚠️  No priority label found, adding '$spec_priority' as default"
+            gh issue edit $issue_num --add-label "$spec_priority"
+            needs_update=true
+          fi
+
+          if [ "$needs_update" = true ]; then
+            echo "✅ SPEC labels validated and corrected"
+          else
+            echo "✅ SPEC labels already valid"
+          fi
 
       - name: Add PR comment
         if: steps.create-issue.outputs.issue_number

moai_adk/templates/.gitignore

@@ -1,41 +1,222 @@
-# Build artifacts
+# ============================================
+# MoAI-ADK Package Distribution .gitignore
+# ============================================
+# Version: 0.28.0
+# Purpose: Essential patterns for user projects
+# ============================================
+
+# ---------------------------------------------
+# Build Artifacts
+# ---------------------------------------------
 build/
 dist/
 *.egg-info/
 *.egg
 
-# Cache
+# ---------------------------------------------
+# Python Cache & Database
+# ---------------------------------------------
 __pycache__/
 .pytest_cache/
 *.pyc
 *.pyo
-node_modules/
-*.tsbuildinfo
-.tscache/
+*.pyd
+.mypy_cache/
+.ruff_cache/
+*.db
+*.sqlite
+*.sqlite3
+*.rdb
+*.dbm
 
-# Backups
-
-# Virtual environment
+# ---------------------------------------------
+# Virtual Environments
+# ---------------------------------------------
 venv/
 .venv/
 env/
 .env/
+.uv_cache/
+.uv-cache/
 
-# IDE
+# ---------------------------------------------
+# IDE & Editors
+# ---------------------------------------------
 .vscode/
 .idea/
 *.swp
 *.swo
+*.sw?
 *~
+.cursor/
+*.sublime-project
+*.sublime-workspace
+*.njsproj
+*.sln
+*.suo
+.#*
 
-# OS
+# ---------------------------------------------
+# OS Files
+# ---------------------------------------------
+# Mac
 .DS_Store
+.AppleDouble
+.LSOverride
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+
+# Windows
+[Dd]esktop.ini
 Thumbs.db
+ehthumbs.db
+
+# Linux
+.directory
 
-# Logs
+# ---------------------------------------------
+# Node.js (for docs/Nextra)
+# ---------------------------------------------
+node_modules/
+*.tsbuildinfo
+.tscache/
+.next/
+out/
+
+# ---------------------------------------------
+# Logs & Temporary Files
+# ---------------------------------------------
 *.log
 logs/
-
-# Temporary files
 *.tmp
 *.temp
+*.bak
+*.backup
+
+# ---------------------------------------------
+# Test Coverage
+# ---------------------------------------------
+.coverage
+coverage.json
+htmlcov/
+.pytest_cache/
+
+# ---------------------------------------------
+# Environment Variables & Secrets
+# ---------------------------------------------
+.env
+.env.*
+!.env.example
+
+# Certificate files
+*.pem
+*.p12
+*.pfx
+*.jks
+
+# Private keys and certificates (specific patterns to avoid false positives)
+# FIXED: Issue #237 - Replaced overly broad *key* and *secret* patterns
+# Old patterns caused false positives for: keyboard-config, hotkey, monkey-patch, etc.
+*-key.*
+*_key.*
+*.key.*
+*-secret-key.*
+*-api-key.*
+api-key-*
+secret-key-*
+private-key*
+*-secret.*
+*_secret.*
+*.secret.*
+secret-*.*
+
+# API credentials patterns
+*_secret=*
+*_token=*
+
+# Cloud provider credentials
+.aws/config
+.aws/credentials
+.vercel/
+.netlify/
+.firebase/
+
+# Claude Code Skills Secrets
+.claude/skills/*/.env*
+.claude/skills/*/secrets/
+.claude/skills/*/*/*secret*
+.claude/skills/*/*/*key*
+.claude/skills/*/*/*token*
+
+# ---------------------------------------------
+# Backups
+# ---------------------------------------------
+.moai-backups/
+*.backup/
+*-backup/
+*_backup_*/
+
+# ---------------------------------------------
+# Claude Code Local Configuration
+# ---------------------------------------------
+.claude/settings.local.json
+.claude/settings.local.*.json
+.claude/.env.local*
+.claude/local/
+
+# ---------------------------------------------
+# MoAI Directory Management
+# ---------------------------------------------
+# Tracked in git: config/, memory/, scripts/, specs/
+# User-generated content: logs/, cache/, reports/, etc.
+
+.moai/*
+!.moai/config/
+!.moai/config/**
+!.moai/memory/
+!.moai/memory/**
+!.moai/scripts/
+!.moai/scripts/**
+!.moai/specs/
+!.moai/specs/**
+
+# Legacy config format (migrated to YAML in v0.32.0)
+.moai/config/config.json
+
+# .moai local-only directories (user projects only)
+.moai/cache/
+.moai/logs/
+.moai/docs/
+.moai/reports/
+.moai/analytics/
+.moai/archive/
+.moai/archived-skills/
+.moai/backups/
+.moai/error_logs/
+.moai/temp/
+.moai/work/
+
+# .moai local development scripts (not distributed)
+.moai/scripts/phase*.py
+.moai/scripts/phase*.sh
+.moai/scripts/sync-*.sh
+.moai/scripts/sync-*.py
+.moai/scripts/*sync*.sh
+.moai/scripts/__pycache__/
+
+# ---------------------------------------------
+# CI/CD
+# ---------------------------------------------
+.github/workflows/*.yml.bak
+.gitlab-ci.yml.bak
+
+# ---------------------------------------------
+# Package Distribution
+# ---------------------------------------------
+# uv.lock is intentionally included for reproducible builds
+# Add to .gitignore if needed per project
+# uv.lock

moai_adk/templates/.mcp.json

@@ -0,0 +1,31 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp@latest"
+      ]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    },
+    "figma-dev-mode-mcp-server": {
+      "type": "sse",
+      "url": "http://127.0.0.1:3845/sse"
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking@latest"
+      ]
+    }
+  },
+  "staggeredStartup": {
+    "enabled": true,
+    "delayMs": 500,
+    "connectionTimeout": 15000
+  }
+}

moai_adk/templates/.moai/config/config.yaml

@@ -0,0 +1,58 @@
+# MoAI-ADK Configuration
+# Format: YAML (modular section-based configuration)
+#
+# This is the main configuration file that references modular section files.
+# Each section is stored in a separate file under .moai/config/sections/
+# for better maintainability and token efficiency.
+#
+# Section Files:
+# - sections/user.yaml: User personalization settings
+# - sections/language.yaml: Language preferences
+# - sections/project.yaml: Project metadata
+# - sections/git-strategy.yaml: Git workflow configuration
+# - sections/quality.yaml: TDD and quality settings
+# - sections/system.yaml: MoAI system settings
+#
+# CLAUDE.md automatically loads:
+# @.moai/config/sections/user.yaml
+# @.moai/config/sections/language.yaml
+
+moai:
+  version: "0.34.0"
+  initialized: true
+  initialized_at: "2025-12-19T00:00:00Z"
+
+# Document Management System
+# Prevents project root pollution by enforcing .moai/ hierarchy for all internal files
+document_management:
+  enabled: true
+  enforce_structure: true
+  block_root_pollution: true
+
+  # Separation policy between logs and docs
+  separation_policy:
+    strict_separation: true
+    description: Clear separation between logs (runtime data) and docs (documentation content)
+    logs_scope: runtime sessions, errors, execution traces, agent transcripts
+    docs_scope: reports, analysis, validation, sync, inspection, documentation files
+
+  # Directory structure and retention policies
+  directories:
+    # Documentation files
+    docs:
+      base: .moai/docs/
+      retention_days: null # Keep indefinitely
+    # Log files (runtime data)
+    logs:
+      base: .moai/logs/
+      retention_days: 30
+    # Temporary files
+    temp:
+      base: .moai/temp/
+      retention_days: 7
+      auto_cleanup: true
+    # Cache files
+    cache:
+      base: .moai/cache/
+      retention_days: 30
+      auto_cleanup: true