@cardstack/boxel-cli 0.0.1

package/src/lib/sync-logic.ts

@@ -0,0 +1,169 @@
+import type { SyncManifest } from './sync-manifest';
+
+export type SideStatus = 'unchanged' | 'changed' | 'added' | 'deleted';
+export type SyncAction =
+  | 'push'
+  | 'pull'
+  | 'push-delete'
+  | 'pull-delete'
+  | 'conflict'
+  | 'noop';
+
+export interface FileClassification {
+  relativePath: string;
+  localStatus: SideStatus;
+  remoteStatus: SideStatus;
+  action: SyncAction;
+}
+
+export type ConflictStrategy =
+  | 'prefer-local'
+  | 'prefer-remote'
+  | 'prefer-newest';
+
+export interface SyncOptions {
+  deleteSync?: boolean;
+  preferLocal?: boolean;
+  preferRemote?: boolean;
+}
+
+export function classifyLocal(
+  relativePath: string,
+  localHashes: Map<string, string>,
+  manifest: SyncManifest | null,
+): SideStatus {
+  const hasLocal = localHashes.has(relativePath);
+  const inManifest = manifest?.files[relativePath] !== undefined;
+
+  if (hasLocal && inManifest) {
+    return localHashes.get(relativePath) === manifest!.files[relativePath]
+      ? 'unchanged'
+      : 'changed';
+  }
+  if (hasLocal && !inManifest) return 'added';
+  if (!hasLocal && inManifest) return 'deleted';
+  // Not local, not in manifest — this file only exists remotely
+  return 'unchanged'; // not relevant on local side
+}
+
+export function classifyRemote(
+  relativePath: string,
+  remoteMtimes: Map<string, number>,
+  manifest: SyncManifest | null,
+): SideStatus {
+  const hasRemote = remoteMtimes.has(relativePath);
+  const inManifestMtimes = manifest?.remoteMtimes?.[relativePath] !== undefined;
+  // Use manifest.files as secondary known-paths set when remoteMtimes is missing
+  const inManifestFiles = manifest?.files[relativePath] !== undefined;
+  const knownInManifest = inManifestMtimes || inManifestFiles;
+
+  if (hasRemote && inManifestMtimes) {
+    return remoteMtimes.get(relativePath) ===
+      manifest!.remoteMtimes![relativePath]
+      ? 'unchanged'
+      : 'changed';
+  }
+  // Known in manifest.files but no mtime to compare — treat as changed, not added
+  if (hasRemote && inManifestFiles) return 'changed';
+  if (hasRemote && !knownInManifest) return 'added';
+  if (!hasRemote && knownInManifest) return 'deleted';
+  // Not remote, not in manifest — only exists locally
+  return 'unchanged'; // not relevant on remote side
+}
+
+export function determineAction(
+  local: SideStatus,
+  remote: SideStatus,
+  syncOptions: SyncOptions,
+): SyncAction {
+  // Both unchanged
+  if (local === 'unchanged' && remote === 'unchanged') return 'noop';
+
+  // One side changed, other unchanged
+  if (local === 'changed' && remote === 'unchanged') return 'push';
+  if (local === 'unchanged' && remote === 'changed') return 'pull';
+
+  // One side added, other doesn't exist
+  if (local === 'added' && remote === 'unchanged') return 'push';
+  if (local === 'unchanged' && remote === 'added') return 'pull';
+
+  // Both changed or both added — conflict
+  if (
+    (local === 'changed' && remote === 'changed') ||
+    (local === 'added' && remote === 'added')
+  ) {
+    return 'conflict';
+  }
+
+  // Cross-state conflicts (e.g., manifest missing remoteMtimes)
+  if (
+    (local === 'changed' && remote === 'added') ||
+    (local === 'added' && remote === 'changed')
+  ) {
+    return 'conflict';
+  }
+
+  // Deletions
+  if (local === 'deleted' && remote === 'unchanged') {
+    return syncOptions.deleteSync || syncOptions.preferLocal
+      ? 'push-delete'
+      : 'noop';
+  }
+  if (local === 'unchanged' && remote === 'deleted') {
+    return syncOptions.deleteSync || syncOptions.preferRemote
+      ? 'pull-delete'
+      : 'noop';
+  }
+
+  // Delete vs change conflicts
+  if (local === 'deleted' && remote === 'changed') return 'conflict';
+  if (local === 'changed' && remote === 'deleted') return 'conflict';
+
+  // Both deleted
+  if (local === 'deleted' && remote === 'deleted') return 'noop';
+
+  // Added vs deleted (shouldn't normally happen but handle gracefully)
+  if (local === 'added' && remote === 'deleted') return 'push';
+  if (local === 'deleted' && remote === 'added') return 'pull';
+
+  return 'noop';
+}
+
+export function resolveConflict(
+  classification: FileClassification,
+  localFilesWithMtimes: Map<string, { path: string; mtime: number }>,
+  remoteMtimes: Map<string, number>,
+  strategy: ConflictStrategy | null,
+): SyncAction | null {
+  const { localStatus, remoteStatus, relativePath } = classification;
+
+  if (!strategy) return null; // skip — no strategy
+
+  switch (strategy) {
+    case 'prefer-local':
+      if (localStatus === 'deleted') return 'push-delete';
+      return 'push';
+
+    case 'prefer-remote':
+      if (remoteStatus === 'deleted') return 'pull-delete';
+      return 'pull';
+
+    case 'prefer-newest': {
+      // For delete-vs-change, the change always wins
+      if (localStatus === 'deleted' && remoteStatus === 'changed')
+        return 'pull';
+      if (localStatus === 'changed' && remoteStatus === 'deleted')
+        return 'push';
+
+      const localInfo = localFilesWithMtimes.get(relativePath);
+      const remoteMtime = remoteMtimes.get(relativePath);
+
+      if (localInfo && remoteMtime !== undefined) {
+        // Remote mtimes are in seconds (epoch), local mtimes are in ms
+        return localInfo.mtime > remoteMtime * 1000 ? 'push' : 'pull';
+      }
+      // If we can't compare, prefer local (it's what the user has)
+      return 'push';
+    }
+  }
+}

package/src/lib/sync-manifest.ts

@@ -0,0 +1,81 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+export interface SyncManifest {
+  realmUrl: string;
+  files: Record<string, string>; // relativePath -> contentHash
+  remoteMtimes?: Record<string, number>; // relativePath -> last-seen server mtime
+}
+
+export function isValidManifest(value: unknown): value is SyncManifest {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.realmUrl !== 'string') return false;
+  if (typeof v.files !== 'object' || v.files === null) return false;
+  for (const hash of Object.values(v.files as Record<string, unknown>)) {
+    if (typeof hash !== 'string') return false;
+  }
+  if (v.remoteMtimes !== undefined) {
+    if (typeof v.remoteMtimes !== 'object' || v.remoteMtimes === null) {
+      return false;
+    }
+    for (const mtime of Object.values(
+      v.remoteMtimes as Record<string, unknown>,
+    )) {
+      if (typeof mtime !== 'number') return false;
+    }
+  }
+  return true;
+}
+
+export async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function computeFileHash(filePath: string): Promise<string> {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+export async function loadManifest(
+  localDir: string,
+): Promise<SyncManifest | null> {
+  const manifestPath = path.join(localDir, '.boxel-sync.json');
+  let content: string;
+  try {
+    content = await fs.readFile(manifestPath, 'utf8');
+  } catch (err: any) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+
+  if (!isValidManifest(parsed)) {
+    console.warn(
+      'Warning: .boxel-sync.json is malformed or has an unexpected shape; falling back to a full upload.',
+    );
+    return null;
+  }
+
+  return parsed;
+}
+
+export async function saveManifest(
+  localDir: string,
+  manifest: SyncManifest,
+): Promise<void> {
+  const manifestPath = path.join(localDir, '.boxel-sync.json');
+  await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+}