@puberty-labs/refuctor

v1.0.6

Published

5 months ago

AI-powered, snark-fueled technical debt cleansing suite with automatic snarky language detection that turns code cleanup into a darkly humorous financial metaphor.

Downloads

0High
0Medium
0Low

puberty-labs

technical-debt code-quality linting refactoring developer-tools cli automation debt-management code-cleanup mcp cursor ai-tools

Refuctor - The Debt Cleansing Syndicate

"Because even your code deserves a fresh financial start."

Tagline: "Refactor or Be Repossessed."

🎯 What is Refuctor?

Refuctor is an AI-powered, snark-fueled technical debt cleansing suite that turns code cleanup into a darkly humorous financial metaphor. It's the world's first debt management system that actually makes developers want to clean up their code.

🎯 Optimized for Cursor IDE - Native integration with AI-powered workflows, plus dedicated extension available for enhanced functionality.

🔥 Origin Story

Born from the meta-irony of a debt tracker that caught its own creator making 36 markdown warnings while building the debt detection system. We used the system to fix itself in real-time - proving that recursive debt management actually works.

✨ Core Philosophy

P1 Critical: "This is fucking embarrassing. Fix it NOW."
P2 High: "We're taking back the repo. Clean this today."
P3 Medium: "A bit crusty. Handle it this sprint."
P4 Low: "Minor blemish. But you'll pay later…"

📦 Installation

Global Installation (Recommended)


# Install globally for CLI access

npm install -g @puberty-labs/refuctor

# Verify installation

refuctor --version
```text

### **Local Installation**

```bash

# Install locally in your project

npm install --save-dev @puberty-labs/refuctor

# Use with npx

npx refuctor scan
```text

### **Cursor Extension**

```bash

# Install the dedicated Cursor extension for enhanced IDE integration

# Available through Cursor's extension marketplace

# Search for "Refuctor - The Debt Collector" in Extensions

```text

---

## 🚀 Features

### ✅ **Professional CLI Suite**

- **🚀 Comprehensive Setup Wizard**: Enhanced `refuctor init` with 6-step automated project setup
- **🌐 Real-time Web Dashboard**: Professional-grade debt monitoring at `http://localhost:1947`
- **📊 Debt Detection Engine**: Markdown linting, spell checking, security audits with MAFIA/Guido escalation levels
- **🎯 Interactive Controls**: SCAN DEBT, FIX DEBT, and NUCLEAR OPTION buttons with real-time progress updates
- **💰 Financial Metaphors**: P1-P4 debt levels with loan shark takeover warnings when debt reaches critical mass

### 🎯 **Cursor IDE Integration**

- **🤖 Native AI Assistant Integration**: Seamless integration with Cursor's AI workflows via MCP (Model Context Protocol)
- **🔌 Dedicated Extension**: Custom Cursor extension for enhanced IDE experience with real-time debt indicators
- **⚡ AI-Powered Commands**: Natural language debt scanning - just ask "scan this project for technical debt"
- **🎯 Optimized Workflows**: Built specifically for Cursor's AI-first development approach
- **📊 Status Bar Integration**: Live debt count and credit score display in IDE

### ✅ **Advanced Features**

- **⚡ Real-time WebSocket**: Live debt updates, progress tracking, critical alerts, and automated monitoring
- **🔥 Advanced Heat Maps**: File-level debt visualization with interactive hotspot analysis and temperature indicators
- **📈 Trend Analysis**: Historical debt tracking, velocity calculations, and predictive insights with real trend data
- **🧠 AI-Powered Suggestions**: Smart fix recommendations with confidence scoring and priority-based filtering
- **📱 Mobile-Responsive Design**: Touch-friendly interface with comprehensive breakpoints and landscape support
- **🔧 API Integration**: Full REST API with `/api/debt/*` endpoints for external integrations
- **📋 TECHDEBT.md Tracking**: Automated session-based debt logging with comprehensive reporting
- **🎨 Professional Branding**: Custom logo, debt-cleansing personality, responsive design
- **🔍 Session Wrap Integration**: 9-step comprehensive debt scanning protocol
- **📝 Spell Check Management**: Extensible dictionary for project-specific terms
- **🍳 Cook the Books**: Export VS Code problems to markdown when Refuctor scan misses issues
- **🧠 Project Intelligence**: Automatic framework detection (React, Vue, Angular, Node.js)
- **⚙️ Smart Configuration**: Context-aware cspell.json and .debtignore generation

### 🎯 **Dashboard Features (Production Ready)**

**The
Refuctor
dashboard at `http://localhost:1947` provides comprehensive debt management:**

- **🔥 Advanced Debt Visualization**: File-level breakdown with sorting, filtering, and pagination
- **📈 Historical Trend Analysis**: Interactive charts showing debt velocity, priority distribution, and key insights
- **🧠 Auto-Fix Integration**: Clickable debt items that trigger automated fixes via API endpoints
- **⚡ Real-time Updates**: Live debt scanning with WebSocket communication and progress tracking
- **📱 Mobile-Responsive Design**: Touch-friendly interface optimized for all device sizes
- **🎯 Performance Optimized**: Debounced search, memoized components, and efficient data handling

**Dashboard Features:**

- **File Debt Breakdown**: Interactive component showing files with debt counts, categories, and severity
- **Trend Analysis**: Historical debt visualization with tabbed interface and SVG charts
- **Search & Filter**: Debounced search with severity filtering and pagination
- **Auto-Fix Controls**: File-specific, category-specific, and global debt fixing capabilities

### 🎯 **Specialized Goons (Advanced Features)**

- **🔧 Markdown Fixer**: Automated markdown linting cleanup
- **📦 Import Cleaner**: Unused import elimination
- **💀 Comment Killer**: Remove outdated comments and dead code
- **💰 Accountant**: Credit rating system (300-850 score) with financial metaphors
- **🔧 General Fixer**: Multi-purpose debt cleanup tool

---

## 🛠️ Quick Start

### **1. Initialize Your Project**

```bash

# Navigate to your project directory

cd your-project

# Run the comprehensive setup wizard

refuctor init

# The setup wizard will:

# 🔍 Analyze your project (detect React, Vue, Angular, Node.js)

# 📝 Generate project-specific cspell.json dictionary

# 🚫 Create .debtignore file with framework-specific patterns

# 📊 Set up context-aware TECHDEBT.md with monitoring recommendations

# 💻 Configure IDE integration (Cursor workspace optimization)

# 🎯 Provide actionable next steps for debt management

```text

### **2. Scan for Debt**

```bash

# Comprehensive debt scan

refuctor scan

# Verbose output with detailed breakdown

refuctor scan --verbose

# Check project information

refuctor info
```text

### **3. Launch Dashboard (Optional)**

```bash
# Start real-time dashboard (opens automatically in browser)
refuctor serve

# Start without opening browser
refuctor serve --no-browser

# Dashboard URL: http://localhost:1947
# Shows YOUR project's debt data, trends, and hotspots

Dashboard displays:

📊 Live debt breakdown for your project files
🔥 Top hotspots with file-specific debt counts
📈 Trend analysis and debt history tracking
🎯 Interactive fixes and priority management

4. Fix Issues


# See what can be auto-fixed

refuctor fix --dry-run

# Apply automatic fixes

refuctor fix

# Use specialized goons

refuctor goon fix-markdown
refuctor goon clean-imports
refuctor goon comment-killer
```text

### **5. 🍳 Cook the Books (When Refuctor Misses Issues)**

When VS Code shows problems that Refuctor scan doesn't detect:

```bash

# Export VS Code problems to markdown report

refuctor cook

# Custom output file

refuctor cook --output my-debt-report.md

# Different formats

refuctor cook --format json
refuctor cook --format csv
```text

**What "Cook the Books" does:**

- 🍳 Runs markdownlint with JSON output (catches markdown issues)
- 📝 Runs cspell for spelling issues (with detailed reporting)
- 💻 Runs TypeScript checks if applicable
- 📊 Exports everything to readable markdown with file breakdown
- 🎯 Shows top problem files and recommended actions

### **🔍 Un-Cook the Books (`refuctor uncook`)**

The opposite of "cooking" - reveals what's really hiding in ignored files:

```bash
# Process ignored files in manageable chunks
refuctor uncook

# Customize processing
refuctor uncook --chunks 5 --max-chunks 10 --max-files 25

Processing Modes:

📦 Chunked Processing: Fixed batch sizes (default 10 files/batch)
🤝 Interactive Processing: User controls each batch with continue/pause/stop
🧠 Smart Prioritization: AI picks most interesting files (READMEs → package.json → docs)

What Un-Cook Does:

🔍 Discovers ignored files in node_modules, build/, dist/, .cache/
📊 Processes files in performance-safe chunks with timeout protection
🎯 Finds hidden debt in typically ignored locations
📋 Provides manageable reporting without overwhelming output
⚡ Prevents buffer overflow issues with massive file processing

Perfect for auditing what's really in your project beyond the main source files.

**🎯 Snarky Intelligence (`refuctor snarky-*`)**

Advanced spelling analysis that distinguishes between actual typos and intentional snarky language:

# Analyze spelling issues with AI intelligence
refuctor snarky-scan

# Add legitimate snarky terms to project dictionary
refuctor snarky-add "refuctor" "puberty-labs" "bitchuation"

# Fix real typos while preserving snarky language
refuctor snarky-fix

What Snarky Intelligence Does:

🧠 AI-powered analysis distinguishes typos from intentional terminology
📝 Automatically adds project-specific terms to dictionary
🎯 Fixes genuine mistakes while preserving brand language
💡 Learns from your project's terminology patterns

⚙️ Mode Management (`refuctor mode`)

Configure debt classification to match your project type and team culture:

# Show current mode and available options
refuctor mode

# Switch to startup mode (high tolerance, fast development)
refuctor mode startup

# Switch to enterprise mode (strict standards)
refuctor mode enterprise

# Auto-detect best mode for your project
refuctor mode auto-detect

Available Modes:

🚀 STARTUP: High tolerance, move fast and break things
👥 DEV_CREW: Balanced approach for development teams
🏢 ENTERPRISE: Strict standards and comprehensive documentation
🎓 LEARNING: Educational feedback for skill development

🎮 Gamification System (`refuctor gamification`)

Track your debt-elimination progress with achievements and streaks:

# View current progress and achievements
refuctor gamification

# Detailed achievement breakdown
refuctor gamification --detailed

# Team leaderboard (if available)
refuctor gamification --leaderboard

📦 Dependency Management (`refuctor dependencies`)

Check for missing dependencies and get installation suggestions:

# Check for missing dependencies
refuctor dependencies

# Get specific installation commands for your project
refuctor dependencies --install

🚫 Ignore Management (`refuctor ignore`)

Manage .debtignore patterns for files you want excluded from debt tracking:

# List current ignore patterns
refuctor ignore list

# Add new ignore pattern
refuctor ignore add "*.generated.js"

# Remove ignore pattern
refuctor ignore remove "old-pattern"

# Initialize .debtignore with common patterns
refuctor ignore init

📋 Available Commands

Core Commands

refuctor init            # Initialize project with setup wizard
refuctor scan            # Scan for technical debt
refuctor fix             # Auto-fix common issues
refuctor serve           # Launch real-time dashboard
refuctor info            # Show project analysis
refuctor status          # Show current debt status and trends
refuctor wrap            # Session wrap protocol
refuctor cook            # Export VS Code problems
refuctor uncook          # Un-cook the books: audit ignored files

Advanced Commands

refuctor snarky-scan     # Analyze spelling with snarky intelligence
refuctor snarky-add      # Add snarky terms to dictionary
refuctor snarky-fix      # Fix typos while preserving snarky language
refuctor mode            # Manage debt classification mode
refuctor ignore          # Manage .debtignore patterns
refuctor dependencies    # Check missing dependencies
refuctor mcp-server      # Start MCP server for AI integration

Goon Commands (Specialized Tools)

refuctor goon            # Deploy all specialized goons
refuctor accountant      # Developer credit rating (300-850)
refuctor comment-killer  # Remove dead comments and TODOs  
refuctor import-cleaner  # Eliminate unused imports
refuctor exterminate     # AGGRESSIVE: Deploy all goons simultaneously
refuctor gamification   # Track achievements and progress

Fun Commands

refuctor shame           # Generate humorous debt report
refuctor guido           # Demonstrate MAFIA → Guido escalation
refuctor bailmeout       # Emergency motivation quotes

🧪 Proven Results

Real-World Testing

The complete system has successfully eliminated:

173 markdown warnings across documentation files
15 spell check issues with preserved snarky terminology
34 additional warnings caught during system self-testing
310+ VS Code problems exported and addressed via "Cook the Books" feature
Total: 532+ warnings eliminated with zero false positives

Advanced Dashboard Performance

The professional-grade dashboard provides:

Real-time heat maps showing debt temperature analysis
Historical trend tracking with persistent storage
Live WebSocket monitoring with <1 second response time
Mobile-responsive design tested across 5 breakpoint ranges

Meta Validation

The debt tracker caught its own creator making debt while building it, then used itself to clean up the mess AND created a professional dashboard to visualize the cleanup process in real-time. This recursive validation proves the concept works in practice.

🎨 Branding & Personality

Financial Metaphors

Debt Levels: P1 Foreclosure → P4 Interest Accruing
Commands: Refinance debt, file for bankruptcy, sell to collection agency
Messaging: "Your code called. It wants a debt consolidation loan."

Snarky Humor

CLI Personality: refuctor shame for motivational debt shaming with financial metaphors
Taglines: "Debt Never Sleeps. Neither Should You." | "Refactor or Be Repossessed."
Self-Aware: "Built by someone who created 36 warnings while building a debt warning system."

Professional Edge

Enterprise-Ready: Team analytics, custom integrations, priority support
Educational Value: Teaching clean coding practices through gamification
Developer-Friendly: Actually makes debt cleanup enjoyable

🔧 Configuration

Project Configuration Files

Refuctor automatically creates and manages:

.debtignore - Patterns to ignore during debt scanning
cspell.json - Spell check configuration with project-specific dictionary
TECHDEBT.md - Debt tracking file with session logs
.refuctor/ - Directory for debt history and persistent data

Framework Detection

Refuctor automatically detects and configures for:

React - JSX-aware scanning and configuration
Vue - Vue-specific patterns and templates
Angular - TypeScript and Angular-specific rules
Node.js - Server-side JavaScript patterns
General JavaScript/TypeScript - Universal patterns

📊 MCP Integration

Refuctor includes a Model Context Protocol (MCP) server for AI assistant integration:


# Start MCP server

refuctor mcp-server

# Available MCP tools:

# - scan_debt: Scan project for technical debt

# - fix_debt: Auto-fix common issues

# - get_shame_report: Generate humorous debt report

# - broadcast_debt_status: Share debt status across workspaces

# - manage_debt_ignore: Manage .debtignore patterns

# - get_debt_status: Get current debt status and trends

```text

---

## 🚀 Getting Started

### **For Individual Developers**

1. **Install globally**: `npm install -g @puberty-labs/refuctor`
2. **Initialize project**: `refuctor init`
3. **Scan for debt**: `refuctor scan`
4. **Launch dashboard**: `refuctor serve`
5. **Fix issues**: `refuctor fix`

### **For Teams**

1. **Install in project**: `npm install --save-dev @puberty-labs/refuctor`
2. **Add to package.json scripts**: `"debt-scan": "refuctor scan"`
3. **Set up CI integration**: Run `refuctor scan` in build pipeline
4. **Use dashboard for monitoring**: `refuctor serve` for real-time tracking

---

## 🤝 Contributing

### **Development Philosophy**

- **No Bloat**: Every line of code must justify its existence
- **Immediate Debt**: Address technical debt the moment it's identified
- **Snarky but Functional**: Maintain irreverent personality without sacrificing performance
- **Meta Awareness**: The system must be able to manage its own technical debt

### **Issues & Support**

- **Bug Reports**: [GitHub Issues](https://github.com/puberty-labs/refuctor/issues)
- **Feature Requests**: [GitHub Discussions](https://github.com/puberty-labs/refuctor/discussions)
- **Documentation**: [GitHub Wiki](https://github.com/puberty-labs/refuctor/wiki)

---

## 📋 Current Status

### ✅ **Production Ready (CLI)**

- **Complete CLI suite** with 8+ commands - fully functional and tested
- **Debt detection engine** - professional-grade scanning and analysis
- **MCP integration** for AI assistants - stable and working
- **5 specialized goons** for targeted cleanup - automated fixes
- **Comprehensive documentation** - ready for end users

### 🚧 **In Development (Web UI)**

- **Real-time dashboard** - basic functionality working, UI polish needed
- **WebSocket communication** - functional but needs optimization
- **Dashboard controls** - SCAN DEBT works, FIX DEBT and NUCLEAR OPTION in progress

### 🎯 **Future Development**

- Gamification system with achievements
- Advanced AI-powered suggestions
- Team collaboration features
- IDE extensions (Cursor, VS Code)

**Recommendation**: Use the CLI commands for production work,
dashboard for monitoring only.

---

## 🎬 Conclusion

**Refuctor
transforms
technical
debt
management
from
reactive
cleanup
to
proactive
prevention.**
By
combining
professional-grade tooling with irreverent humor and financial metaphors,
we've created a tool that developers actually want to use.

The foundation is proven,
the results are measurable, and the personality is unforgettable.

**Ready to eliminate technical debt with a sense of humor?**

---

*"Built
by someone who created 36 warnings while building a debt warning system.
Self-own level: legendary."*

**Let's turn technical debt into a solved problem.** 🚀💪