npm package: @hotshot-it/server
Description: Standalone HTTP + WebSocket server for Hotshot - Works with any framework (Rails, Vue, Svelte, plain HTML)
Latest version: 0.0.1

# @hotshot/server

Standalone HTTP + WebSocket server for AI-powered component editing with Hotshot.

This package provides a framework-agnostic server that works with plain HTML, Rails, Vue, Svelte, and any other web framework—no Vite required.

## Installation

```bash
# Global installation
npm install -g @hotshot/server

# Or use directly with npx
npx @hotshot/server
```

## Quick Start

1. **Start the server in your project directory:**

```bash
cd /path/to/your/project
npx @hotshot/server
```

2. **Install the Hotshot Chrome extension** (if you haven't already)

3. **Open your app in Chrome** and start editing components!

## Usage

### Basic Usage

```bash
# Start with default settings (port 3737)
hotshot-server

# Custom port
hotshot-server --port 8080

# With config file
hotshot-server --config hotshot.json
```

### Configuration File

Create `.hotshotrc.json` in your project root:

```json
{
  "port": 3737,
  "cwd": "/path/to/project",
  "model": "claude-sonnet-4-5",
  "permissionMode": "acceptEdits",
  "systemPromptAdditions": "Additional instructions for Claude..."
}
```

### CLI Options

```
Options:
  -p, --port <port>      Server port (default: 3737)
  -c, --config <path>    Path to config file (default: .hotshotrc.json)
  -h, --help             Show help message
```

## Supported Frameworks

### ✅ React (with Fiber)
- Automatic component detection
- File path extraction from React internals
- Full props and context support

### ✅ Rails
- View path detection from HTML comments
- Supports ERB templates and partials
- Line number extraction

### ✅ Plain HTML
- Direct element selection
- Manual file path configuration
- Works with any static site generator

### 🚧 Vue, Svelte (Coming Soon)
- Framework detection implemented
- Full support in development

## How It Works

1. **Server runs independently** from your app's dev server
2. **Extension connects via WebSocket** (`ws://localhost:3737/hotshot-ws`)
3. **Claude CLI integration** handles AI-powered edits
4. **Health check endpoint** at `http://localhost:3737/health`

## Differences from Vite Plugin

| Feature | Vite Plugin | Standalone Server |
|---------|-------------|-------------------|
| Framework Support | React only | React, Rails, HTML, etc. |
| Installation | Part of Vite config | Separate process |
| Port | Same as Vite | Independent (3737) |
| HMR Integration | Automatic | Uses your dev server's HMR |
| Best For | React + Vite projects | Everything else |

## Programmatic Usage

You can also use the server programmatically in Node.js:

```typescript
import { HotshotServer } from '@hotshot/server';

const server = new HotshotServer({
  port: 3737,
  cwd: process.cwd(),
  model: 'claude-sonnet-4-5',
  permissionMode: 'acceptEdits',
});

await server.start();
```

## Requirements

- Node.js 20.19+ or 22.12+
- Claude CLI installed and configured
- Chrome browser with Hotshot extension

## Troubleshooting

### Extension won't connect

1. Make sure the server is running: `hotshot-server`
2. Check server output for errors
3. Verify port 3737 is not blocked by firewall
4. Check health endpoint: `curl http://localhost:3737/health`

### Claude CLI errors

Make sure Claude CLI is installed and authenticated:

```bash
# Install Claude CLI
npm install -g @anthropic-ai/claude-cli

# Authenticate
claude auth
```

## License

Apache-2.0