realm.json handling

Author: Chris

.gitignore

@@ -8,7 +8,9 @@ dist/
 .env
 .env.local
 
-# Sync artifacts (workspace-specific)
+# Synced workspaces (never commit workspace content)
+stack.cards/
+boxel.ai/
 .boxel-sync.json
 .boxel-history/
 

src/commands/history.ts

@@ -17,7 +17,7 @@ function scanWorkspaceForChanges(workspaceDir: string): CheckpointChange[] {
     for (const entry of entries) {
       // Skip internal files
       if (entry.name.startsWith('.boxel-') || entry.name === '.git') continue;
-      if (entry.name.startsWith('.') && entry.name !== '.realm.json') continue;
+      if (entry.name.startsWith('.')) continue;
 
       const fullPath = path.join(dir, entry.name);
       const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;

src/commands/push.ts

@@ -1,4 +1,4 @@
-import { RealmSyncBase, validateMatrixEnvVars, type SyncOptions } from '../lib/realm-sync-base.js';
+import { RealmSyncBase, validateMatrixEnvVars, isProtectedFile, type SyncOptions } from '../lib/realm-sync-base.js';
 import { CheckpointManager, type CheckpointChange } from '../lib/checkpoint-manager.js';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -88,6 +88,7 @@ class RealmPusher extends RealmSyncBase {
         console.log('Workspace URL changed, will upload all files');
       }
       for (const [relativePath, localPath] of localFiles) {
+        if (isProtectedFile(relativePath)) continue;
         filesToUpload.set(relativePath, localPath);
       }
     } else {
@@ -96,6 +97,10 @@ class RealmPusher extends RealmSyncBase {
       let skipped = 0;
 
       for (const [relativePath, localPath] of localFiles) {
+        if (isProtectedFile(relativePath)) {
+          skipped++;
+          continue;
+        }
         const currentHash = computeFileHash(localPath);
         const previousHash = manifest.files[relativePath];
 
@@ -135,6 +140,13 @@ class RealmPusher extends RealmSyncBase {
       const remoteFiles = await this.getRemoteFileList();
       const filesToDelete = new Set(remoteFiles.keys());
 
+      // Never delete protected files from the server
+      for (const relativePath of filesToDelete) {
+        if (isProtectedFile(relativePath)) {
+          filesToDelete.delete(relativePath);
+        }
+      }
+
       for (const relativePath of localFiles.keys()) {
         filesToDelete.delete(relativePath);
       }

src/commands/sync.ts

@@ -1,4 +1,4 @@
-import { RealmSyncBase, validateMatrixEnvVars, type SyncOptions } from '../lib/realm-sync-base.js';
+import { RealmSyncBase, validateMatrixEnvVars, isProtectedFile, type SyncOptions } from '../lib/realm-sync-base.js';
 import { resolveWorkspace } from '../lib/workspace-resolver.js';
 import { MatrixClient } from '../lib/matrix-client.js';
 import { CheckpointManager, type CheckpointChange } from '../lib/checkpoint-manager.js';
@@ -413,10 +413,15 @@ class RealmSyncer extends RealmSyncBase {
     isFirstSync: boolean,
   ): FileAction[] {
     const actions: FileAction[] = [];
-    // Use remoteFiles for existence check (includes dotfiles like .realm.json)
     const allPaths = new Set([...localFiles.keys(), ...remoteFiles.keys()]);
 
     for (const relativePath of allPaths) {
+      // Protected files (e.g. .realm.json) are server-managed and must never be
+      // pushed, deleted, or overwritten on the server via the CLI.
+      if (isProtectedFile(relativePath)) {
+        continue;
+      }
+
       const localPath = localFiles.get(relativePath);
       const remoteMtime = remoteMtimes.get(relativePath);
       const baseState = manifest?.files[relativePath];
@@ -461,7 +466,7 @@ class RealmSyncer extends RealmSyncBase {
         const localNew = hasLocal && !hasBase;
         const localDeleted = !hasLocal && hasBase;
 
-        // For remote change detection: if file exists but no mtime available (e.g., .realm.json),
+        // For remote change detection: if file exists but no mtime available,
         // we can't detect changes, so assume unchanged
         const remoteChanged = hasRemote && hasBase && remoteMtime !== undefined && remoteMtime !== baseState.remoteMtime;
         const remoteNew = hasRemote && !hasBase;

src/commands/track.ts

@@ -50,7 +50,7 @@ export async function trackCommand(
     for (const entry of entries) {
       // Skip internal files
       if (entry.name.startsWith('.boxel-') || entry.name === '.git') continue;
-      if (entry.name.startsWith('.') && entry.name !== '.realm.json') continue;
+      if (entry.name.startsWith('.')) continue;
 
       const fullPath = path.join(dir, entry.name);
       const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -153,7 +153,7 @@ export async function trackCommand(
       for (const entry of entries) {
         // Skip internal files
         if (entry.name.startsWith('.boxel-') || entry.name === '.git') continue;
-        if (entry.name.startsWith('.') && entry.name !== '.realm.json') continue;
+        if (entry.name.startsWith('.')) continue;
 
         const fullPath = path.join(dir, entry.name);
         const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -243,7 +243,7 @@ export async function trackCommand(
 
         // Skip internal files
         if (filename.startsWith('.boxel-') || filename.includes('.git')) return;
-        if (filename.startsWith('.') && filename !== '.realm.json') return;
+        if (filename.startsWith('.')) return;
 
         // Debounced check for changes
         checkForChanges();

src/commands/watch.ts

@@ -4,6 +4,7 @@ import { MatrixClient } from '../lib/matrix-client.js';
 import { RealmAuthClient } from '../lib/realm-auth-client.js';
 import { resolveWorkspace } from '../lib/workspace-resolver.js';
 import { CheckpointManager, type CheckpointChange } from '../lib/checkpoint-manager.js';
+import { isProtectedFile } from '../lib/realm-sync-base.js';
 import { createHash } from 'crypto';
 import { getEditingFiles } from '../lib/edit-lock.js';
 import { getProfileManager, formatProfileBadge } from '../lib/profile-manager.js';
@@ -266,6 +267,7 @@ export async function watchCommand(
       let hasNewChanges = false;
 
       for (const [file, mtime] of Object.entries(remoteMtimes)) {
+        if (isProtectedFile(file)) continue;
         if (!(file in realm.lastKnownState)) {
           if (!realm.pendingChanges.has(file) || realm.pendingChanges.get(file)!.mtime !== mtime) {
             realm.pendingChanges.set(file, { status: 'added', mtime });

src/lib/checkpoint-manager.ts

@@ -1,6 +1,7 @@
 import { execSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { isProtectedFile } from './realm-sync-base.js';
 
 export interface Checkpoint {
   hash: string;
@@ -105,7 +106,7 @@ export class CheckpointManager {
         if (entry.name === '.boxel-history' || entry.name === '.boxel-sync.json') {
           continue;
         }
-        if (entry.name.startsWith('.') && entry.name !== '.realm.json') {
+        if (entry.name.startsWith('.')) {
           continue;
         }
 
@@ -286,14 +287,12 @@ export class CheckpointManager {
     // - More than 3 files changed
     // - Any .gts file changed (card definition)
     // - Any file added or deleted
-    // - .realm.json changed
 
     if (changes.length > 3) return true;
 
     for (const change of changes) {
       if (change.status === 'added' || change.status === 'deleted') return true;
       if (change.file.endsWith('.gts')) return true;
-      if (change.file === '.realm.json') return true;
     }
 
     return false;
@@ -468,6 +467,7 @@ export class CheckpointManager {
 
     // Remove files that don't exist in the checkpoint
     for (const file of workspaceFiles) {
+      if (isProtectedFile(file)) continue;
       if (!historyFiles.includes(file)) {
         const filePath = path.join(this.workspaceDir, file);
         fs.unlinkSync(filePath);
@@ -476,6 +476,7 @@ export class CheckpointManager {
 
     // Copy files from history to workspace
     for (const file of historyFiles) {
+      if (isProtectedFile(file)) continue;
       const srcPath = path.join(this.gitDir, file);
       const destPath = path.join(this.workspaceDir, file);
 

src/lib/realm-sync-base.ts

@@ -6,6 +6,14 @@ import ignoreModule from 'ignore';
 const ignore = ignoreModule.default || ignoreModule;
 type Ignore = ReturnType<typeof ignore>;
 
+// Files that must never be pushed, deleted, or overwritten on the server via CLI.
+// These are server-managed config files - corrupting them can break a realm.
+export const PROTECTED_FILES = new Set(['.realm.json']);
+
+export function isProtectedFile(relativePath: string): boolean {
+  return PROTECTED_FILES.has(relativePath);
+}
+
 export const SupportedMimeType = {
   CardJson: 'application/vnd.card+json',
   CardSource: 'application/vnd.card+source',
@@ -142,27 +150,6 @@ export abstract class RealmSyncBase {
       throw error;
     }
 
-    // Check for .realm.json in root directory
-    if (!dir) {
-      try {
-        const realmJsonUrl = this.buildFileUrl('.realm.json');
-        const jwt = await this.realmAuthClient.getJWT();
-
-        const response = await fetch(realmJsonUrl, {
-          method: 'HEAD',
-          headers: {
-            Authorization: jwt,
-          },
-        });
-
-        if (response.ok) {
-          files.set('.realm.json', true);
-        }
-      } catch {
-        console.log('Note: .realm.json not found in remote realm');
-      }
-    }
-
     return files;
   }
 
@@ -289,6 +276,11 @@ export abstract class RealmSyncBase {
   }
 
   protected async uploadFile(relativePath: string, localPath: string): Promise<void> {
+    if (isProtectedFile(relativePath)) {
+      console.log(`  Skipped (protected): ${relativePath}`);
+      return;
+    }
+
     console.log(`Uploading: ${relativePath}`);
 
     if (this.options.dryRun) {
@@ -362,6 +354,11 @@ export abstract class RealmSyncBase {
   }
 
   protected async deleteFile(relativePath: string): Promise<void> {
+    if (isProtectedFile(relativePath)) {
+      console.log(`  Skipped (protected): ${relativePath}`);
+      return;
+    }
+
     console.log(`Deleting remote: ${relativePath}`);
 
     if (this.options.dryRun) {
@@ -451,9 +448,6 @@ export abstract class RealmSyncBase {
     }
 
     if (fileName.startsWith('.')) {
-      if (fileName === '.realm.json') {
-        return false;
-      }
       return true;
     }
 
@@ -467,9 +461,6 @@ export abstract class RealmSyncBase {
   private shouldIgnoreRemoteFile(relativePath: string): boolean {
     const fileName = path.basename(relativePath);
     if (fileName.startsWith('.')) {
-      if (fileName === '.realm.json') {
-        return false;
-      }
       return true;
     }
     return false;