metabuilder/scripts

Scripts Directory

This directory contains utility scripts for the MetaBuilder project.

Scripts

Package Metadata Management

generate-package-metadata.js

Purpose: Automatically generates seed/metadata.json files for all packages that don't have them.

Features:

• 🔍 Scans all packages in /packages/ directory
• 📁 Creates seed/ directories where missing
• 🤖 Generates metadata with intelligent defaults:
  • Converts package_id to "Package Name" format
  • Auto-categorizes based on package name patterns (ui, editor, management, etc.)
  • Sets standard fields (version 0.1.0, author, etc.)
• ⏭️ Skips packages that already have metadata
• 📊 Reports detailed progress and summary

Usage:

node scripts/generate-package-metadata.js

Example output:

🔍 Scanning packages directory...
📦 Found 51 packages

⏭️  admin_dialog: metadata.json already exists
📁 arcade_lobby: created seed/ directory
✅ arcade_lobby: created metadata.json
...

============================================================
📊 Summary:
   ✅ Created: 43
   ⏭️  Skipped: 8
   ❌ Errors: 0
   📦 Total: 51
============================================================

Related Documentation:

• MVP Package Metadata Migration
• Package Metadata Schema

---

validate-package-metadata.js

Purpose: Validates all package metadata files against schema requirements.

Features:

• ✅ Validates required fields (packageId, name, version, description)
• 🔤 Checks packageId format (snake_case/kebab-case)
• 📋 Validates version format (semver)
• 🔍 Ensures packageId matches directory name
• 🎯 Verifies correct field types
• 🛡️ Validates JSON syntax

Usage:

node scripts/validate-package-metadata.js

Example output:

🔍 Validating package metadata files...

✅ admin_dialog: Valid
✅ arcade_lobby: Valid
✅ dashboard: Valid
...

============================================================
📊 Validation Summary:
   ✅ Valid: 51
   ❌ Invalid: 0
   🚫 Missing: 0
   📦 Total: 51
============================================================

✅ All metadata files are valid!

Related Documentation:

• MVP Package Metadata Migration
• Package Metadata Schema

---

GitHub Issue Management

triage-duplicate-issues.sh

Purpose: Automatically finds and closes duplicate GitHub issues while keeping the most recent one open.

Features:

• 🔍 Dynamically searches for duplicate issues using GitHub API
• 📅 Sorts issues by creation date (newest first)
• ✅ Keeps the most recent issue open as the canonical tracking issue
• 🔒 Closes all older duplicates with explanatory comments
• ⚙️ Configurable search pattern via environment variables
• 🛡️ Error handling and rate limiting protection

Usage:

# Basic usage (uses default search pattern)
export GITHUB_TOKEN="ghp_your_github_token_here"
./scripts/triage-duplicate-issues.sh

# With custom search pattern
export GITHUB_TOKEN="ghp_your_github_token_here"
export SEARCH_TITLE="Your custom issue title"
./scripts/triage-duplicate-issues.sh

# Show help
./scripts/triage-duplicate-issues.sh --help

Environment Variables:

• GITHUB_TOKEN (required): GitHub personal access token with repo access
• SEARCH_TITLE (optional): Issue title pattern to search for
  • Default: "🚨 Production Deployment Failed - Rollback Required"

How it works:

1. Searches GitHub API for all open issues matching the title pattern
2. Sorts issues by creation date (newest first)
3. Identifies the most recent issue to keep open
4. Adds an explanatory comment to each older duplicate
5. Closes older duplicates with state_reason: "not_planned"

Example output:

🔍 Searching for issues with title: "🚨 Production Deployment Failed - Rollback Required"
📊 Found 5 duplicate issues
📌 Most recent issue: #124 (created: 2025-12-27T10:30:00Z)

🔧 Starting bulk issue triage...
📋 Planning to close 4 duplicate issues
📌 Keeping issue #124 open (most recent)

📝 Adding comment to issue #122...
✅ Added comment to issue #122
🔒 Closing issue #122...
✅ Closed issue #122
...
✨ Triage complete!

---

Testing Scripts

test-triage-logic.sh

Purpose: Comprehensive test suite for the triage script logic.

Features:

• ✅ Tests multiple duplicate issues handling
• ✅ Tests two duplicate issues
• ✅ Tests single issue (should not close)
• ✅ Tests empty input handling
• ✅ Validates date sorting
• ✅ Tests jq parsing and formatting

Usage:

./scripts/test-triage-logic.sh

Example output:

🧪 Testing triage-duplicate-issues.sh logic
=============================================

Test 1: Multiple duplicate issues (should close all except most recent)
-----------------------------------------------------------------------
  Total issues found: 5
  Most recent issue: #124
  Issues to close: 122 121 119 117 
  Count to close: 4
  ✅ PASS: Correctly identified most recent and 4 issues to close
...
=============================================
✅ All tests passed!

---

Other Utilities

generate_mod.py

Purpose: Python script for generating module files.

---

Development Guidelines

Adding New Scripts

When adding new scripts to this directory:

1. Use descriptive names that clearly indicate the script's purpose
2. Add executable permissions: chmod +x script-name.sh
3. Include usage documentation in the script header
4. Add help flag support (--help or -h)
5. Handle errors gracefully with proper exit codes
6. Update this README with script documentation

Testing Scripts

• Run shellcheck on bash scripts before committing
• Create test scripts for complex logic
• Validate with sample data before using in production
• Test edge cases (empty input, single item, etc.)

Best Practices

• ✅ Use set -e to exit on errors
• ✅ Validate required environment variables
• ✅ Add descriptive comments
• ✅ Use meaningful variable names
• ✅ Include usage examples
• ✅ Handle rate limiting for API calls
• ✅ Provide clear error messages

---

Related Documentation

• Triage Summary
• Duplicate Issues Documentation