feat: update installation guide and improve error handling in repo client

Author: ErcinDedeoglu

docs/LLM-INSTALL.md

@@ -18,117 +18,88 @@ Ask the user:
 Run this command:
 npm install oc-sync
 
-### Step 2: Create Private GitHub Repository
-Guide the user:
-1. Go to https://github.com/new
-2. Repository name: suggest "opencode-sync-data" or ask user preference
-3. Set visibility to "Private" (important for security)
-4. Click "Create repository"
-5. Ask user: "What is your GitHub username?" - Save this as OWNER
-6. Ask user: "What did you name the repository?" - Save this as REPO
-
-### Step 3: Generate GitHub Personal Access Token
+### Step 2: Generate GitHub Personal Access Token
 Guide the user step by step:
-1. Go to https://github.com/settings/tokens?type=beta
-2. Click "Generate new token"
+1. Go to https://github.com/settings/tokens
+2. Click "Generate new token (classic)"
 3. Token name: "opencode-sync"
 4. Expiration: recommend "90 days" or "No expiration" based on user preference
-5. Under "Repository access", select "Only select repositories" and choose the sync repo created in Step 2
-6. Under "Permissions" → "Repository permissions":
-   - Contents: Read and write
-   - Metadata: Read-only
-7. Click "Generate token"
-8. IMPORTANT: Tell user to copy the token immediately (starts with "github_pat_")
-9. Ask user: "Please paste your token here" - Save this as TOKEN
-
-### Step 4: Encryption Key (Optional)
-Ask the user:
-"Do you want to encrypt your credentials (auth tokens) before syncing? This adds extra security but requires the same key on all machines."
-
-If YES:
-- Generate a random 32-character alphanumeric string, or let user provide their own (minimum 16 characters)
-- Save this as ENCRYPTION_KEY
-- IMPORTANT: Tell user to save this key securely. If lost, encrypted credentials cannot be recovered.
-- WARNING: All machines must use the same key. Adding encryption later will break sync on machines without the key.
-
-If NO:
-- Skip this step. Credentials will sync in plain text (still protected by GitHub's private repo authentication).
-
-### Step 5: Create Configuration
-Create or update the OpenCode config file with these values:
+5. Select scope: "repo" (Full control of private repositories)
+6. Click "Generate token"
+7. IMPORTANT: Tell user to copy the token immediately (starts with "ghp_")
+8. Ask user: "Please paste your token here" - Save this as TOKEN
 
-Without encryption:
-{
-  "plugins": {
-    "oc-sync": {
-      "token": "<TOKEN from Step 3>",
-      "owner": "<OWNER from Step 2>",
-      "repo": "<REPO from Step 2>",
-      "branch": "main"
-    }
-  }
-}
+### Step 3: Create Configuration
+Create the config file at ~/.config/opencode/opencode-sync.json:
 
-With encryption:
 {
-  "plugins": {
-    "oc-sync": {
-      "token": "<TOKEN from Step 3>",
-      "owner": "<OWNER from Step 2>",
-      "repo": "<REPO from Step 2>",
-      "branch": "main",
-      "encryptionKey": "<ENCRYPTION_KEY from Step 4>"
-    }
-  }
+  "token": "<TOKEN from Step 2>"
 }
 
-Show the user the complete config with their actual values filled in.
+That's it! The plugin will automatically:
+- Detect your GitHub username
+- Create a private repository (.opencode-sync)
+- Detect the default branch (main/master)
 
-### Step 6: Verify Installation
+### Step 4: Verify Installation
 Tell user to restart OpenCode. The plugin will:
-- Auto-sync on startup
+- Auto-create the sync repository if needed
+- Sync on startup
 - Watch for file changes
 - Push/pull automatically
 
+Check logs at: ~/.local/share/opencode/log/opencode-sync.log
+
+Expected output:
+[opencode-sync] Plugin starting...
+[opencode-sync] Token loaded from: config file
+[opencode-sync] Setting up sync storage...
+[opencode-sync] Linked to repo: username/.opencode-sync
+[opencode-sync] Plugin ready
+
 ### Troubleshooting
 If user reports errors:
-- "404 Not Found": Repository name or owner is wrong. Verify spelling.
 - "401 Unauthorized": Token is invalid or expired. Generate a new one.
-- "403 Forbidden": Token lacks required permissions. Recreate with Contents read/write.
-- "Encryption error": Key is less than 16 characters or contains invalid characters.
-- "Decryption failed": Wrong encryption key or data was synced with a different key.
+- "403 Forbidden": Token lacks "repo" scope. Recreate with correct permissions.
+- "Not Found": Check token has repo scope for creating private repositories.
+
+### Advanced Options (Optional)
+These settings are auto-detected but can be overridden if needed:
+
+{
+  "token": "ghp_...",
+  "repoOwner": "custom-username",      // Override auto-detected username
+  "repoName": "custom-repo-name",      // Override default .opencode-sync
+  "branch": "custom-branch",           // Override auto-detected main/master
+  "encryptionKey": "your-secret-key"   // Encrypt credentials before sync
+}
+
+### Encryption (Optional)
+If user wants to encrypt credentials:
+1. Add encryptionKey to config (minimum 16 characters)
+2. WARNING: Same key must be used on ALL machines
+3. WARNING: If key is lost, encrypted credentials cannot be recovered
 
 ### Key Rotation (Advanced)
 If user needs to change their encryption key:
 
 1. On ALL machines, update config to include BOTH keys:
 {
-  "plugins": {
-    "oc-sync": {
-      "token": "...",
-      "owner": "...",
-      "repo": "...",
-      "encryptionKey": "<NEW_KEY>",
-      "oldEncryptionKey": "<OLD_KEY>"
-    }
-  }
+  "token": "...",
+  "encryptionKey": "<NEW_KEY>",
+  "oldEncryptionKey": "<OLD_KEY>"
 }
 
 2. Restart OpenCode on each machine. The plugin will:
    - Decrypt using old key (fallback)
    - Re-encrypt using new key on push
 
-3. After ALL machines have synced with the new key, remove oldEncryptionKey from config.
-
-IMPORTANT: Do NOT remove oldEncryptionKey until all machines have synced at least once with the new configuration.
+3. After ALL machines have synced, remove oldEncryptionKey.
 
 ### Summary
 After setup, confirm with user:
-- GitHub username: [OWNER]
-- Repository: [REPO] (private)
 - Token: configured (never display full token)
-- Encryption: enabled/disabled
 - Status: Ready to sync
 ```
 
----
+---

src/plugin/plugin.ts

@@ -179,7 +179,6 @@ async function ensureStorageExists(pathConfig: PathConfig): Promise<void> {
 
     log(`Linked to repo: ${owner}/${repoName}`);
     await updateConfig(pathConfig, { repoOwner: owner, repoName });
-    log('Repo saved to config');
     initializeEngine();
   } catch (error) {
     const errMsg = error instanceof Error ? error.message : String(error);

src/storage/repo/repo-client.ts

@@ -77,8 +77,16 @@ export class RepoStorageBackend implements StorageBackend {
   }
 
   public async exists(): Promise<boolean> {
-    const res = await this.fetch(`/contents/${SYNC_DIR}/manifest.json`);
-    return res.ok;
+    try {
+      const res = await this.fetch(`/contents/${SYNC_DIR}/manifest.json`);
+      return res.ok;
+    } catch (error) {
+      // 404 means file doesn't exist, which is expected for new repos
+      if (error instanceof RepoApiError && error.status === 404) {
+        return false;
+      }
+      throw error;
+    }
   }
 
   public async initialize(manifest: string): Promise<void> {
@@ -170,9 +178,19 @@ export class RepoStorageBackend implements StorageBackend {
   }
 
   private async createOrUpdateFile(path: string, content: string, message: string): Promise<void> {
-    // Get current file SHA if exists
-    const existing = await this.fetch(`/contents/${path}`);
-    const sha = existing.ok ? ((await existing.json()) as ContentFile).sha : undefined;
+    // Get current file SHA if exists (404 means file doesn't exist yet)
+    let sha: string | undefined;
+    try {
+      const existing = await this.fetch(`/contents/${path}`);
+      if (existing.ok) {
+        sha = ((await existing.json()) as ContentFile).sha;
+      }
+    } catch (error) {
+      // 404 is expected for new files
+      if (!(error instanceof RepoApiError && error.status === 404)) {
+        throw error;
+      }
+    }
 
     const body = JSON.stringify({
       message,