{"id":31230837,"url":"https://github.com/alteriom/repository-metadata-manager","last_synced_at":"2026-01-20T17:03:45.127Z","repository":{"id":311969317,"uuid":"1045819228","full_name":"Alteriom/repository-metadata-manager","owner":"Alteriom","description":"Complete repository compliance and health management suite for GitHub repositories","archived":false,"fork":false,"pushed_at":"2025-09-06T18:28:04.000Z","size":657,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T20:31:16.505Z","etag":null,"topics":["alteriom","automation","branch-protection","ci-cd","compliance","description","documentation","github","github-integration","health-score","metadata","npm-package","organization-tools","repository","security","topics"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Alteriom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-27T18:55:49.000Z","updated_at":"2025-09-06T18:27:48.000Z","dependencies_parsed_at":"2025-08-28T03:56:15.294Z","dependency_job_id":"5f4ef421-a7be-44c3-a0d2-3f76fff33f9f","html_url":"https://github.com/Alteriom/repository-metadata-manager","commit_stats":null,"previous_names":["alteriom/repository-metadata-manager"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Alteriom/repository-metadata-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alteriom%2Frepository-metadata-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alteriom%2Frepository-metadata-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alteriom%2Frepository-metadata-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alteriom%2Frepository-metadata-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alteriom","download_url":"https://codeload.github.com/Alteriom/repository-metadata-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alteriom%2Frepository-metadata-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276383424,"owners_count":25632653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-22T02:00:08.972Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alteriom","automation","branch-protection","ci-cd","compliance","description","documentation","github","github-integration","health-score","metadata","npm-package","organization-tools","repository","security","topics"],"created_at":"2025-09-22T10:13:06.491Z","updated_at":"2026-01-20T17:03:45.088Z","avatar_url":"https://github.com/Alteriom.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Repository Metadata Manager\n\n[![npm version](https://img.shields.io/npm/v/@alteriom/repository-metadata-manager.svg)](https://www.npmjs.com/package/@alteriom/repository-metadata-manager)\n[![npm downloads](https://img.shields.io/npm/dt/%40alteriom%2Frepository-metadata-manager.svg)](https://www.npmjs.com/package/@alteriom/repository-metadata-manager)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n[![CI](https://github.com/Alteriom/repository-metadata-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/Alteriom/repository-metadata-manager/actions/workflows/ci.yml)\n[![Security](https://github.com/Alteriom/repository-metadata-manager/actions/workflows/security.yml/badge.svg)](https://github.com/Alteriom/repository-metadata-manager/actions/workflows/security.yml)\n[![Release](https://github.com/Alteriom/repository-metadata-manager/actions/workflows/release.yml/badge.svg)](https://github.com/Alteriom/repository-metadata-manager/actions/workflows/release.yml)\n[![Repository Health](\u003chttps://img.shields.io/badge/health-A%20(96%25)-brightgreen.svg\u003e)](https://github.com/Alteriom/repository-metadata-manager)\n\n## 🚀 Complete Repository Compliance and Health Management Suite for GitHub Organizations\n\nA comprehensive utility for managing GitHub repository metadata, security, documentation, CI/CD pipelines, and overall repository health to ensure compliance with organization standards.\n\n## 🎯 Purpose\n\nThis enterprise-grade tool addresses comprehensive repository management needs:\n\n- **📊 Repository Health Scoring**: Calculate overall repository health with weighted scoring\n- **🔒 Security Management**: Security audits, vulnerability detection, and policy enforcement\n- **🛡️ Branch Protection**: Automated branch protection rule management\n- **📚 Documentation Standards**: Quality analysis and auto-generation of documentation\n- **⚙️ CI/CD Pipeline Management**: Workflow analysis and template generation\n- **🎯 Compliance Automation**: Full compliance checking with auto-fix capabilities\n- **🤖 AI Agent Mode**: Zero-configuration automation for CI/CD and AI agents\n- **🔄 Cross-Repository Automation**: Organization-wide health monitoring and dependency tracking\n- **📋 Interactive Management**: User-friendly CLI with guided workflows\n- **🧠 MCP Server**: Model Context Protocol server for AI assistants (GitHub Copilot, Claude) ✨ NEW\n\n## 📦 Installation\n\n### Option 1: Install as NPM Package (Recommended)\n\n```bash\nnpm install --save-dev @alteriom/repository-metadata-manager\n```\n\n### Option 2: Global Installation\n\n```bash\nnpm install -g @alteriom/repository-metadata-manager\n```\n\n## 🚀 Quick Start\n\n### 1. Create Configuration File\n\nCreate a `metadata-config.json` file:\n\n```json\n{\n    \"organizationTag\": \"myorg\"\n}\n```\n\n### 2. Add to package.json scripts\n\n```json\n{\n    \"scripts\": {\n        \"health\": \"repository-manager health\",\n        \"security\": \"repository-manager security --audit\",\n        \"compliance\": \"repository-manager compliance\"\n    }\n}\n```\n\n### 3. Calculate repository health\n\n```bash\nnpm run health\n```\n\n### 4. Run full compliance check\n\n```bash\n# View compliance report\nnpm run compliance\n\n# Apply automatic fixes\nnpm run compliance --fix\n```\n\n### 5. Interactive mode\n\n```bash\nnpm run interactive\n```\n\n### 6. Organization Analytics\n\n```bash\n# Generate comprehensive organization report\nnpm run analytics\n\n# Export analytics to file\nrepository-manager analytics --save organization-report.json\n```\n\n### 7. Project Templates\n\n```bash\n# List available templates\nnpm run template -- --list\n\n# Generate IoT firmware project\nnpm run template -- --type iot-firmware --name my-sensor-project\n\n# Generate AI agent project\nnpm run template -- --type ai-agent --name my-automation-agent\n```\n\n### 8. Enhanced Automation ✨ NEW\n\n```bash\n# Run organization-wide health audit\nnpm run automation:org-health\n\n# Detect missing workflows across all repos\nnpm run automation:detect-workflows\n\n# Track dependencies across organization\nnpm run automation:track-deps\n\n# Generate compliance report with auto-save\nnpm run automation:compliance\n\n# Generate security vulnerability dashboard\nnpm run automation:security\n\n# Run automated maintenance tasks\nnpm run automation:maintenance\n\n# Auto-fix compliance issues (dry-run)\nnpm run automation:dry-run\n\n# Auto-fix compliance issues (apply changes)\nnpm run automation:auto-fix\n```\n\n### 9. MCP Server for AI Assistants ✨ NEW\n\n**Use repository management tools directly in GitHub Copilot, Claude, and other AI assistants** via Model Context Protocol:\n\n```bash\n# Install MCP server dependencies\ncd mcp-server \u0026\u0026 npm install\n\n# Server automatically activates in VS Code\n# Open GitHub Copilot Chat → Agent mode → Tools icon\n# You'll see 13 repository management tools available\n\n# Example prompts:\n\"Calculate health score for this repository\"\n\"What documentation is missing?\"\n\"Run security audit\"\n\"Auto-fix compliance issues (dry-run first)\"\n```\n\n**Features:**\n- 13 tools for health, security, docs, CI/CD, compliance\n- Natural language interface through AI assistants\n- Organization-wide operations\n- Auto-fix capabilities with dry-run\n- See `mcp-server/README.md` for full documentation\n\n### 10. AI Agent Mode ✨ NEW\n\n**Zero-configuration compliance automation** for AI agents and CI/CD environments:\n\n```bash\n# Detect environment and token availability\nrepository-manager ai-agent --detect\n\n# Run in local-only mode (no GitHub API required)\nrepository-manager ai-agent --local-only\n\n# Dry-run mode - show what would be fixed\nrepository-manager ai-agent --dry-run\n\n# Auto-fix compliance issues\nrepository-manager ai-agent --auto-fix\n\n# Full automation (local fixes + API checks)\nrepository-manager ai-agent --auto-fix\n```\n\n**Key Features:**\n\n- 🔑 **Automatic Token Detection**: Hierarchical token detection (Environment → GitHub Actions → .env file)\n- 🤖 **GitHub Actions Integration**: Automatic detection and configuration when running in CI/CD\n- 📁 **Local File Fixes**: Create missing documentation (SECURITY.md, CONTRIBUTING.md, etc.)\n- 🔧 **Auto-Fix Capabilities**: Automated compliance fixes without manual intervention\n- 🛡️ **Graceful Degradation**: Works even without GitHub API access\n\n**Example: GitHub Actions Workflow**\n\n```yaml\nname: Compliance Check\non: [pull_request, push]\n\njobs:\n  compliance:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n      - run: npm install -g @alteriom/repository-metadata-manager\n      - run: repository-manager ai-agent --auto-fix\n        env:\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\nSee [AI Agent Workflow](.github/workflows/ai-agent-compliance.yml) for the complete automated workflow.\n\n## 📋 Enhanced Commands\n\n| Command           | Description                                                         |\n| ----------------- | ------------------------------------------------------------------- |\n| `health`          | Calculate overall repository health score (0-100)                   |\n| `security`        | Security audit and vulnerability detection                          |\n| `branches`        | Branch protection analysis and enforcement                          |\n| `docs`            | Documentation quality assessment and generation                     |\n| `cicd`            | CI/CD workflow analysis and template generation                     |\n| `iot`             | IoT-specific compliance and template generation                     |\n| `compliance`      | Full compliance check with auto-fix capabilities                    |\n| `ai-agent`        | AI agent mode with automatic token detection and local fixes ✨ NEW |\n| `automation`      | Cross-repository operations and organization-wide automation        |\n| `interactive`     | Interactive wizard for guided repository management                 |\n| `analytics`       | Organization-wide analytics and insights                            |\n| `template`        | Generate new projects from comprehensive templates                  |\n| `security-policy` | Generate and manage security policies                               |\n\n## 🎨 Project Template Engine\n\nThe Repository Metadata Manager now includes a comprehensive template engine for rapid project scaffolding, specifically designed for Alteriom organization patterns.\n\n### Available Templates\n\n| Template Type  | Language   | Description                                          |\n| -------------- | ---------- | ---------------------------------------------------- |\n| `iot-firmware` | C++        | ESP32/ESP8266 firmware with sensors, LoRa, WiFi mesh |\n| `ai-agent`     | JavaScript | AI-powered automation and repository management      |\n| `iot-platform` | TypeScript | Multi-tenant IoT platform with React + FastAPI       |\n| `cli-tool`     | JavaScript | Command-line tools with comprehensive features       |\n\n### Template Features\n\n**IoT Firmware Template:**\n\n- Complete PlatformIO configuration for ESP32/ESP8266\n- Sensor management (DHT22, BMP280, custom sensors)\n- WiFi connectivity with automatic reconnection\n- MQTT communication for telemetry\n- LoRa mesh networking support\n- OTA update capabilities\n- Hardware documentation templates\n- Security and encryption modules\n\n**AI Agent Template:**\n\n- GitHub API integration with Octokit\n- Automated compliance monitoring\n- Issue and PR creation capabilities\n- Configurable automation workflows\n- Comprehensive test suite\n- Docker deployment configuration\n\n**IoT Platform Template:**\n\n- React TypeScript frontend with modern UI\n- FastAPI Python backend with async support\n- MQTT integration for real-time data\n- InfluxDB time-series data storage\n- Redis caching and session management\n- Multi-tenant architecture\n- Grafana dashboard configurations\n- Docker Compose for local development\n\n### Usage Examples\n\n```bash\n# Interactive template generation\nnpm run interactive\n# Select \"🎨 Generate New Project\"\n\n# Command line usage\nnpm run template -- --type iot-firmware --name weather-station\nnpm run template -- --type ai-agent --name compliance-bot\nnpm run template -- --type iot-platform --name sensor-dashboard\n\n# List all available templates\nnpm run template -- --list\n```\n\n| `iot` | IoT-specific compliance and template generation |\n| `compliance` | Full compliance check with auto-fix capabilities |\n| `interactive` | Interactive wizard for guided repository management |\n\n## 🔌 IoT Repository Management\n\nSpecialized features for IoT/embedded systems development, designed for organizations like Alteriom with extensive IoT portfolios.\n\n### IoT Repository Types\n\nThe tool automatically detects and handles four types of IoT repositories:\n\n- **🔧 IoT Firmware** (`iot-firmware`): ESP32/ESP8266, Arduino, PlatformIO projects\n- **🖥️ IoT Server** (`iot-server`): MQTT backends, sensor data processing, telemetry\n- **📚 IoT Documentation** (`iot-documentation`): Hardware specs, API docs, setup guides\n- **🐳 IoT Infrastructure** (`iot-infrastructure`): Docker containers, deployment configs\n\n### IoT Commands\n\n```bash\n# Run IoT-specific compliance audit\nnpm run iot\n\n# Generate IoT project templates\nrepository-manager iot --template firmware    # ESP32/Arduino firmware\nrepository-manager iot --template server      # Python/FastAPI MQTT server\nrepository-manager iot --template infrastructure  # Docker deployment\nrepository-manager iot --template documentation   # IoT project docs\n```\n\n### IoT Compliance Scoring\n\nIoT repositories get specialized scoring based on:\n\n- **Firmware Projects**: PlatformIO config, security headers, OTA updates, hardware docs\n- **Server Projects**: MQTT handlers, database schemas, API documentation, monitoring\n- **Documentation**: Hardware specs, setup guides, troubleshooting, examples\n- **Infrastructure**: Container configs, monitoring, security policies, deployment scripts\n\n### IoT Template Structures\n\n**Firmware Template Features:**\n\n- PlatformIO configuration for ESP32/ESP8266\n- Security and encryption modules\n- WiFi and MQTT connectivity\n- Sensor management and calibration\n- OTA update mechanisms\n- Hardware documentation templates\n\n**Server Template Features:**\n\n- FastAPI with MQTT integration\n- InfluxDB time-series data storage\n- Redis caching and session management\n- Grafana dashboard configurations\n- Docker containerization\n- API documentation and testing\n\n**Example IoT Audit Output:**\n\n```bash\n🔌 Starting IoT-Specific Compliance Audit...\n\n✅ IoT repository detected\n\n📊 IoT Compliance Score: 85/100\n🎯 Repository Type: iot-firmware\n\n🔧 IoT Files Detected:\n  • platformio.ini\n  • src/main.cpp\n  • include/config.h\n  • lib/sensors/\n\n✅ Compliance Findings:\n  ✅ PlatformIO configuration found\n  ✅ Main firmware file found\n  ✅ Header files directory found\n  ✅ Documentation found\n\n💡 Recommendations:\n  • Add security header file (include/security.h)\n  • Add OTA update configuration\n  • Include hardware compatibility matrix\n\n🔒 Security Recommendations:\n  • Consider adding cryptographic functions\n  • Implement WiFi credential security\n  • Add MQTT authentication\n```\n\n## 📊 Organization Analytics\n\nComprehensive analytics and insights across all repositories in your organization, providing detailed visibility into health, compliance, and technology adoption patterns.\n\n### Analytics Features\n\n- **Repository Health Overview**: Aggregated health scores and grade distribution\n- **Language \u0026 Technology Analysis**: Usage patterns and technology adoption\n- **IoT Portfolio Insights**: Specialized analysis for IoT/embedded projects\n- **Security Posture Assessment**: Organization-wide security metrics\n- **Compliance Trends**: Tracking compliance improvements over time\n- **Actionable Recommendations**: Prioritized suggestions for improvement\n\n### Analytics Commands\n\n```bash\n# Generate comprehensive organization report\nnpm run analytics\n\n# Export analytics to JSON\nrepository-manager analytics --export json --save org-report.json\n\n# Export analytics to CSV for spreadsheet analysis\nrepository-manager analytics --export csv --save org-metrics.csv\n```\n\n### Sample Analytics Output\n\n```\n🏢 ALTERIOM ORGANIZATION ANALYTICS REPORT\n============================================================\n\n📊 ORGANIZATION OVERVIEW\nTotal Repositories: 12\nPrivate/Public: 8/4\nAverage Health Score: 87/100\nTotal Stars: 156\nTotal Forks: 23\nOpen Issues: 14\n\n💻 LANGUAGE DISTRIBUTION\n  JavaScript: 5 repositories (42%)\n  C++: 4 repositories (33%)\n  TypeScript: 2 repositories (17%)\n  Python: 1 repositories (8%)\n\n🔌 IOT PORTFOLIO ANALYSIS\nTotal IoT Repositories: 6\nAverage IoT Health: 92/100\nTop IoT Technologies:\n  • esp32: 4 projects\n  • mqtt: 4 projects\n  • platformio: 3 projects\n  • sensors: 3 projects\n\n🎯 KEY RECOMMENDATIONS\n  1. 🔴 [Security] Implement organization-wide security policies\n  2. 🟡 [Documentation] 3 repositories missing descriptions\n  3. 🟡 [IoT] Consider creating shared IoT libraries\n```\n\n## 🤖 Enhanced Automation ✨ NEW\n\nPowerful cross-repository automation features for organization-wide management and monitoring.\n\n### Automation Features\n\n- **Organization Health Monitoring**: Daily automated health audits across all repositories\n- **Workflow Detection**: Automatically detect repositories missing critical CI/CD workflows\n- **Dependency Tracking**: Monitor and coordinate dependency versions across all repositories\n- **Compliance Reporting**: Generate org-wide compliance reports with critical issue tracking ✨ NEW\n- **Security Dashboard**: Track security vulnerabilities across all repositories ✨ NEW\n- **Automated Maintenance**: Run scheduled maintenance tasks (stale issues, outdated deps, unused workflows) ✨ NEW\n- **Compliance Auto-Fix**: Automatically fix common compliance issues\n- **Automated Reporting**: Generate comprehensive reports and create GitHub issues for issues needing attention\n\n### Automation Commands\n\n```bash\n# Run organization-wide health audit\nnpm run automation:org-health\n\n# Detect missing workflows across all repositories\nnpm run automation:detect-workflows\n\n# Track dependencies and identify version conflicts\nnpm run automation:track-deps\n\n# Generate compliance report (saved to compliance-report-YYYY-MM-DD.json)\nnpm run automation:compliance\n\n# Generate security vulnerability dashboard (saved to security-dashboard-YYYY-MM-DD.json)\nnpm run automation:security\n\n# Run automated maintenance tasks (stale issues, outdated deps, unused workflows)\nnpm run automation:maintenance\n\n# Auto-fix compliance issues (preview mode)\nnpm run automation:dry-run\n\n# Auto-fix compliance issues (apply changes)\nnpm run automation:auto-fix\n```\n\n### New Automation Features ✨\n\n#### 📋 Compliance Report Generation\n\nGenerate comprehensive organization-wide compliance reports with:\n\n- **Health Score Analysis**: Average health scores across all repositories\n- **Compliance Status**: Count of compliant (≥80) vs non-compliant (\u003c80) repositories\n- **Critical Issue Tracking**: Identifies repositories with critical security issues\n- **Auto-Save Reports**: Reports saved to `compliance-report-YYYY-MM-DD.json`\n\n**Example Output:**\n```\n📊 Compliance Summary:\nTotal Repositories: 29\nCompliant (≥80): 1\nNon-Compliant (\u003c80): 28\nAverage Health Score: 38.7\nCritical Security Issues: 25\n```\n\n#### 🔒 Security Dashboard\n\nGenerate security vulnerability dashboards tracking:\n\n- **Security Scoring**: Categorize repositories by security level (secure ≥80, critical \u003c50)\n- **Vulnerability Count**: Track total vulnerable repositories\n- **Priority Levels**: High priority (\u003c70) and critical (\u003c50) repositories\n- **Actionable Recommendations**: Specific security improvements needed\n- **Auto-Save Dashboards**: Saved to `security-dashboard-YYYY-MM-DD.json`\n\n**Example Output:**\n```\n🔒 Security Overview:\nTotal Repositories: 29\nSecure (≥80): 3\nVulnerable (\u003c80): 26\nCritical Issues (\u003c50): 22\n\n💡 Recommendations:\n  1. Immediate action required for repositories with critical security issues\n  2. Review and update security policies for vulnerable repositories\n```\n\n#### 🔧 Automated Maintenance Tasks\n\nRun scheduled maintenance tasks across all repositories:\n\n- **Stale Issue Detection**: Find issues inactive for 90+ days\n- **Outdated Dependency Tracking**: Identify repositories with outdated dependencies\n- **Unused Workflow Detection**: Find unused or obsolete CI/CD workflows\n- **Configurable Tasks**: Run specific tasks with `--tasks` parameter\n\n**Task Options:**\n```bash\n# Run all maintenance tasks (default)\nnpm run automation:maintenance\n\n# Run specific tasks only\nrepository-manager automation --maintenance --tasks stale-issues,outdated-deps\nrepository-manager automation --maintenance --tasks unused-workflows\n```\n\n**Example Output:**\n```\n📌 Running task: stale-issues\nFound 0 stale issues\n\n📌 Running task: outdated-deps\nChecked 5 repositories for outdated dependencies\n\n📌 Running task: unused-workflows\nFound 31 workflows across repositories\n```\n\n### Automated Workflow\n\nThe organization health monitor runs automatically via GitHub Actions:\n\n- **Schedule**: Daily at 6 AM UTC\n- **Monitors**: All repositories in the organization\n- **Reports**: Health scores, missing workflows, dependency conflicts, compliance status\n- **Alerts**: Automatic GitHub issues for repositories below health threshold\n\n### Automation Output Example\n\n```\n🔍 Running Organization-Wide Health Audit...\n\nFound 27 repositories\n\n[A] repository-metadata-manager: 96/100\n[B] alteriom-mqtt-schema: 88/100\n[C] alteriom-firmware: 72/100\n[F] alteriom-data-analytics: 45/100\n\n📊 Health Audit Summary:\nTotal Repositories: 27\nUnhealthy (\u003c 70): 5\nAverage Health Score: 82.3\n\n⚠️  Unhealthy Repositories:\n  - alteriom-data-analytics (45/100): 8 issues\n  - alteriom-config-manager (52/100): 6 issues\n```\n\nFor complete automation documentation, see [AUTOMATION.md](docs/AUTOMATION.md).\n\n## 🛡️ Security Policy Management\n\nComprehensive security policy generation and management for enterprise-grade security standards across all repository types.\n\n### Security Policy Types\n\n| Policy Type    | Description                               | Use Case              |\n| -------------- | ----------------------------------------- | --------------------- |\n| `organization` | Standard organizational security policy   | All repositories      |\n| `iot`          | Enhanced IoT device and firmware security | IoT/embedded projects |\n| `ai-agent`     | AI agent and automation security          | AI/automation systems |\n| `web-platform` | Web application security policy           | Web applications      |\n\n### Security Policy Features\n\n**Organization Policy:**\n\n- Vulnerability disclosure procedures\n- Incident response planning\n- Security contact information\n- Compliance guidelines\n- Supported versions matrix\n\n**IoT Policy:**\n\n- Hardware security requirements\n- Firmware security standards\n- Device authentication protocols\n- Secure communication guidelines\n- OTA update security\n\n**AI Agent Policy:**\n\n- API security standards\n- Data privacy protection\n- Automation security controls\n- GitHub integration security\n\n**Web Platform Policy:**\n\n- Authentication and authorization\n- Data protection standards\n- Web application security\n- HTTPS/TLS requirements\n\n### Security Commands\n\n```bash\n# Audit existing security policies\nnpm run security-policy -- --audit\n\n# Generate organization security policy\nnpm run security-policy -- --generate --type organization\n\n# Generate IoT-specific security policy\nnpm run security-policy -- --generate --type iot --contact security@yourorg.com\n```\n\n### Generated Security Files\n\n**Standard Organization Policy:**\n\n- `SECURITY.md` - Main security policy\n- `.github/SECURITY.md` - GitHub security integration\n- `docs/security/SECURITY_GUIDELINES.md` - Detailed guidelines\n- `docs/security/VULNERABILITY_DISCLOSURE.md` - Disclosure procedures\n- `docs/security/INCIDENT_RESPONSE.md` - Response procedures\n\n**IoT-Specific Policy:**\n\n- Enhanced device security requirements\n- Firmware security standards\n- Hardware security guidelines\n- Secure communication protocols\n\n### Usage Examples\n\n```bash\n# Interactive security policy management\nnpm run interactive\n# Select \"🛡️ Security Policy Management\"\n\n# Command line usage\nrepository-manager security-policy --audit\nrepository-manager security-policy --generate --type iot\nrepository-manager security-policy --generate --type organization --contact security@alteriom.com\n```\n\n### Sample Security Audit Output\n\n```\n🔒 Security Policy Score: 85/100\n\n✅ SECURITY.md file\n✅ GitHub security policy\n✅ Security documentation\n❌ Security workflow\n   Fix: Add automated security scanning workflow\n\n💡 Recommendations:\n  1. Add vulnerability disclosure timeline section\n  2. Include emergency contact procedures\n  3. Implement automated security scanning\n```\n\n### Original Metadata Commands\n\n| Command    | Description                                             |\n| ---------- | ------------------------------------------------------- |\n| `report`   | Generate compliance report with recommendations         |\n| `validate` | Check if current metadata meets compliance requirements |\n| `dry-run`  | Preview what changes would be made                      |\n| `apply`    | Apply recommended changes (requires GitHub token)       |\n\n## ⚙️ Configuration\n\n### Environment Variables (.env file) - Recommended\n\nCreate a `.env` file for local development:\n\n```bash\n# Copy the example file\ncp .env.example .env\n\n# Edit with your tokens\nNPM_TOKEN=npm_your_token_here\nGITHUB_TOKEN=ghp_your_github_token_here\nORGANIZATION_TAG=alteriom\n```\n\nAll CLI commands will automatically load the `.env` file. See [ENVIRONMENT.md](ENVIRONMENT.md) for detailed setup instructions.\n\n### Configuration File (Alternative)\n\nCreate a `metadata-config.json` file:\n\n```json\n{\n    \"organizationTag\": \"myorg\",\n    \"organizationName\": \"My Organization\",\n    \"packagePath\": \"./package.json\",\n    \"repositoryType\": \"auto-detect\",\n    \"customTopics\": {\n        \"ai-agent\": [\"automation\", \"github-integration\", \"compliance\"],\n        \"api\": [\"api\", \"backend\", \"server\"],\n        \"frontend\": [\"frontend\", \"ui\", \"web\"],\n        \"cli-tool\": [\"cli\", \"tool\", \"command-line\"],\n        \"library\": [\"library\", \"package\", \"sdk\"],\n        \"general\": [\"utility\"]\n    }\n}\n```\n\n### Environment Variables\n\n```bash\n# GitHub API access\nGITHUB_TOKEN=ghp_your_token_here\n# or\nAGENT_ORG_TOKEN=ghp_your_token_here\n\n# Repository identification (auto-detected from git if not set)\nGITHUB_REPOSITORY_OWNER=your-org\nGITHUB_REPOSITORY_NAME=your-repo-name\n```\n\n### Command Line Options\n\n```bash\nrepository-metadata report --owner myorg --repo my-repo --org-tag myorg --token ghp_xxx\n```\n\n| Option           | Description                 | Default                       |\n| ---------------- | --------------------------- | ----------------------------- |\n| `--owner`        | Repository owner            | Auto-detected from git remote |\n| `--repo`         | Repository name             | Auto-detected from git remote |\n| `--token`        | GitHub API token            | From environment variables    |\n| `--package-path` | Path to package.json        | `./package.json`              |\n| `--org-tag`      | Organization tag for topics | **REQUIRED**                  |\n| `--config`       | Configuration file path     | None                          |\n\n## 🏗️ How It Works\n\n1. **Reads** your `package.json` for description and keywords\n2. **Analyzes** repository type (ai-agent, api, frontend, library, etc.)\n3. **Generates** appropriate topics based on content and type\n4. **Validates** current GitHub repository metadata\n5. **Provides** exact values and instructions for fixes\n\n## 📖 Example Output\n\n```bash\n$ npm run metadata:report\n\n🔍 Generating repository metadata compliance report...\n\n📋 Current Repository Metadata:\n  Description: \"\"\n  Topics: []\n\n📦 Package.json Metadata:\n  Description: \"AI-powered repository review agent\"\n  Keywords: [ai-agent, automation, github]\n\n❌ Compliance Issues Found:\n  • Missing repository description\n  • Missing repository topics/tags for discoverability\n\n🎯 Recommended Changes:\n  Description: \"AI-powered repository review agent\"\n  Topics: [myorg, ai-agent, automation, github, github-integration, compliance]\n```\n\n- **ai-agent**: automation, github-integration, compliance\n- **api**: api, backend, server\n- **frontend**: frontend, ui, web\n- **cli-tool**: cli, tool, command-line\n- **library**: library, package, sdk\n- **general**: utility\n\n## 🎨 Manual Setup Instructions\n\nIf you can't use npm scripts, you can run the tool directly:\n\n```bash\n# Using npx\nnpx @alteriom/repository-metadata-manager report\n\n# Using node (if files copied locally)\nnode scripts/utility/repository-metadata-manager.js report\n```\n\n## 🏢 Organization-Wide Deployment\n\n### For Repository Maintainers\n\n1. **Add to package.json**:\n\n    ```bash\n    npm install --save-dev @alteriom/repository-metadata-manager\n    ```\n\n2. **Add scripts**:\n\n    ```json\n    {\n        \"scripts\": {\n            \"metadata:report\": \"alteriom-metadata report\",\n            \"metadata:validate\": \"alteriom-metadata validate\",\n            \"metadata:apply\": \"alteriom-metadata apply\",\n            \"metadata:dry-run\": \"alteriom-metadata dry-run\"\n        }\n    }\n    ```\n\n3. **Run compliance check**:\n\n    ```bash\n    npm run metadata:validate\n    ```\n\n### For Organization Admins\n\n1. **Create organization template** with the tool pre-installed\n2. **Add to CI/CD** to automatically check compliance\n3. **Use in GitHub Actions** for automated compliance checking\n\n## 📝 Example GitHub Actions Integration\n\n```yaml\nname: Repository Compliance Check\non: [push, pull_request]\n\njobs:\n    metadata-compliance:\n        runs-on: ubuntu-latest\n        steps:\n            - uses: actions/checkout@v4\n            - uses: actions/setup-node@v4\n              with:\n                  node-version: '18'\n            - run: npm install\n            - run: npm run metadata:validate\n              env:\n                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n## 🤝 Contributing\n\nThis tool is designed to be extended and customized for your organization's needs:\n\n1. **Fork** or copy the package\n2. **Modify** the `generateRecommendedTopics()` method for your topic strategy\n3. **Update** the `organizationTag` configuration\n4. **Customize** validation rules in `validateMetadata()`\n\n## 🧪 Testing \u0026 Development\n\n### Test Suites\n\nThe project includes comprehensive testing with different levels:\n\n```bash\n# Run all tests (including unstable ones)\nnpm test\n\n# Run only stable core functionality tests (used for releases)\nnpm run test:core\n\n# Run unstable tests that need infrastructure fixes\nnpm run test:unstable\n\n# Run feature integration tests\nnpm run test:features\n```\n\n### Test Categories\n\n- **Core Tests** (92 tests): Stable tests covering essential functionality\n- **Feature Manager Tests**: Testing individual feature modules (may have infrastructure dependencies)\n- **CLI Integration Tests**: End-to-end command-line interface testing\n- **Enhanced CLI Tests**: Advanced CLI functionality testing\n\n### Development Workflow\n\n1. **Core functionality** is thoroughly tested and stable\n2. **Feature tests** may require additional infrastructure setup\n3. **Release process** uses only stable core tests to ensure reliability\n4. **All functionality** works as demonstrated by working npm scripts\n\n## 📄 License\n\nMIT License - feel free to use and modify for your organization.\n\n## 📚 Documentation\n\n### Central Documentation\n\nFor comprehensive documentation, guides, and organizational standards, visit the **Alteriom Documentation Repository**:\n\n🔗 **[Alteriom Central Documentation](https://github.com/Alteriom/alteriom-documentation)**\n\n### Local Documentation\n\nComprehensive documentation is available in the [`docs/`](docs/) directory and [`.github/DOCUMENTATION.md`](.github/DOCUMENTATION.md):\n\n- **[Documentation Index](.github/DOCUMENTATION.md)** - Complete documentation hub with central links\n- **[Local Documentation](docs/README.md)** - Complete local documentation overview\n- **[Environment Setup](docs/guides/ENVIRONMENT.md)** - Development environment configuration\n- **[Organization Setup](docs/guides/ORGANIZATION_SETUP.md)** - Organization-wide setup guide\n- **[CLI Reference](docs/guides/CLI.md)** - Command-line interface guide\n- **[Automation Guide](docs/AUTOMATION.md)** - Cross-repository automation features\n- **[Implementation Details](docs/development/IMPLEMENTATION_SUMMARY.md)** - Technical architecture\n- **[API Reference](docs/development/API.md)** - Detailed API documentation\n- **[Versioning Guidelines](docs/development/VERSIONING.md)** - Release management\n- **[Release Notes](docs/releases/)** - Version history and changelogs\n\n## 🆘 Support\n\n- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/Alteriom/repository-metadata-manager/issues)\n- **Documentation**: Check our comprehensive [documentation](docs/)\n- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines\n- **Organization Standards**: Refer to Alteriom organization guidelines\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falteriom%2Frepository-metadata-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falteriom%2Frepository-metadata-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falteriom%2Frepository-metadata-manager/lists"}