hsync-cli 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,152 @@
+# hsync-cli
+
+> Premium, zero-dependency cross-device file synchronization and storage manager terminal client.
+
+`hsync-cli` is a powerful, lightweight command-line companion for **File Sync V2**. It allows you to manage buckets, transfer files, and orchestrate automated, real-time bidirectional synchronization directly from your terminal.
+
+---
+
+## 🚀 Installation
+
+Install the package globally via your preferred Node package manager:
+
+```bash
+npm install -g hsync-cli
+```
+
+*Note: Once installed, the `hsync` command will be globally symlinked to your shell environment.*
+
+---
+
+## 🛠️ Setup & Authentication
+
+Before running synchronization tasks, configure the CLI to target your Express API server and authenticate.
+
+### 1. Set API Server Target
+Specify the URL of the running File Sync V2 API server:
+```bash
+hsync config set-server http://localhost:3000
+```
+
+### 2. Login & Authenticate
+Log in securely to generate and download your persistent personal API key (`X-API-Key`):
+```bash
+hsync login
+```
+*Note: You can skip interactive prompts in script/headless environments by passing a pre-generated API key directly:*
+```bash
+hsync login --api-key hmd_xxxxxxxxxxxxxxxxxxxx
+```
+
+### 3. Check Connection
+Verify your authenticated session details:
+```bash
+hsync me
+```
+
+### 4. Logout
+Remove credentials and invalidate the active API key session locally:
+```bash
+hsync logout
+```
+
+---
+
+## 📁 Managing Storage Buckets
+
+Storage buckets are logical sandboxes backed by pluggable providers (Local folders or Amazon S3 buckets).
+
+### List Buckets
+See all buckets registered under your account:
+```bash
+hsync bucket list
+```
+
+### Create a Bucket
+Register a new storage sandbox:
+```bash
+# Create a Local folder provider bucket
+hsync bucket create "My Projects" my-projects --provider local --rootPath /data/my-projects
+
+# Create an Amazon S3 provider bucket
+hsync bucket create "Cloud Backups" backups --provider s3 --bucket my-aws-s3-bucket-name
+```
+
+### Delete a Bucket
+Permanently destroy a storage bucket (this also wipes files inside):
+```bash
+hsync bucket delete my-projects
+```
+
+---
+
+## ⚡ Direct File Transfers (Push & Pull)
+
+You can run immediate, one-off file or folder transfers without setting up persistent schedules.
+
+### Push (Upload to Server)
+Upload a local folder or file to a specific remote bucket target (e.g. `bucket-slug:optional-remote-path`):
+```bash
+hsync push ./my-local-code projects-bucket:active-source
+```
+*Tip: Skip conflict resolution prompts and force overwrites using `-y` or `--yes`:*
+```bash
+hsync push ./my-local-code projects-bucket:active-source --yes
+```
+
+### Pull (Download to Machine)
+Download a folder or file from a remote bucket directly to your local machine:
+```bash
+hsync pull projects-bucket:active-source ./downloaded-code
+```
+
+---
+
+## 🔄 Automated Folder Synchronization
+
+The sync engine uses local SQLite trackers to orchestrate continuous synchronization cycles, keeping folders on multiple devices automatically in sync with the remote server.
+
+### 1. Register a Sync Profile
+Define a persistent local-to-remote folder synchronization job:
+```bash
+hsync sync add /path/to/local/dir bucket-slug:remote-path \
+  --name project-sync \
+  --direction bidirectional \
+  --strategy newer-wins \
+  --interval 10
+```
+
+#### Sync Config Flags:
+*   `-n, --name <jobName>`: A unique name identifier for your job.
+*   `-d, --direction <push|pull|bidirectional>`: Sync direction format.
+*   `-s, --strategy <local-wins|server-wins|newer-wins>`: Rules on resolving file modifications conflicts.
+*   `-i, --interval <seconds>`: Frequency of the background scan cycle (default: `10` seconds).
+*   `--no-conflict-copy`: Disable saving conflict backup files (`filename.conflict-YYYY-MM-DD.ext`).
+
+### 2. List Registered Sync Jobs
+List all synchronization jobs configured on your machine:
+```bash
+hsync sync list
+```
+
+### 3. Remove a Sync Job
+Stop tracking a registered sync job:
+```bash
+hsync sync remove project-sync
+```
+
+### 4. Start the Synchronization Scheduler
+Launch the active sync loop to scan and synchronize folders automatically in the background:
+```bash
+# Start all registered sync jobs
+hsync sync start
+
+# Start a specific sync job by name
+hsync sync start project-sync
+```
+
+---
+
+## 🛡️ License
+
+MIT License. Designed with antigravity by the Advanced Agentic Coding team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hsync-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "hsync CLI for file sync operations",
   "bin": {
     "hsync": "./dist/bin.js"
@@ -15,7 +15,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@file-sync/sync-engine": "workspace:*",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "axios": "^1.6.5",
@@ -23,6 +22,7 @@
     "ora": "^8.0.1"
   },
   "devDependencies": {
+    "@file-sync/sync-engine": "workspace:*",
     "@types/bun": "^1.1.0",
     "@types/node": "^20.11.0",
     "typescript": "^5.3.0"