Pow3r Ecosystem v3.0 - X-FILES Edition

A fully autonomous, schema-driven ecosystem for discovering, analyzing, and visualizing Git repositories with self-healing capabilities and real-time anomaly detection.

Status: ✅ v3.0 X-FILES SYSTEM ACTIVE
Live Demo: 🌐 thewatchmen.pages.dev
Constitution: 📜 Project Phoenix Constitution v3.0
X-FILES: 🔍 In-Situ Triage & Action Console for system anomaly detection

Overview

The Pow3r Ecosystem v3.0 provides a fully autonomous, self-healing workflow:

• 🔍 Discover - Scan directories for Git repositories
• ✅ Select - Interactively choose repos to analyze
• 📊 Analyze - Deep analysis of Git history and code structure
• 🎨 Visualize - Interactive 3D network visualization with "Data as Light" philosophy
• 📈 Monitor - Real-time development status and activity tracking
• 🔧 Self-Heal - Automatic anomaly detection and repair via X-FILES system
• 📋 Case Files - Comprehensive bug reports, feature requests, and system anomaly tracking

Quick Start

Local Repository Analysis

cd "/Users/creator/Documents/DEV/Repo to 3D"

# 1. Select repositories (Phase 0)
python analyze.py /Users/creator/Documents/DEV

# 2. Analyze repositories (Phase 1) 
python run_phase1.py --markdown "selection.md" --base-path "/path"

# 3. Launch 3D visualization (Phase 2)
./start-visualization.sh

GitHub Integration (NEW!)

# Set your GitHub token
export GITHUB_TOKEN=your_github_token

# Interactive setup
python setup_github_integration.py

# Or scan directly
python github_scanner.py --token $GITHUB_TOKEN --org your-organization
python github_scanner.py --token $GITHUB_TOKEN --repo owner/repo

# Aggregate all data
python data_aggregator.py

→ See QUICKSTART.md for detailed steps
→ See GitHub Integration Guide

Installation

Requirements

• Python 3.7+
• Git installed and accessible from command line
• Unix-like terminal with ANSI color support (macOS, Linux, or WSL)

Setup

cd /Users/creator/Documents/DEV/repo-analyzer
chmod +x analyze.py

Usage

Basic Usage

python analyze.py /path/to/root/directory

Examples

# Scan your entire DEV directory
python analyze.py ~/Documents/DEV

# Scan a specific projects folder
python analyze.py ~/dev/projects

# Use absolute path
python analyze.py /Users/creator/Documents/DEV

CloudFlare Deployment (NEW!)

Deploy the entire system to CloudFlare with automatic GitHub webhook integration:

# Deploy to CloudFlare Pages
wrangler pages deploy public

# Configure webhooks for automatic updates
# See GITHUB_INTEGRATION_COMPLETE.md for details

The CloudFlare workers automatically:

• 🔄 Update when repositories change
• 📊 Generate power.status.json files
• 🌐 Serve aggregated data via API
• ⚡ Cache for optimal performance

Features

X-FILES System (NEW in v3.0!)

• In-Situ Triage & Action Console - Real-time anomaly detection and self-healing
• Case File Management - Comprehensive bug reports, feature requests, and system anomaly tracking
• Self-Healing Protocol - Automatic root cause analysis and repair dispatch
• Constitutional Enforcement - Guardian agent validation of all system operations
• Real-time Monitoring - Continuous observability with session recording

GitHub Integration & CloudFlare Workers

• Automatic Repository Scanning - Scan entire GitHub organizations
• Webhook Integration - Auto-update on push, PR, issues
• CloudFlare Workers - Serverless processing and API
• Real-time Updates - Changes reflected immediately

Phase 0: Repository Selection

The tool provides an interactive CLI interface with the following features:

1. Automatic Repository Discovery

• Recursively scans directory trees
• Identifies all directories containing .git folders
• Skips hidden directories (except .git)
• Handles permission errors gracefully

2. Repository Metadata Collection

For each repository found, the tool gathers:

• Name: Repository directory name
• Path: Absolute and relative paths
• Branch: Current Git branch
• Remote: Git remote URL (if configured)
• Last Commit: Date of most recent commit
• File Count: Total number of files (excluding .git)
• Size: Total repository size in MB

3. Interactive Selection Interface

Multiple selection methods:

• Individual: 1 3 5 - Select specific repositories
• Range: 1-10 - Select a range of repositories
• All: all - Select all repositories
• None: none - Clear all selections
• Done: done - Confirm selection and proceed

4. Visual Feedback

• Color-coded terminal output
• Selection indicators (✓)
• Progress messages
• Summary statistics

5. Data Persistence

Saves selection to JSON file:

{
  "timestamp": "2025-10-02T...",
  "total_selected": 5,
  "repositories": [...]
}

Interactive Selection Commands

Command	Description
1 3 5	Select repositories 1, 3, and 5
1-5	Select repositories 1 through 5
1-5 8 10-12	Combine ranges and individual numbers
all	Select all repositories
none	Clear all selections
done	Finish selection and proceed
quit or q	Exit without saving

Output

Console Output

🔍 Scanning for Git repositories in: /Users/creator/Documents/DEV
Please wait...

✓ Found 25 repositories

Found 25 Git repositories:

[✓]   1. PowerFlow
      Path: PowerFlow
      Branch: main | Files: 418 | Size: 15.3 MB
      Last commit: 2025-10-01 14:23:15 -0700

[ ]   2. Expunge
      Path: Expunge
      Branch: develop | Files: 479 | Size: 8.7 MB
      Last commit: 2025-09-28 09:45:32 -0700
...

JSON Output

Selection saved to: .repo-analyzer/selected_repositories_[timestamp].json

{
  "timestamp": "2025-10-02T10:30:45.123456",
  "total_selected": 3,
  "repositories": [
    {
      "name": "PowerFlow",
      "path": "/Users/creator/Documents/DEV/PowerFlow",
      "relative_path": "PowerFlow",
      "branch": "main",
      "remote": "git@github.com:user/powerflow.git",
      "last_commit": "2025-10-01 14:23:15 -0700",
      "file_count": 418,
      "size_mb": 15.3
    }
  ]
}

Architecture

The A-TEAM system operates as a fully autonomous multi-agent workflow with comprehensive v3 status schema mapping. See V3 Architecture Mapping for complete details.

Core Components

1. RepositoryScanner: Discovers and analyzes repositories

   • scan(): Recursively walks directory tree
   • _analyze_repository(): Gathers metadata for each repo
   • _get_git_info(): Extracts Git branch and remote
   • _get_last_commit_date(): Gets last commit timestamp
   • _get_file_stats(): Calculates file counts and sizes

2. InteractiveSelector: Handles user interaction

   • display_repositories(): Shows formatted repository list
   • interactive_select(): Runs selection loop
   • _parse_selection(): Parses user input (ranges, lists)

3. Output Functions:

   • save_selection(): Persists selection to JSON
   • display_summary(): Shows selection statistics

Design Principles

• No External Dependencies: Uses only Python standard library
• Graceful Error Handling: Continues on permission errors
• User-Friendly Output: Color-coded, formatted terminal output
• Fast Scanning: Efficient directory traversal
• Cross-Platform: Works on macOS, Linux, WSL

Error Handling

The tool handles common errors gracefully:

• Permission Denied: Skips directories without access
• Invalid Path: Validates directory existence
• Git Errors: Falls back to "unknown" for missing Git info
• Keyboard Interrupt: Clean exit on Ctrl+C

Project Phases

This tool is divided into distinct phases:

Phase 0: Repository Selection ✅ COMPLETE

• Interactive CLI for repository discovery
• Metadata collection (branch, files, size, commits)
• Selection and filtering
• Output to JSON

Phase 1: Repository Analysis & Data Generation ✅ COMPLETE

• Git history analysis (commits, branches, tags)
• Development status inference (green/orange/red/gray)
• Code structure analysis (language, architecture)
• Component identification (nodes and edges)
• Configuration generation (dev-status.config.json)

→ See Phase 1 Guide for detailed documentation

Phase 2: 3D Visualization Web Application ✅ COMPLETE

• Local web server (Node.js/Express)
• Three.js 3D graph visualization
• Interactive node exploration with click details
• Status-based color coding (green/orange/red/gray)
• Real-time statistics dashboard
• Smooth camera controls (rotate, pan, zoom)
• RESTful API with caching
• Responsive glassmorphism UI

→ See Phase 2 Guide for detailed documentation

Phase 3: GitHub Integration & CloudFlare ✅ COMPLETE

• GitHub Repository Scanner - Analyze any GitHub repo or organization
• Automatic Status Updates - CloudFlare workers monitor repo changes
• Real-time Synchronization - Webhooks trigger immediate updates
• Cloud-based Processing - No local scanning required
• Multi-source Aggregation - Combines local and GitHub data
• Scalable Architecture - CloudFlare KV and R2 storage

→ See GitHub Integration Guide

X-FILES System & Constitution

Project Phoenix Constitution v3.0

The Pow3r Ecosystem operates under the Project Phoenix Constitution v3.0, which establishes:

• Prime Directive: Build and maintain a fully autonomous, schema-driven ecosystem
• Data as Light Philosophy: UI as the living, luminous embodiment of underlying data
• Full-Auto Mandate: Operate autonomously without human intervention
• Schema Supremacy: pow3r.config.json as the single source of truth
• Constitutional Enforcement: Guardian agent with veto authority

X-FILES In-Situ Triage & Action Console

The X-FILES system provides:

• Real-time Anomaly Detection: Continuous monitoring for system violations
• Case File Creation: Automatic generation of comprehensive dossiers
• Self-Healing Protocol: Root cause analysis and repair dispatch
• Constitutional Compliance: Validation against constitutional articles
• Status Lifecycle: Open → InProgress → PendingValidation → Closed

Phase 4: X-FILES System & Self-Healing ✅ COMPLETE

• In-Situ Triage & Action Console - Real-time anomaly detection interface
• Case File Management - Bug reports, feature requests, system anomalies
• Self-Healing Protocol - Automatic root cause analysis and repair
• Constitutional Enforcement - Guardian agent validation system
• Real-time Observability - Continuous monitoring with session recording

Phase 5: Advanced Features 📋 FUTURE

• Actual dependency graph parsing
• Time-based commit animations
• Multiple layout algorithms
• Export to image/video formats
• Team collaboration features
• AI-powered insights

Troubleshooting

Permission Errors

# If you encounter permission errors, try:
sudo python analyze.py /path/to/directory

Git Not Found

# Ensure Git is installed:
git --version

# Install Git if needed:
# macOS: brew install git
# Linux: sudo apt-get install git

ANSI Colors Not Displaying

# Some terminals don't support ANSI colors
# Try using a modern terminal like iTerm2, Terminal.app, or Windows Terminal

Contributing

To extend this tool:

1. Add new analysis methods to RepositoryScanner
2. Enhance metadata collection in _analyze_repository()
3. Add new selection features to InteractiveSelector
4. Implement Phase 1 analysis functions

License

See parent directory LICENSE file.

Links

• Parent README
• Project: Part of the Local Repository Analysis & Generation Tool suite