This document describes the new file operation and comparison endpoints added to make Grid Transit production-ready.
Endpoint: POST /api/file/status
Changes the status of a file in the system.
{
"filePath": "src/components/Button.tsx",
"newStatus": "modified_local"
}filePath(string, required): Relative path to the filenewStatus(string, required): One of:syncednew_localnew_remotemodified_localmodified_remotedeleted_localdeleted_remoteconflictconflict_deleted_remoteconflict_deleted_local
{
"success": true,
"message": "File status updated to modified_local"
}{
"error": "Missing filePath or newStatus"
}200- Status updated successfully400- Missing or invalid parameters500- Server error
Endpoint: POST /api/file/delete
Marks a file for deletion or removes it from specified location.
{
"filePath": "src/old-file.ts",
"deleteWhat": "both"
}filePath(string, required): Relative path to the filedeleteWhat(string, required): One of:"both"- Delete from local and remote"local"- Delete from local client only"remote"- Delete from remote server only
{
"success": true,
"message": "File deleted from both"
}{
"error": "Missing filePath or deleteWhat"
}200- File deleted successfully400- Missing or invalid parameters500- Server error
Endpoint: POST /api/file/rename
Renames a file on both local and remote locations.
{
"oldPath": "src/OldName.tsx",
"newPath": "src/NewName.tsx"
}oldPath(string, required): Current relative pathnewPath(string, required): New relative path (can include directory changes)
{
"success": true,
"message": "File renamed from src/OldName.tsx to src/NewName.tsx"
}{
"error": "Missing oldPath or newPath"
}200- File renamed successfully400- Missing or invalid parameters500- Server error (target exists, permission denied, etc.)
Endpoint: POST /api/compare
Initiates file comparison with immediate return + background processing.
{
"profile": {
"id": "conn-123",
"name": "Production Server",
"type": "SFTP",
"host": "sftp.example.com",
"port": 22,
"username": "deploy",
"password": "secret",
"authType": "password",
"localRoot": "local_dir",
"remoteRoot": "/var/www/html"
},
"phase": "auto"
}profile(object, required): Connection profilephase(string, optional):"auto"(default) or"immediate"(for polling)
{
"success": true,
"localDir": "local_dir",
"remoteDir": "/var/www/html",
"isComparing": true,
"items": [
{
"key": "src/main.ts",
"path": "src/main.ts",
"status": "synced",
"suggestedAction": "already_synced",
"localFile": {
"path": "src/main.ts",
"size": 256,
"mtime": 1704067200000,
"hash": "abc123def456",
"type": "file"
},
"remoteFile": {
"path": "src/main.ts",
"size": 256,
"mtime": 1704067200000,
"hash": "abc123def456",
"type": "file"
},
"priority": 1704067200000,
"isComparingStatus": true
}
]
}success(boolean): Operation successlocalDir(string): Local directory pathremoteDir(string): Remote directory pathisComparing(boolean): NEW - Indicates background comparison is runningitems(array): Array of SyncItem objects
{
key: string; // Unique identifier
path: string; // Relative file path
status: string; // Current sync status
suggestedAction: string; // Recommended action
localFile?: SyncFile | null; // Local file info
remoteFile?: SyncFile | null; // Remote file info
priority: number; // Sort priority
isComparingStatus?: boolean; // NEW - Status still being compared
}- Immediate (< 500ms): Receive file list with
isComparing: true - Background: Status comparison runs on server
- Polling: Client calls
/api/compare-statusevery 1 second - Update: When comparison complete, receive full results with real statuses
200- Success (may still be comparing in background)400- Invalid connection profile500- Server error during scanning
Endpoint: GET /api/compare-status
Polls for completion of background file status comparison.
GET /api/compare-status
No parameters needed.
{
"success": true,
"isComparing": false,
"timestamp": 1704067200000,
"localDir": "local_dir",
"remoteDir": "/var/www/html",
"items": [
{
"key": "src/main.ts",
"path": "src/main.ts",
"status": "modified_local",
"suggestedAction": "upload",
"localFile": { ... },
"remoteFile": { ... },
"priority": 1704067200000
}
]
}{
"success": false,
"isComparing": true
}200- Status returned (may still be comparing)
// Client code
async function pollComparison() {
let attempts = 0;
const interval = setInterval(async () => {
attempts++;
const res = await fetch('/api/compare-status');
const data = await res.json();
if (data.success && !data.isComparing) {
// Comparison complete
updateUI(data.items);
clearInterval(interval);
} else if (attempts > 30) {
// Timeout after 30 seconds
clearInterval(interval);
}
}, 1000); // Poll every second
}async function changeFileStatus(filePath, newStatus) {
const response = await fetch('/api/file/status', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ filePath, newStatus })
});
const data = await response.json();
if (data.success) {
console.log('Status updated:', data.message);
} else {
console.error('Error:', data.error);
}
}
// Usage
await changeFileStatus('src/app.tsx', 'synced');async function deleteFile(filePath, deleteWhat) {
const response = await fetch('/api/file/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ filePath, deleteWhat })
});
const data = await response.json();
return data.success;
}
// Usage
await deleteFile('src/old-file.ts', 'remote');async function compareWithPolling(profile) {
// Phase 1: Get immediate results
const compareRes = await fetch('/api/compare', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ profile })
});
const data = await compareRes.json();
// Display files immediately
displayFiles(data.items);
// Phase 2: Poll if still comparing
if (data.isComparing) {
let attempts = 0;
const pollInterval = setInterval(async () => {
attempts++;
const statusRes = await fetch('/api/compare-status');
const statusData = await statusRes.json();
if (statusData.success && !statusData.isComparing) {
// Update with real statuses
updateFileStatuses(statusData.items);
clearInterval(pollInterval);
} else if (attempts > 30) {
clearInterval(pollInterval); // Timeout
}
}, 1000);
}
}{
"error": "Missing filePath or newStatus"
}Fix: Ensure all required parameters are provided
{
"error": "File not found in snapshot"
}Fix: Path may have changed or file may have been deleted
{
"error": "Target file already exists at new path"
}Fix: Choose a different name or location
{
"error": "Failed to update status: Permission denied"
}Fix: Check file permissions, retry operation
Currently, no rate limiting is implemented. Recommended:
- Limit polling to 1 second intervals
- Maximum 30 polling attempts (30 seconds timeout)
- Batch file operations when possible
- Validate paths - Ensure paths don't escape working directories
- Check permissions - Verify user has access to target locations
- Sanitize input - Remove special characters from file operations
- Log operations - Track all file mutations for audit trail
- CSRF protection - Implement if needed for production
- All credentials handled securely in connection profile
- File operations logged to history
- No sensitive data in responses
✅ Fully Compatible
- Existing
/api/comparecalls still work - Old clients ignore
isComparingandisComparingStatusfields - New fields are optional and don't break parsing
- Added two-phase comparison with background processing
- Added file operation endpoints (status, delete, rename)
- Added polling endpoint for completion tracking
- Enhanced SyncItem interface with metadata flag
- Original single-phase comparison
- Limited file operations
- File must wait for full comparison
Potential additions for v3.0:
- WebSocket support for real-time status updates
- Batch operations endpoint
- File preview endpoint
- Advanced filtering API
- Sync scheduling API
- Webhook support for external integrations
# Check file status
curl -X POST http://localhost:3000/api/file/status \
-H "Content-Type: application/json" \
-d '{"filePath":"src/main.ts","newStatus":"synced"}'
# Delete file
curl -X POST http://localhost:3000/api/file/delete \
-H "Content-Type: application/json" \
-d '{"filePath":"src/old.ts","deleteWhat":"both"}'
# Poll comparison status
curl http://localhost:3000/api/compare-status- Create POST request to
http://localhost:3000/api/file/status - Headers:
Content-Type: application/json - Body (JSON):
{ "filePath": "src/main.ts", "newStatus": "modified_local" } - Send and check response
For API questions, refer to:
- Implementation: src/server/api-router.ts
- Types: src/server/api-router.ts (SyncItem interface)
- Client usage: src/stores/sync-store.ts