qiming/qiming-file-server/docs/QUICK_START.md

# Quick start

This guide helps you get started with the qiming-file-server CLI.

## 1. Local testing

From the project root:

```bash
# Install dependencies
pnpm install

# Start the server (development)
pnpm run cli:start:dev

# Check status
pnpm run cli:status

# Health check
curl http://localhost:60000/health

# Stop the server
pnpm run cli:stop
```

## 2. Global install

```bash
# Global install
npm install -g .

# or
pnpm add -g .

# Then run from any directory
qiming-file-server start --env development
qiming-file-server status
qiming-file-server stop
```

## 3. Commands

| Command | Description |
| ------- | ----------- |
| `qiming-file-server start` | Start (default: production) |
| `qiming-file-server start --env dev` | Start (development) |
| `qiming-file-server stop` | Stop |
| `qiming-file-server restart` | Restart |
| `qiming-file-server status` | Status |
| `qiming-file-server --help` | Help |

## 4. Health check

```bash
curl http://localhost:60000/health
```

### Example response

```json
{
  "status": "ok",
  "timestamp": 1738600000000,
  "uptime": 3600,
  "version": "1.0.0",
  "platform": "darwin",
  "nodeVersion": "v22.0.0",
  "pid": 12345,
  "memory": {
    "heapUsed": 25.5,
    "heapTotal": 50.0,
    "rss": 100.0,
    "external": 5.0
  },
  "env": "production"
}
```

## 5. Environment variables

### Defaults

```bash
# Use defaults from env.production
qiming-file-server start --env production --port 60000
```

### Override paths

```bash
# Override path-related variables as needed
qiming-file-server start --env production --port 60000 \
  PROJECT_SOURCE_DIR=/data/projects \
  DIST_TARGET_DIR=/var/www/html \
  UPLOAD_PROJECT_DIR=/data/uploads
```

See the full reference: [Environment variables](./ENV.md)

## 6. Troubleshooting

### Server will not start

Check if the port is in use:

```bash
lsof -i :60000

# or
netstat -tlnp | grep 60000
```

### Stop fails

Force stop:

```bash
qiming-file-server stop --force
```

### Logs / sanity check

```bash
qiming-file-server status
curl http://localhost:60000/health
```

## 7. Docker

```yaml
# docker-compose.yml
version: "3.8"

services:
  qiming-file-server:
    image: qiming-file-server:latest
    container_name: qiming-file-server
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - PORT=60000
      - PROJECT_SOURCE_DIR=/app/projects
      - DIST_TARGET_DIR=/var/www/html
      - UPLOAD_PROJECT_DIR=/app/uploads
      - LOG_BASE_DIR=/app/logs
    volumes:
      - ./projects:/app/projects
      - ./logs:/app/logs
    ports:
      - "60000:60000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:60000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

## 8. Tests

The repo includes several ways to exercise the CLI.

### 8.1 Run all tests

```bash
pnpm run test:run

pnpm run test:unit

pnpm run test:integration
```

### 8.2 CLI unit tests

```bash
npx jest tests/unit/cli.test.js

pnpm run test:unit -- --testPathPattern=cli.test.js
```

**Coverage areas:**

| Group | Topics |
| ----- | ------ |
| Service Manager | PID file, process state, service status |
| Environment Utils | Env resolution, typing, CLI parsing |
| Cross-Platform | Platform detection, paths |
| Config | CLI-specific config validation |

### 8.3 Manual checks

#### Development

```bash
pnpm run cli:start:dev
pnpm run cli:status
curl http://localhost:60000/health
pnpm run cli:stop
```

#### Production

```bash
pnpm run cli:start:prod
pnpm run cli:status
curl http://localhost:60000/health
pnpm run cli:restart
pnpm run cli:stop
```

#### Custom config

```bash
qiming-file-server start --env development --port 60001

qiming-file-server start --env development --port 60002 \
  PROJECT_SOURCE_DIR=/data/test-projects \
  DIST_TARGET_DIR=/var/www/test-nginx

qiming-file-server status
qiming-file-server stop
```

### 8.4 Health endpoint

```bash
curl http://localhost:60000/health

curl http://localhost:60000/health | jq

curl http://localhost:60000/health | jq '.status'
curl http://localhost:60000/health | jq '.uptime'
curl http://localhost:60000/health | jq '.memory'
```

### 8.5 Cross-platform

#### macOS / Linux

```bash
qiming-file-server start --env production
ps aux | grep qiming-file-server
qiming-file-server stop
```

#### Windows

```cmd
qiming-file-server start --env production
tasklist | findstr qiming-file-server
qiming-file-server stop --force
```

### 8.6 Automation script (`test-cli.sh`)

Create `test-cli.sh`:

```bash
#!/bin/bash

# qiming-file-server CLI smoke test

set -e

echo "=== qiming-file-server CLI test ==="

PORT=60000
HEALTH_URL="http://localhost:${PORT}/health"

test_command() {
    local cmd=$1
    local description=$2
    echo "Test: ${description}"
    echo "Command: ${cmd}"
    eval "${cmd}"
    echo "✓ done"
    echo ""
}

echo "Cleaning up..."
qiming-file-server stop 2>/dev/null || true
sleep 1

test_command "qiming-file-server start --env production --port ${PORT}" "start server"

sleep 3

echo "Test: health check"
curl -s "${HEALTH_URL}" | jq '.status'
echo "✓ health OK"
echo ""

test_command "qiming-file-server status" "status"

test_command "qiming-file-server restart" "restart"
sleep 3

echo "Test: health after restart"
curl -s "${HEALTH_URL}" | jq '.status'
echo "✓ health OK after restart"
echo ""

test_command "qiming-file-server stop" "stop"

echo "=== All tests passed ==="
```

Run it:

```bash
chmod +x test-cli.sh
./test-cli.sh
```

## 9. Related docs

- [README.md](../README.md) — Main readme
- [ENV.md](./ENV.md) — Environment variables
- [CHANGELOG.md](../CHANGELOG.md) — Changelog