Implement

2025-10-20 20:22:29 +01:00 · 2025-10-20 20:22:29 +01:00 · b160dadf44
commit b160dadf44
parent d1c4b319a5
18 changed files with 1615 additions and 48 deletions
--- a/frontend/local-client-cli/README.md
+++ b/frontend/local-client-cli/README.md
@ -0,0 +1,288 @@
+# VaultLink Local CLI
+
+A standalone command-line interface for syncing VaultLink vaults to your local filesystem. This CLI wraps the VaultLink sync client and provides file watching capabilities for real-time synchronization.
+
+## Features
+
+- Real-time bidirectional sync between local filesystem and VaultLink server
+- File watching with automatic change detection
+- Cross-platform support (Linux, macOS, Windows)
+- Configuration via command-line arguments or JSON file
+- Comprehensive error handling and logging
+- Graceful shutdown on SIGINT/SIGTERM
+
+## Installation
+
+### Using Docker (Recommended)
+
+The easiest way to run VaultLink CLI is using Docker:
+
+```bash
+docker pull ghcr.io/schmelczer/vault-link-cli:latest
+
+# Run with all options via command line
+docker run -v /path/to/vault:/vault \
+  ghcr.io/schmelczer/vault-link-cli:latest \
+  -l /vault \
+  -r https://sync.example.com \
+  -t your-auth-token \
+  -v default
+
+# Or use a config file
+docker run -v /path/to/vault:/vault \
+  -v /path/to/config.json:/config.json \
+  ghcr.io/schmelczer/vault-link-cli:latest \
+  -l /vault \
+  -c /config.json
+```
+
+### Using Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  vaultlink-cli:
+    image: ghcr.io/schmelczer/vault-link-cli:latest
+    volumes:
+      - ./vault:/vault
+      - ./config.json:/config.json
+    command: -l /vault -c /config.json
+    restart: unless-stopped
+```
+
+### From npm Package
+
+```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
+
+### Basic Usage
+
+```bash
+vaultlink \
+  --local-path ./my-vault \
+  --remote-uri https://sync.example.com \
+  --token your-auth-token \
+  --vault-name default
+```
+
+### Using a Configuration File
+
+Create a `config.json` file:
+
+```json
+{
+  "remoteUri": "https://sync.example.com",
+  "token": "your-auth-token",
+  "vaultName": "default",
+  "syncConcurrency": 1,
+  "maxFileSizeMB": 10,
+  "ignorePatterns": [".git/**", "*.tmp"],
+  "webSocketRetryIntervalMs": 3500
+}
+```
+
+Then run:
+
+```bash
+vaultlink --local-path ./my-vault --config config.json
+```
+
+### Command-Line Options
+
+#### Required Arguments
+
+- `-l, --local-path <PATH>` - Local directory path to sync
+- `-r, --remote-uri <URI>` - Remote server URI (unless using --config)
+- `-t, --token <TOKEN>` - Authentication token (unless using --config)
+- `-v, --vault-name <NAME>` - Vault name (unless using --config)
+
+#### Optional Arguments
+
+- `-c, --config <FILE>` - Load configuration from JSON file
+- `--sync-concurrency <NUM>` - Number of concurrent sync operations (default: 1)
+- `--max-file-size-mb <NUM>` - Maximum file size in MB (default: 10)
+- `--ignore-pattern <PATTERN>` - Pattern to ignore (can be used multiple times)
+- `--websocket-retry-interval-ms <NUM>` - WebSocket retry interval in ms (default: 3500)
+- `-h, --help` - Print help message
+- `-V, --version` - Print version
+
+### Ignore Patterns
+
+Ignore patterns support glob syntax. The CLI automatically ignores:
+
+- `.vaultlink/**` - Internal sync data directory
+- `.git/**` - Git repository files
+
+You can add additional patterns:
+
+```bash
+vaultlink \
+  --local-path ./my-vault \
+  --remote-uri https://sync.example.com \
+  --token mytoken \
+  --vault-name default \
+  --ignore-pattern "*.tmp" \
+  --ignore-pattern ".DS_Store" \
+  --ignore-pattern "node_modules/**"
+```
+
+## Docker Deployment
+
+### Self-Hosting with Docker
+
+The CLI is designed to run as a long-lived container:
+
+```bash
+# Create a vault directory
+mkdir -p ./vault
+
+# Create config.json
+cat > config.json <<EOF
+{
+  "remoteUri": "https://your-server.com",
+  "token": "your-token",
+  "vaultName": "default"
+}
+EOF
+
+# Run the container
+docker run -d \
+  --name vaultlink-sync \
+  --restart unless-stopped \
+  -v $(pwd)/vault:/vault \
+  -v $(pwd)/config.json:/config.json \
+  ghcr.io/schmelczer/vault-link-cli:latest \
+  -l /vault -c /config.json
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vaultlink-cli
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vaultlink-cli
+  template:
+    metadata:
+      labels:
+        app: vaultlink-cli
+    spec:
+      containers:
+      - name: vaultlink-cli
+        image: ghcr.io/schmelczer/vault-link-cli:latest
+        args:
+          - "-l"
+          - "/vault"
+          - "-c"
+          - "/config/config.json"
+        volumeMounts:
+        - name: vault
+          mountPath: /vault
+        - name: config
+          mountPath: /config
+      volumes:
+      - name: vault
+        persistentVolumeClaim:
+          claimName: vaultlink-pvc
+      - name: config
+        configMap:
+          name: vaultlink-config
+```
+
+## How It Works
+
+1. **Initialization**: The CLI creates a `.vaultlink` directory in your local path to store sync metadata and state
+2. **Initial Sync**: On first run, all local files are synced to the server
+3. **File Watching**: The CLI watches for file system changes using Node's `fs.watch` API
+4. **Real-time Sync**: Any local changes are automatically synced to the server, and server changes are applied locally
+5. **Graceful Shutdown**: On Ctrl+C or termination signals, the CLI waits for pending operations to complete
+
+## Development
+
+### Building
+
+```bash
+npm run build
+# or from the parent folder, run
+docker build -f local-client-cli/Dockerfile  .
+```
+
+### Development Mode with Watch
+
+```bash
+npm run dev
+```
+
+### Running Tests
+
+```bash
+npm test
+```
+
+Tests cover:
+- Filesystem operations (read, write, delete, rename, etc.)
+- CLI argument parsing and validation
+- Cross-platform path handling
+- Error handling
+
+## Architecture
+
+The CLI consists of several key components:
+
+- **`cli.ts`**: Main entry point, orchestrates initialization and lifecycle
+- **`node-filesystem.ts`**: Node.js filesystem adapter implementing the `FileSystemOperations` interface with cross-platform path normalization
+- **`file-watcher.ts`**: Watches filesystem changes and triggers sync operations
+- **`args.ts`**: Command-line argument parser using `commander` library
+- **`config-loader.ts`**: JSON configuration file loader and merger
+
+### Dependencies
+
+- **commander**: Industry-standard CLI argument parsing with built-in help generation and validation
+- **sync-client**: Core VaultLink synchronization library
+
+### Path Handling
+
+The filesystem adapter ensures cross-platform compatibility by:
+- **API Contract**: Always accepts forward slashes (`/`) as input
+- **API Contract**: Always returns forward slashes (`/`) as output
+- **Implementation**: Converts between forward slashes and platform-native separators internally
+- **Windows Support**: Automatically converts `/` to `\` on Windows for filesystem operations
+
+## Error Handling
+
+The CLI provides robust error handling:
+
+- Invalid arguments result in clear error messages and exit code 1
+- Connection failures are reported before starting sync
+- File operation errors are logged with context
+- Graceful shutdown ensures no data loss on termination
+
+## Cross-Platform Support
+
+The CLI is built with cross-platform compatibility:
+
+- Uses Node's `path` module for platform-agnostic path handling
+- Automatically detects platform line endings (CRLF on Windows, LF on Unix)
+- File watching works on all platforms through Node's native `fs.watch`
+- Compiled with Webpack for Node target, ensuring broad compatibility
+- Path normalization ensures consistent behavior across Windows, macOS, and Linux
+