npm package: @scom/serve
Description: SCOM HTTP/HTTPS server for static files
Latest version: 0.1.3

# @scom/serve

A simple HTTP/HTTPS static file server built with Node.js built-in modules only. No external dependencies required.

## Features

- ✅ HTTP and HTTPS support
- ✅ Static file serving with proper MIME types
- ✅ Directory listing when no index file is found
- ✅ CORS support (enabled by default)
- ✅ Cache headers
- ✅ Automatic browser opening
- ✅ Cross-platform compatibility
- ✅ Zero external dependencies

## Installation

```bash
npm install @scom/serve
```

## Usage

### Command Line

```bash
# Serve current directory on 0.0.0.0:8080
npx @scom/serve

# Serve specific directory on custom port
npx @scom/serve dist -p 3000

# HTTPS server with SSL certificates
npx @scom/serve -p 8443 -s --cert cert.pem --key key.pem

# Open browser automatically after starting
npx @scom/serve --open

# Run in silent mode (suppress log output)
npx @scom/serve --silent

# Map URL paths to local directories
npx @scom/serve --map /dist:./dist --map /assets:../assets

# Disable CORS and gzip compression
npx @scom/serve --no-cors --no-gzip

# Custom cache settings
npx @scom/serve --cache 7200

# Serve on specific host and port
npx @scom/serve -H 127.0.0.1 -p 9000
```

### Programmatic API

```typescript
import { StaticServer, createServer } from '@scom/serve';

// Using the class with basic options
const server = new StaticServer({
  port: 3000,
  root: './dist',
  open: true
});

await server.start();

// Using the factory function with advanced options
const server2 = createServer({
  port: 8080,
  host: '0.0.0.0',
  cors: true,
  cache: 3600,
  gzip: true,
  staticMaps: {
    '/api': './mock-api',
    '/assets': '../shared-assets'
  }
});

await server2.start();

// HTTPS server with SSL certificates
const httpsServer = new StaticServer({
  port: 8443,
  https: true,
  cert: './certs/server.crt',
  key: './certs/server.key',
  silent: true
});

await httpsServer.start();
```

## CLI Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--port` | `-p` | Port number for the server to listen on | 8080 |
| `--host` | `-H` | Hostname or IP address to bind the server to | 0.0.0.0 |
| `--root` | `-r` | Root directory to serve static files from | Current directory |
| `--https` | `-s` | Enable HTTPS/SSL encryption (requires --cert and --key) | false |
| `--cert` | | Path to SSL/TLS certificate file for HTTPS connections | |
| `--key` | | Path to SSL/TLS private key file for HTTPS connections | |
| `--open` | `-o` | Automatically open the served URL in default web browser | false |
| `--silent` | `-S` | Suppress log output and run in quiet mode | false |
| `--no-cors` | | Disable Cross-Origin Resource Sharing (CORS) headers | CORS enabled |
| `--cache` | | Set Cache-Control max-age header value in seconds | 3600 |
| `--no-gzip` | | Disable gzip compression for served files | gzip enabled |
| `--map` | | Map URL paths to local directories (format: `/url:./local/path`) | |
| `--help` | `-h` | Display help information with usage and available options | |
| `--version` | `-v` | Show the current version of the @scom/serve package | |

## API Options

```typescript
interface ServeOptions {
  port?: number;          // Port number for the server to listen on (default: 8080)
  host?: string;          // Hostname or IP address to bind to (default: '0.0.0.0')
  root?: string;          // Root directory to serve static files from (default: process.cwd())
  https?: boolean;        // Enable HTTPS/SSL encryption (default: false)
  cert?: string;          // Path to SSL/TLS certificate file for HTTPS connections
  key?: string;           // Path to SSL/TLS private key file for HTTPS connections
  cors?: boolean;         // Enable Cross-Origin Resource Sharing headers (default: true)
  open?: boolean;         // Automatically open the served URL in default browser (default: false)
  silent?: boolean;       // Suppress log output and run in quiet mode (default: false)
  cache?: number;         // Cache-Control max-age header value in seconds (default: 3600)
  gzip?: boolean;         // Enable gzip compression for served files (default: true)
  staticMaps?: Record<string, string>; // Map URL paths to local directories
}
}
```

## Supported MIME Types

The server automatically detects and serves files with appropriate MIME types for:

- HTML files (`.html`, `.htm`)
- JavaScript files (`.js`)
- CSS files (`.css`)
- JSON files (`.json`)
- Images (`.png`, `.jpg`, `.gif`, `.ico`, `.svg`)
- Fonts (`.woff`, `.woff2`, `.ttf`, `.eot`)
- Media files (`.mp4`, `.webm`, `.mp3`, `.wav`, `.ogg`)
- Documents (`.pdf`, `.txt`, `.xml`, `.zip`)

## Directory Listing

When a directory is accessed and no index file (index.html, index.htm, default.html) is found, the server generates a clean, sortable directory listing.

## HTTPS Support

To enable HTTPS, provide both certificate and key files:

```bash
npx @scom/serve -s --cert path/to/cert.pem --key path/to/key.pem
```

## CORS Support

CORS is enabled by default with permissive headers. To disable CORS:

```bash
npx @scom/serve --no-cors
```

## Testing

The package includes comprehensive tests covering:

- Core server functionality
- CLI interface
- Performance characteristics
- Error handling
- Concurrent request handling

```bash
# Run all tests
npm test

# Run specific test suites
npm run test:server      # Core server tests
npm run test:cli         # CLI tests  
npm run test:performance # Performance tests
```

## Development

```bash
# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Run tests during development
npm run test:watch
```