powerhouse-rp-toolkit/scripts/README.md

Renaissance Periodization Training Toolkit for PowerHouseATX

# PowerHouse Tracker Scripts

## Overview

This directory contains utility scripts for auditing and converting the PowerHouse Tracker UI inventory.

## Scripts

### 1. collect-ui-inventory.js
Generates the UI inventory using Playwright and saves it to `buttons.json`.

**Usage:**
```bash
node scripts/collect-ui-inventory.js
```

**Purpose:** Automates opening the app, scraping buttons and inputs, and exporting the JSON inventory.

**Features:**
- Headless Chromium via Playwright
- Section, form, and handler metadata
- Categorization by button ID patterns
- Saves to `buttons.json`

### 2. report-missing-handlers.js
Identifies buttons with missing event handlers from the inventory.

**Usage:**
```bash
node scripts/report-missing-handlers.js
```

**Purpose:** Scans `buttons.json` and reports buttons where `hasHandler` is false OR `handlerName` is "(none)".

**Features:**
- Filters buttons missing handlers
- Shows expected handler function names
- Provides section-by-section breakdown
- Calculates handler coverage percentage
- Suggests next steps for implementation

### 3. convert-inventory-to-md.js
Converts the JSON inventory into comprehensive markdown audit tables.

**Usage:**
```bash
node scripts/convert-inventory-to-md.js
```

**Prerequisites:** Requires `buttons.json` file generated by `collect-ui-inventory.js`

## Complete Workflow

```bash
npm run dev
node scripts/collect-ui-inventory.js
node scripts/convert-inventory-to-md.js buttons.json
node scripts/report-missing-handlers.js
```

### Review Generated Files
The conversion creates two comprehensive audit tables:

## Generated Files

### BUTTON_MASTER_TABLE.md
Complete button inventory with these exact columns:
- **Section**: Workflow phase or form section
- **Button ID**: Unique button identifier  
- **Label**: Display text on button
- **Form**: Parent form/calculator name
- **Inputs**: Related input fields (comma-separated)
- **Category**: Auto-categorized type (RP Algorithms, Live Monitoring, etc.)
- **RP Book Reference**: *(blank - to be filled manually)*
- **Formula Accuracy**: *(blank - to be filled manually)*  
- **Handler**: JavaScript function/method
- **Works?**: ✅/❌/⚠️ status indicator
- **Priority**: *(blank - to be filled manually)*
- **Notes**: *(blank - to be filled manually)*

### CALCULATOR_AUDIT.md
Calculator analysis with these exact columns:
- **Calculator**: Form/calculator name
- **Purpose**: Auto-detected or manual purpose
- **RP Book Formula**: *(blank - to be filled manually)*
- **Current Implementation**: Summary of algorithms/actions
- **Accuracy**: *(blank - to be filled manually)*
- **Test Cases**: *(blank - to be filled manually)*
- **Notes**: *(blank - to be filled manually)*

Plus detailed breakdown of each calculator's components.

## Input File Structure

The script expects `buttons.json` with this structure:

```json
{
  "buttons": [
    {
      "id": "btnExample",
      "label": "Example Button", 
      "section": "Phase 1 · Foundation Setup",
      "calculator": "Volume Landmarks",
      "form": "volumeCard",
      "handler": "exampleFunction()"
    }
  ],
  "inputs": [
    {
      "id": "exampleInput",
      "name": "Example Input",
      "type": "number",
      "form": "volumeCard",
      "calculator": "Volume Landmarks"
    }
  ],
  "algorithms": [
    {
      "name": "exampleAlgorithm",
      "function": "exampleFunction()",
      "category": "RP Algorithms", 
      "calculator": "Volume Landmarks",
      "purpose": "Example calculation"
    }
  ]
}
```

## Features

### Auto-Categorization
Buttons are automatically categorized based on naming patterns:
- **RP Algorithms**: RP, Algorithm keywords
- **Live Monitoring**: Live, Session keywords
- **Auto-Progression**: Auto, Progression keywords  
- **AI/Intelligence**: Intelligence, AI keywords
- **Analysis**: Deload, Analysis keywords
- **Configuration**: Setup, Config keywords
- **Volume Management**: Volume, Frequency keywords
- **Foundation/Mesocycle/Weekly/Daily**: Based on section names

### Handler Status Detection
- ✅ **Working**: Contains "✅" or "working" in handler info
- ⚠️ **Stub**: Contains "stub" or "placeholder" 
- ❌ **Missing**: No handler or broken implementation

### Smart Grouping
- Buttons sorted by Section, then Button ID
- Calculators grouped by shared forms/sections
- Related inputs automatically linked to calculators

## Next Steps

After generation:
1. Fill in RP Book Reference columns with specific formula citations
2. Add Formula Accuracy ratings (High/Medium/Low)
3. Set Priority levels (Critical/High/Medium/Low)
4. Add Test Cases for calculator validation
5. Include implementation Notes and observations

This creates a comprehensive audit trail for RP methodology compliance and UI functionality.