npm package: @maderatools/bridge
Description: Development bridge for forwarding Chrome extension service worker logs to MADERA Helper DevTools panel
Author: MADERA Team
Latest version: 1.0.0

# @maderatools/bridge

> 🚀 **Development bridge for Chrome extension service worker logging**

Automatically forward all your Chrome extension service worker logs to [MADERA Helper](https://github.com/your-org/madera-helper) DevTools panel!

## Why?

Chrome's security prevents DevTools extensions from accessing other extensions' service worker logs. This bridge solves that by running **inside your extension** and forwarding logs to MADERA Helper.

**Before:** Open chrome://extensions → Click "service worker" → Look at console → Copy manually
**After:** All logs automatically appear in MADERA Helper panel with 1-click copy! 🎉

## Quick Start

### Option 1: Auto-Install (Recommended! ⚡)

```bash
npx @maderatools/bridge install
```

That's it! The bridge will:
- 🔍 Scan for all Chrome extension projects
- 📦 Install the bridge in each one
- ✅ Add `importScripts()` automatically
- 🎉 Done!

### Option 2: Manual Install

```bash
npm install --save-dev @maderatools/bridge
```

Then in your service worker:

```javascript
// background.js
importScripts('node_modules/@maderatools/bridge/index.js');

// All your logs are now forwarded! 🎉
console.log('Service worker started');
console.error('Something went wrong');
```

### Option 3: With Bundler (Webpack/Vite/etc.)

```bash
npm install --save-dev @maderatools/bridge
```

```javascript
// background.js
import '@maderatools/bridge';

// Done! Logs are forwarded automatically
console.log('This appears in MADERA Helper!');
```

## CLI Commands

### Install Bridge

```bash
npx @maderatools/bridge install
```

Scans your workspace and installs bridge in all Chrome extension projects.

### Update Bridge

```bash
npx @maderatools/bridge update
```

Updates the bridge to the latest version in all projects that have it.

### Remove Bridge (Before Publishing!)

```bash
npx @maderatools/bridge remove
```

Removes bridge from all projects. Run this before publishing to Chrome Web Store!

### List Projects

```bash
npx @maderatools/bridge list
```

Shows all detected Chrome extension projects in your workspace.

## Usage

### 1. Install Bridge

Choose any installation method above.

### 2. Get MADERA Helper Extension ID

1. Open `chrome://extensions`
2. Enable "Developer mode"
3. Find "MADERA Helper"
4. Copy the extension ID (default: `hdiebgpeehbbpipcpamhdacncaclomfi`)

### 3. Use MADERA Helper

1. Reload your extension
2. Open DevTools (F12)
3. Click "MADERA Helper" tab
4. Select your extension from dropdown
5. Check "🔧 Test Mode"
6. **All service worker logs appear automatically!** 🎉

## Features

### Captures Everything

- ✅ `console.log()` → Regular logs
- ✅ `console.error()` → Errors (red)
- ✅ `console.warn()` → Warnings (yellow)
- ✅ `console.info()` → Info
- ✅ `console.debug()` → Debug
- ✅ `console.trace()` → With stack traces

### Visual Indicators

Logs appear in MADERA Helper with:
- **Green left border** (service worker indicator)
- **Extension name prefix**: `[Your Extension] Your log`
- **Timestamps**
- **Color coding** by log level

### Runtime Control

```javascript
// In your service worker console:

// Disable bridge temporarily
MADERABridge.disable();
console.log('This will NOT be forwarded');

// Re-enable
MADERABridge.enable();
console.log('This WILL be forwarded');

// Restore original console
MADERABridge.restore();

// Check status
console.log(MADERABridge.version); // "1.0.0"
```

## Workflow Example

### Development

```bash
# Install once
npx @maderatools/bridge install

# Work on your extension
# All logs appear in MADERA Helper automatically!

# Update when new version is released
npx @maderatools/bridge update
```

### Before Publishing

```bash
# Clean up for production
npx @maderatools/bridge remove

# Build and publish
npm run build
# Upload to Chrome Web Store
```

## Advanced Usage

### Environment-Based Loading

```javascript
// background.js
if (process.env.NODE_ENV === 'development') {
  importScripts('madera-bridge.js');
}

// Or with bundler
if (import.meta.env.DEV) {
  import('@madera/bridge');
}
```

### With Build Tools

**Webpack:**
```javascript
// webpack.config.js
const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'node_modules/@maderatools/bridge/index.js',
          to: 'madera-bridge.js'
        }
      ]
    })
  ]
};
```

**Vite:**
```javascript
// vite.config.js
export default {
  build: {
    rollupOptions: {
      input: {
        background: 'src/background.js',
        bridge: 'node_modules/@maderatools/bridge/index.js'
      }
    }
  }
};
```

### Multiple Workspaces

```bash
# Scan specific directory
npx @maderatools/bridge install /path/to/projects

# Or run from workspace root
cd ~/projects/extensions
npx @maderatools/bridge install
```

## Troubleshooting

### "No Chrome extension projects found"

Make sure you're running the command from a directory containing extension projects with `manifest.json` files.

### "Bridge already installed"

The bridge is already present! Use `npx @maderatools/bridge update` to update it.

### "Logs not appearing in MADERA Helper"

Check:
1. ✅ MADERA Helper extension is installed
2. ✅ Your extension is selected in MADERA Helper dropdown
3. ✅ "🔧 Test Mode" is checked
4. ✅ You've triggered your service worker (click extension icon, etc.)
5. ✅ MADERA Helper ID matches in the bridge file

### "Error: Cannot find module"

If using `importScripts()`, make sure the path is correct:
```javascript
// If bridge is in root
importScripts('madera-bridge.js');

// If bridge is in subfolder
importScripts('scripts/madera-bridge.js');
```

## Security & Performance

### Is it safe?

✅ **YES!** The bridge:
- Only forwards logs to MADERA Helper (nowhere else)
- Doesn't modify extension behavior
- Runs entirely locally
- Open source - inspect the code!

### Performance impact?

⚡ **Minimal!** Adds ~1ms per log statement (imperceptible).

### Should I remove it before publishing?

🚫 **YES!** Always remove before publishing:

```bash
npx @maderatools/bridge remove
```

The bridge is **development only** - don't ship it to production!

## Contributing

Found a bug? Have an idea? [Open an issue!](https://github.com/your-org/madera-bridge/issues)

## License

MIT

## Related

- [MADERA Helper](https://github.com/your-org/madera-helper) - The DevTools extension
- [MADERA Bridge Manual Installation Guide](./README-BRIDGE.md)

---

**Happy debugging! 🚀**