dev-lamp/README.md

Your friendly lighthouse performance companion - 100% local

# dev-lamp

![npm version](https://img.shields.io/npm/v/dev-lamp)
![MLoT](https://img.shields.io/badge/MLoT-ai-blue)

> Your friendly lighthouse performance companion - 100% local, privacy-first

![Demo](https://raw.githubusercontent.com/incrediblecrab/Packages-and-Extensions-Media/main/dev-lamp.gif)

## Why dev-lamp?

- **100% Local** - Your data never leaves your machine
- **Privacy First** - No tracking, no analytics, no external connections
- **One Command** - Simple as `dev-lamp http://localhost:3000`
- **Developer Friendly** - Clear errors, great documentation
- **Multiple Formats** - Markdown, Text, JSON output

## Quick Start

```bash
# Install globally
npm install -g dev-lamp

# Analyze your local site
dev-lamp http://localhost:3000

# That's it! Your report is ready
```

## Installation

### Global Installation (Recommended)
```bash
npm install -g dev-lamp
```

### Local Installation
```bash
npm install --save-dev dev-lamp
```

## Usage

### Basic Analysis
```bash
# Analyze and save as markdown (default)
dev-lamp http://localhost:3000

# Specify output file
dev-lamp http://localhost:3000 -o performance.md

# Different format (txt, json)
dev-lamp http://localhost:3000 -f txt

# Analyze mobile performance
dev-lamp http://localhost:3000 --device mobile

# Multiple categories
dev-lamp http://localhost:3000 --categories performance,accessibility,seo
```

### Command Options

```bash
dev-lamp analyze <url> [options]

Options:
  -o, --output <path>      Output file path (default: "lighthouse-report.md")
  -f, --format <type>      Output format: md, txt, json (default: "md")
  -t, --template <name>    Template: minimal, detailed, github (default: "detailed")
  --device <type>          Device: mobile, desktop (default: "desktop")
  --categories <list>      Categories to audit (default: "performance")
  --threshold <score>      Minimum acceptable score
  --no-headless           Show Chrome window
  --keep-alive            Keep Chrome open for multiple runs
```

### Alternative Commands
```bash
# Make a wish for performance insights
dev-lamp wish http://localhost:3000

# Alternative command
dev-lamp rub http://localhost:3000
```

## Output Examples

### Markdown Output (Default)
```markdown
# Lighthouse Performance Report

Generated by dev-lamp
**URL:** http://localhost:3000
**Score:** 95/100 [GOOD]

## Core Web Vitals
- **LCP:** 1.2s - Good
- **FID:** 50ms - Good
- **CLS:** 0.05 - Good
```

### Text Output
```
LIGHTHOUSE PERFORMANCE REPORT
============================
URL: http://localhost:3000
Score: 95/100 [GOOD]

CORE WEB VITALS
LCP: 1.2s [GOOD]
FID: 50ms [GOOD]  
CLS: 0.05 [GOOD]
```

### JSON Output
```json
{
  "metadata": {
    "url": "http://localhost:3000",
    "timestamp": "2024-01-01T00:00:00Z",
    "device": "desktop"
  },
  "scores": {
    "performance": 95
  },
  "metrics": {
    "lcp": {
      "score": 90,
      "value": 1200,
      "displayValue": "1.2s"
    }
  }
}
```

## Categories

Available audit categories:
- `performance` - Core Web Vitals and performance metrics
- `accessibility` - Accessibility best practices
- `best-practices` - Web development best practices
- `seo` - Search Engine Optimization
- `pwa` - Progressive Web App features

## Templates

### Minimal
Compact report with just essential metrics

### Detailed (Default)
Comprehensive report with all metrics, opportunities, and diagnostics

### GitHub
PR-ready format optimized for GitHub comments

## Privacy Commitment

**Your data stays on your machine. Period.**

- No external API calls
- No tracking or analytics
- No data collection
- Chrome runs locally
- Reports generated locally

## Requirements

- Node.js 18+
- Chrome or Chromium browser

## Development

```bash
# Clone repository
git clone https://github.com/incrediblecrab/dev-lamp.git
cd dev-lamp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Run tests
npm test
```

## Contributing

Contributions welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT © mlot.ai

## Support

- **Issues:** [GitHub Issues](https://github.com/incrediblecrab/dev-lamp/issues)
- **Discussions:** [GitHub Discussions](https://github.com/incrediblecrab/dev-lamp/discussions)

## Resources

- 📺 [Watch Demo Video](https://youtu.be/pVsoAoPQqTo)
- 🌐 [Visit MLoT Page](https://mlot.ai/dev-lamp/)
- 📦 [View on GitHub](https://github.com/incrediblecrab/dev-lamp)
- 🔒 [Privacy Policy](https://mlot.ai/privacy)

## Publisher

**Max's Lab of Things**
Visit [mlot.ai](https://mlot.ai/)

---

*dev-lamp - Performance insights, 100% locally*