Add local CLI (#144)

frontend/local-client-cli/README.md

@@ -0,0 +1,206 @@
+# VaultLink Local CLI
+
+Standalone CLI for syncing VaultLink vaults to local filesystem with real-time bidirectional sync and file watching.
+
+## Installation
+
+### Docker (Recommended)
+
+```bash
+docker pull ghcr.io/schmelczer/vault-link-cli:latest
+
+docker run -v /path/to/vault:/vault \
+  ghcr.io/schmelczer/vault-link-cli:latest \
+  -l /vault \
+  -r wss://sync.example.com \
+  -t your-auth-token \
+  -v default
+```
+
+### npm
+
+```bash
+npm install -g @schmelczer/local-client-cli
+vaultlink --help
+```
+
+### From Source
+
+```bash
+cd frontend/local-client-cli
+npm install
+npm run build
+node dist/cli.js --help
+```
+
+## Usage
+
+```bash
+vaultlink \
+  --local-path ./vault \
+  --remote-uri wss://sync.example.com \
+  --token your-auth-token \
+  --vault-name default
+```
+
+## Options
+
+### Required
+
+| Option | Description |
+|--------|-------------|
+| `-l, --local-path <path>` | Local directory to sync |
+| `-r, --remote-uri <uri>` | Remote server WebSocket URI (ws:// or wss://) |
+| `-t, --token <token>` | Authentication token |
+| `-v, --vault-name <name>` | Vault name on server |
+
+### Optional
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--sync-concurrency <number>` | `1` | Concurrent sync operations |
+| `--max-file-size-mb <number>` | `10` | Maximum file size in MB |
+| `--ignore-pattern <pattern>` | - | Glob pattern to ignore (repeatable) |
+| `--websocket-retry-interval-ms <ms>` | `3500` | WebSocket reconnection interval |
+| `--log-level <level>` | `INFO` | Log level: DEBUG, INFO, WARNING, ERROR |
+| `-h, --help` | - | Show help |
+| `-V, --version` | - | Show version |
+
+### Auto-Ignored Patterns
+
+- `.vaultlink/**` - Internal sync metadata
+- `.git/**` - Git repository files
+
+### Examples
+
+Basic usage:
+```bash
+vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default
+```
+
+With ignore patterns:
+```bash
+vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default \
+  --ignore-pattern "*.tmp" \
+  --ignore-pattern ".DS_Store" \
+  --ignore-pattern "node_modules/**"
+```
+
+With debug logging:
+```bash
+vaultlink -l ./vault -r wss://sync.example.com -t token123 -v default \
+  --log-level DEBUG
+```
+
+## Docker Deployment
+
+### Docker Run
+
+```bash
+docker run -d \
+  --name vaultlink-sync \
+  --restart unless-stopped \
+  -v $(pwd)/vault:/vault \
+  ghcr.io/schmelczer/vault-link-cli:latest \
+  -l /vault \
+  -r wss://your-server.com \
+  -t your-token \
+  -v default
+```
+
+### Docker Compose
+
+```yaml
+services:
+  vaultlink-cli:
+    image: ghcr.io/schmelczer/vault-link-cli:latest
+    volumes:
+      - ./vault:/vault
+    command:
+      - "-l"
+      - "/vault"
+      - "-r"
+      - "wss://sync.example.com"
+      - "-t"
+      - "your-token"
+      - "-v"
+      - "default"
+    restart: unless-stopped
+```
+
+## Health Monitoring
+
+The Docker container includes a built-in healthcheck that monitors the WebSocket connection to the server.
+
+### Healthcheck Configuration
+
+- **Interval**: 30 seconds
+- **Timeout**: 10 seconds
+- **Start period**: 30 seconds (grace period for initial connection)
+- **Retries**: 3 failed checks before marking unhealthy
+
+### How It Works
+
+The CLI writes connection status to `/tmp/vaultlink-health.json` every 10 seconds and whenever the WebSocket connection status changes. The healthcheck script verifies:
+
+1. The health file exists
+2. The status is recent (updated within last 30 seconds)
+3. The WebSocket connection is active
+
+### Checking Container Health
+
+```bash
+# View health status
+docker ps
+
+# View detailed health check logs
+docker inspect --format='{{json .State.Health}}' vaultlink-sync | jq
+```
+
+### Custom Healthcheck
+
+To override the default healthcheck in docker-compose.yml:
+
+```yaml
+services:
+  vaultlink-cli:
+    image: ghcr.io/schmelczer/vault-link-cli:latest
+    healthcheck:
+      test: ["CMD", "node", "/app/healthcheck.js"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+```
+
+## Development
+
+Build:
+```bash
+npm run build
+# or from the parent folder, run
+docker build -f local-client-cli/Dockerfile  .
+```
+
+Test:
+```bash
+npm test
+```
+
+Docker build:
+```bash
+cd frontend
+docker build -f local-client-cli/Dockerfile -t vault-link-cli:test .
+```
+
+## How It Works
+
+1. Creates `.vaultlink` directory for sync metadata
+2. Performs initial sync of local files to server
+3. Watches filesystem for changes using Node's `fs.watch`
+4. Syncs changes bidirectionally in real-time
+5. Handles graceful shutdown on SIGINT/SIGTERM
+
+## License
+
+MIT