Cloudverest for VS Code

Source Control extension for Cloudverest file collaboration. Push, pull, view diffs, manage locks, and track changes directly from VS Code's Source Control panel.

Features

Source Control integration — appears in VS Code's SCM sidebar alongside Git
Push/Pull — upload local changes and download server updates
Inline diffs — click any changed file to see a side-by-side diff with the server version
Quick diff gutter — colored bars in the editor gutter showing changed lines
File decorations — M/A/D/L badges in the Explorer and editor tabs
Conflict resolution — 3-way merge editor when push conflicts arise (VS Code 1.69+)
File locking — lock/unlock files to prevent concurrent editing
Branching — switch branches, create branches, view branch status
Version history — Timeline panel shows file version history with restore/compare
Cloud Files sidebar — browse all cloud files, open/preview without downloading
Team activity — see recent team actions in the sidebar
Real-time sync — WebSocket connection for instant updates when teammates push changes

Installation

From VSIX file

# Build the extension
cd vscode-extension
npm install
npm run build
npm run package    # Creates cloudverest-0.2.0.vsix

# Install in VS Code
code --install-extension cloudverest-0.2.0.vsix

For development (F5 debug)

Open the vscode-extension/ folder in VS Code
Run npm install
Press F5 to launch an Extension Development Host window
Open a folder with a .cloudverest file (or run "Link to Cloudverest Project")

Getting Started

Sign in: The extension will prompt you to sign in when needed, or run the command Cloudverest: Sign In from the Command Palette (Ctrl+Shift+P).
Link a project: Open a folder in VS Code, then run Cloudverest: Link to Cloudverest Project from the Command Palette. Select a project to clone or link.
Use Source Control: Open the Source Control panel (Ctrl+Shift+G). You'll see Cloudverest alongside any Git repos, with three sections:
- Changes — locally modified files (click to diff)
- Incoming Changes — files with newer server versions
- Locked by Others — files locked by teammates
Push changes: Click the cloud-upload icon in the SCM title bar, or press Ctrl+Enter in the commit message box.
Pull changes: Click the cloud-download icon in the SCM title bar.

Commands

All commands are available from the Command Palette (Ctrl+Shift+P, type "Cloudverest"):

Command	Description
Link to Cloudverest Project	Connect workspace folder to a cloud project
Unlink Cloudverest Project	Remove the connection
Push	Upload local changes to server
Pull	Download incoming changes
Refresh	Re-scan for changes
Lock File	Lock a file (right-click in SCM panel)
Unlock File	Unlock a file
Discard Changes	Revert file to server version
View File History	Show version history for a file
Restore This Version	Restore file to a previous version (from Timeline)
Compare with Previous Version	Diff two versions (from Timeline)
Switch Branch	Switch to a different branch
Create Branch	Create a new branch from current
Open Cloud File	Preview a cloud file without downloading

The Cloudverest sidebar (cloud icon in the Activity Bar) shows:

Cloud Files — browse all files in the cloud project. Useful for seeing what files exist without downloading them all.
Branches — view and manage branches (only shown when branching is enabled for the project).
Team Activity — recent actions by team members (uploads, locks, etc.).

Configuration

Setting	Default	Description
`cloudverest.apiUrl`	`https://cloudvault-api.polytooldesign.workers.dev/api`	API base URL. Set to `http://localhost:8787/api` for local development.
`cloudverest.pollInterval`	`300000` (5 min)	Safety-net polling interval in ms. WebSocket is the primary sync mechanism.

How It Works

The extension uses a .cloudverest JSON file in the project root to track which files are synced and at which version. This file is shared with the Electron desktop app and the CLI — all three tools can work with the same project folder.

Change detection: The extension monitors file mtime and size. When a tracked file changes, it appears in the "Changes" group in the SCM panel.

Server sync: On refresh, the extension calls the sync-status API to check which files have newer server versions (shown in "Incoming Changes") and fetches lock information.

Diffs: Clicking a changed file in the SCM panel opens a side-by-side diff. The left side shows the server version (fetched on demand), the right side shows your local file. The editor gutter also shows colored bars for changed lines (Quick Diff).

Building

cd vscode-extension
npm install
npm run build      # One-time build
npm run watch      # Rebuild on changes (for development)
npm run package    # Create .vsix file for distribution

The extension is bundled with esbuild into a single file (dist/extension.js). Firebase and ws are bundled as dependencies.

Local Development

For testing against a local Cloudflare Worker:

Start the worker: cd worker && wrangler dev
In VS Code settings, set cloudverest.apiUrl to http://localhost:8787/api
The worker's dev mode skips Firebase auth, so no login is needed locally

Cloudverest

Ritsea