@bobfrankston/gcards 0.1.21 → 0.1.23

package/gcards.ts

@@ -8,6 +8,7 @@ import fs from 'fs';
 import fp from 'fs/promises';
 import path from 'path';
 import crypto from 'crypto';
+import { parse as parseJsonc } from 'jsonc-parser';
 import { parseArgs, showUsage, showHelp } from './glib/parsecli.ts';
 import { authenticateOAuth } from '../../../projects/oauth/oauthsupport/index.ts';
 import type { GooglePerson, GoogleConnectionsResponse } from './glib/types.ts';
@@ -150,7 +151,23 @@ function saveIndex(paths: UserPaths, index: ContactIndex): void {
         sortedContacts[key] = value;
     }
     index.contacts = sortedContacts;
-    fs.writeFileSync(paths.indexFile, JSON.stringify(index, null, 2));
+    
+    // Add helpful comments to the file
+    const comment = `// index.json - Active contacts index
+// This file tracks all contacts synced from Google.
+//
+// Special fields:
+//   _delete: Set to 'force' to mark a contact for deletion on next push
+//            Set to 'queue' to mark for interactive deletion review
+//   hasPhoto: Indicates contact has a non-default photo
+//   starred: Indicates contact is starred in Google
+//   guids: Array of GUID values from userDefined fields
+//
+// To delete a contact: Add "_delete": "force" to the entry, then run 'gcards push'
+// To queue for review: Add "_delete": "queue" to the entry
+//
+`;
+    fs.writeFileSync(paths.indexFile, comment + JSON.stringify(index, null, 2));
 }
 
 /** Deleted contacts index (separate from active index) */
@@ -160,7 +177,11 @@ interface DeletedIndex {
 
 function loadDeleted(paths: UserPaths): DeletedIndex {
     if (fs.existsSync(paths.deletedFile)) {
-        return JSON.parse(fs.readFileSync(paths.deletedFile, 'utf-8'));
+        try {
+            return parseJsonc(fs.readFileSync(paths.deletedFile, 'utf-8'));
+        } catch (e: any) {
+            throw new Error(`Failed to parse ${paths.deletedFile}: ${e.message}`);
+        }
     }
     return { deleted: {} };
 }
@@ -174,7 +195,18 @@ function saveDeleted(paths: UserPaths, deletedIndex: DeletedIndex): void {
         sorted[key] = value;
     }
     deletedIndex.deleted = sorted;
-    fs.writeFileSync(paths.deletedFile, JSON.stringify(deletedIndex, null, 2));
+    
+    // Add helpful comments
+    const comment = `// deleted.json - Tombstone index of deleted contacts
+// This file tracks contacts that have been deleted from Google.
+// These entries are kept for historical reference and audit purposes.
+//
+// Fields:
+//   deletedAt: ISO timestamp when the contact was deleted
+//   _delete: Reason for deletion ('server', 'force', 'queue', etc.)
+//
+`;
+    fs.writeFileSync(paths.deletedFile, comment + JSON.stringify(deletedIndex, null, 2));
 }
 
 interface SavedPhoto {
@@ -194,7 +226,11 @@ interface PhotosIndex {
 
 function loadPhotos(paths: UserPaths): PhotosIndex {
     if (fs.existsSync(paths.photosFile)) {
-        return JSON.parse(fs.readFileSync(paths.photosFile, 'utf-8'));
+        try {
+            return parseJsonc(fs.readFileSync(paths.photosFile, 'utf-8'));
+        } catch (e: any) {
+            throw new Error(`Failed to parse ${paths.photosFile}: ${e.message}`);
+        }
     }
     return { photos: {} };
 }
@@ -208,19 +244,90 @@ function savePhotos(paths: UserPaths, photosIndex: PhotosIndex): void {
         sorted[key] = value;
     }
     photosIndex.photos = sorted;
-    fs.writeFileSync(paths.photosFile, JSON.stringify(photosIndex, null, 2));
+
+    // Add helpful comments
+    const comment = `// _photos.json - Saved photos from deleted or merged contacts
+// This file preserves photo URLs when contacts are deleted or merged.
+// Photos are saved automatically during sync and merge operations.
+//
+// Fields:
+//   displayName: Contact's display name when photo was saved
+//   photos: Array of photo objects with url and sourceType
+//   deletedAt: ISO timestamp when the photo was saved
+//
+`;
+    // Save JSON data file
+    fs.writeFileSync(paths.photosFile, comment + JSON.stringify(photosIndex, null, 2));
+
+    // Generate HTML view
+    const html = `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Saved Photos from Deleted Contacts</title>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 20px; }
+        h1 { color: #333; }
+        table { border-collapse: collapse; width: 100%; }
+        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; vertical-align: middle; }
+        th { background: #f5f5f5; }
+        tr:hover { background: #f9f9f9; }
+        img { width: 100px; height: 100px; object-fit: cover; border-radius: 4px; }
+        a { color: #1a73e8; text-decoration: none; }
+        a:hover { text-decoration: underline; }
+        .deleted { font-size: 12px; color: #666; }
+    </style>
+</head>
+<body>
+    <h1>Saved Photos from Deleted Contacts (${entries.length})</h1>
+    <table>
+        <tr><th>Photo</th><th>Name</th></tr>
+${entries.map(([resourceName, entry]) => {
+    const id = resourceName.replace('people/', '');
+    const contactUrl = `https://contacts.google.com/person/${id}`;
+    const photoUrl = entry.photos[0]?.url || '';
+    return `        <tr>
+            <td>${photoUrl ? `<img src="${photoUrl}" alt="${entry.displayName}" loading="lazy">` : '(no photo)'}</td>
+            <td><a href="${contactUrl}" target="_blank">${entry.displayName}</a><br><span class="deleted">Deleted: ${entry.deletedAt?.split('T')[0] || 'unknown'}</span></td>
+        </tr>`;
+}).join('\n')}
+    </table>
+</body>
+</html>`;
+    fs.writeFileSync(paths.photosHtmlFile, html);
 }
 
 function loadDeleteQueue(paths: UserPaths): DeleteQueue {
     if (fs.existsSync(paths.deleteQueueFile)) {
-        return JSON.parse(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
+        try {
+            return parseJsonc(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
+        } catch (e: any) {
+            throw new Error(`Failed to parse ${paths.deleteQueueFile}: ${e.message}`);
+        }
     }
     return { updatedAt: '', entries: [] };
 }
 
 function saveDeleteQueue(paths: UserPaths, queue: DeleteQueue): void {
     queue.updatedAt = new Date().toISOString();
-    fs.writeFileSync(paths.deleteQueueFile, JSON.stringify(queue, null, 2));
+    
+    // Add helpful comments
+    const comment = `// _delete.json - Pending deletion queue
+// This file contains contacts marked for deletion that require review.
+// Run 'gcards push' to process deletions (will prompt for confirmation unless --yes flag is used).
+//
+// Fields:
+//   resourceName: Google resource name (people/xxxxx)
+//   displayName: Contact's display name
+//   reason: Reason for deletion (e.g., '*photo', '*starred')
+//   _delete: Deletion mode ('queue', 'force', etc.)
+//   queuedAt: ISO timestamp when added to queue
+//
+// To skip deletion: Remove the entry from this file
+// To force deletion: Change _delete value to 'force'
+//
+`;
+    fs.writeFileSync(paths.deleteQueueFile, comment + JSON.stringify(queue, null, 2));
 }
 
 function extractNonDefaultPhotos(contact: GooglePerson): SavedPhoto[] {
@@ -249,14 +356,23 @@ function generateGuid(): string {
 
 function loadSyncToken(paths: UserPaths): string {
     if (fs.existsSync(paths.syncTokenFile)) {
-        const data = JSON.parse(fs.readFileSync(paths.syncTokenFile, 'utf-8'));
-        return data.syncToken || null;
+        try {
+            const data = parseJsonc(fs.readFileSync(paths.syncTokenFile, 'utf-8'));
+            return data.syncToken || null;
+        } catch (e: any) {
+            throw new Error(`Failed to parse ${paths.syncTokenFile}: ${e.message}`);
+        }
     }
     return null;
 }
 
 function saveSyncToken(paths: UserPaths, token: string): void {
-    fs.writeFileSync(paths.syncTokenFile, JSON.stringify({ syncToken: token, savedAt: new Date().toISOString() }, null, 2));
+    const comment = `// sync-token.json - Google Contacts API sync token
+// This token enables incremental sync, fetching only changes since last sync.
+// Delete this file to force a full sync on next run.
+//
+`;
+    fs.writeFileSync(paths.syncTokenFile, comment + JSON.stringify({ syncToken: token, savedAt: new Date().toISOString() }, null, 2));
 }
 
 async function sleep(ms: number): Promise<void> {
@@ -334,7 +450,14 @@ function saveContact(paths: UserPaths, person: GooglePerson): void {
 
     const id = person.resourceName.replace('people/', '');
     const filePath = path.join(paths.contactsDir, `${id}.json`);
-    fs.writeFileSync(filePath, JSON.stringify(person, null, 2));
+    
+    // Add helpful comment for contact files
+    const comment = `// Contact file from Google People API
+// To delete this contact: Add "_delete": "force" field at root level, then run 'gcards push'
+// To modify: Edit this file, then run 'gcards push' to sync changes to Google
+//
+`;
+    fs.writeFileSync(filePath, comment + JSON.stringify(person, null, 2));
 }
 
 function deleteContactFile(paths: UserPaths, resourceName: string): void {
@@ -439,7 +562,7 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
                         // Save photos before deleting
                         if (fs.existsSync(contactFile)) {
                             try {
-                                const contact = JSON.parse(fs.readFileSync(contactFile, 'utf-8')) as GooglePerson;
+                                const contact = parseJsonc(fs.readFileSync(contactFile, 'utf-8')) as GooglePerson;
                                 const photos = extractNonDefaultPhotos(contact);
                                 if (photos.length > 0) {
                                     photosIndex.photos[person.resourceName] = {
@@ -461,12 +584,16 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
                             if (!fs.existsSync(paths.deletedDir)) {
                                 fs.mkdirSync(paths.deletedDir, { recursive: true });
                             }
-                            const contactData = JSON.parse(fs.readFileSync(contactFile, 'utf-8'));
-                            contactData._deletedAt = new Date().toISOString();
-                            contactData._delete = 'server';
-                            const destPath = path.join(paths.deletedDir, `${id}.json`);
-                            fs.writeFileSync(destPath, JSON.stringify(contactData, null, 2));
-                            fs.unlinkSync(contactFile);
+                            try {
+                                const contactData = parseJsonc(fs.readFileSync(contactFile, 'utf-8'));
+                                contactData._deletedAt = new Date().toISOString();
+                                contactData._delete = 'server';
+                                const destPath = path.join(paths.deletedDir, `${id}.json`);
+                                fs.writeFileSync(destPath, JSON.stringify(contactData, null, 2));
+                                fs.unlinkSync(contactFile);
+                            } catch (e: any) {
+                                console.error(`\n[PARSE ERROR] ${id}.json: ${e.message}`);
+                            }
                         }
 
                         deleted++;
@@ -554,6 +681,30 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
     const activeContacts = Object.keys(index.contacts).length;
     const tombstones = Object.keys(deletedIndex.deleted).length;
 
+    // Move orphaned files if doing full sync
+    let orphaned = 0;
+    if (options.full && fs.existsSync(paths.contactsDir)) {
+        const contactFiles = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+        const indexedResourceNames = new Set(
+            Object.keys(index.contacts).map(rn => rn.replace('people/', '') + '.json')
+        );
+        
+        for (const file of contactFiles) {
+            if (!indexedResourceNames.has(file)) {
+                if (!fs.existsSync(paths.orphansDir)) {
+                    fs.mkdirSync(paths.orphansDir, { recursive: true });
+                }
+                const src = path.join(paths.contactsDir, file);
+                const dst = path.join(paths.orphansDir, file);
+                fs.renameSync(src, dst);
+                orphaned++;
+                if (options.verbose) {
+                    console.log(`\n  Orphaned: ${file}`);
+                }
+            }
+        }
+    }
+
     console.log(`\n\nSync complete:`);
     console.log(`  Processed: ${totalProcessed}`);
     console.log(`  Added: ${added}`);
@@ -562,13 +713,20 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
     if (conflicts > 0) {
         console.log(`  Conflicts: ${conflicts} (delete local file and sync to resolve)`);
     }
+    if (orphaned > 0) {
+        console.log(`  Orphaned: ${orphaned} (moved to orphans/)`);
+    }
     console.log(`  Active contacts: ${activeContacts}`);
     console.log(`  Tombstones: ${tombstones}`);
 }
 
 function loadStatus(paths: UserPaths): PushStatus {
     if (fs.existsSync(paths.statusFile)) {
-        return JSON.parse(fs.readFileSync(paths.statusFile, 'utf-8'));
+        try {
+            return parseJsonc(fs.readFileSync(paths.statusFile, 'utf-8'));
+        } catch (e: any) {
+            throw new Error(`Failed to parse ${paths.statusFile}: ${e.message}`);
+        }
     }
     return { lastPush: '' };
 }
@@ -628,7 +786,7 @@ async function findPendingChanges(paths: UserPaths, logger: FileLogger, since?:
             checked++;
             let content: GooglePerson & { _delete?: boolean };
             try {
-                content = JSON.parse(await fp.readFile(filePath, 'utf-8'));
+                content = parseJsonc(await fp.readFile(filePath, 'utf-8'));
             } catch (e: any) {
                 const errMsg = `[PARSE ERROR] ${file}: ${e.message}`;
                 parseErrors.push(errMsg);
@@ -666,7 +824,7 @@ async function findPendingChanges(paths: UserPaths, logger: FileLogger, since?:
             const filePath = path.join(paths.toDeleteDir, file);
             let content: GooglePerson & { _delete?: string | boolean };
             try {
-                content = JSON.parse(await fp.readFile(filePath, 'utf-8'));
+                content = parseJsonc(await fp.readFile(filePath, 'utf-8'));
             } catch (e: any) {
                 const errMsg = `[PARSE ERROR] ${file}: ${e.message}`;
                 parseErrors.push(errMsg);
@@ -692,7 +850,7 @@ async function findPendingChanges(paths: UserPaths, logger: FileLogger, since?:
             const filePath = path.join(paths.toAddDir, file);
             let content: GooglePerson;
             try {
-                content = JSON.parse(await fp.readFile(filePath, 'utf-8'));
+                content = parseJsonc(await fp.readFile(filePath, 'utf-8'));
             } catch (e: any) {
                 const errMsg = `[PARSE ERROR] ${file}: ${e.message}`;
                 parseErrors.push(errMsg);
@@ -962,7 +1120,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
         processed++;
         try {
             if (change.type === 'add') {
-                const content = JSON.parse(fs.readFileSync(change.filePath, 'utf-8')) as GooglePerson;
+                const content = parseJsonc(fs.readFileSync(change.filePath, 'utf-8')) as GooglePerson;
                 process.stdout.write(`${ts()} [${String(processed).padStart(5)}/${total}] Creating ${change.displayName}...`);
                 const created = await createContactOnGoogle(content);
 
@@ -996,7 +1154,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 console.log(` done (${created.resourceName})`);
                 successCount++;
             } else if (change.type === 'update') {
-                const content = JSON.parse(fs.readFileSync(change.filePath, 'utf-8')) as GooglePerson;
+                const content = parseJsonc(fs.readFileSync(change.filePath, 'utf-8')) as GooglePerson;
                 process.stdout.write(`${ts()} [${String(processed).padStart(5)}/${total}] Updating ${change.displayName}...`);
                 await updateContactOnGoogle(content);
 
@@ -1017,7 +1175,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 let isForced = change._delete === 'force' || index.contacts[change.resourceName]?._delete === 'force';
                 if (fs.existsSync(fileToRead)) {
                     try {
-                        const contact = JSON.parse(fs.readFileSync(fileToRead, 'utf-8')) as GooglePerson;
+                        const contact = parseJsonc(fs.readFileSync(fileToRead, 'utf-8')) as GooglePerson;
                         contactHasPhoto = hasNonDefaultPhoto(contact);
                         contactIsStarred = isStarred(contact);
                         if ((contact as any)._delete === 'force') isForced = true;
@@ -1071,7 +1229,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                     }
                     if (fs.existsSync(contactFile)) {
                         // Add deletion metadata to the JSON file
-                        const contactData = JSON.parse(fs.readFileSync(contactFile, 'utf-8'));
+                        const contactData = parseJsonc(fs.readFileSync(contactFile, 'utf-8'));
                         contactData._deletedAt = new Date().toISOString();
                         contactData._delete = change._delete || entry?._delete || 'unknown';
                         const destPath = path.join(paths.deletedDir, path.basename(contactFile));
@@ -1090,7 +1248,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 }
             }
 
-            await sleep(700);  // 90 writes/min limit = ~700ms between ops
+            await sleep(1500);  // Google tightened limits - need ~1.5s between ops
         } catch (error: any) {
             const fileName = path.basename(change.filePath);
             const errorMsg = `${fileName}: ${error.message}`;
@@ -1104,6 +1262,26 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 continue;
             }
 
+            // Check for 404 - contact deleted on server, remove locally
+            if (error.message?.includes('404') || error.message?.includes('NOT_FOUND')) {
+                console.log(`    → Contact deleted on Google. Removing local copy.`);
+                // Move to deleted folder
+                if (fs.existsSync(change.filePath)) {
+                    const id = path.basename(change.filePath, '.json');
+                    if (!fs.existsSync(paths.deletedDir)) {
+                        fs.mkdirSync(paths.deletedDir, { recursive: true });
+                    }
+                    const destPath = path.join(paths.deletedDir, `${id}.json`);
+                    fs.renameSync(change.filePath, destPath);
+                }
+                // Remove from index
+                if (index.contacts[change.resourceName]) {
+                    delete index.contacts[change.resourceName];
+                    saveIndex(paths, index);
+                }
+                continue;
+            }
+
             // Get AI explanation if available and error is from API
             if (error instanceof ApiError && error.payload) {
                 if (isAIAvailable()) {
@@ -1169,7 +1347,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
             let email = '';
             if (nd.filePath && fs.existsSync(nd.filePath)) {
                 try {
-                    const contact = JSON.parse(fs.readFileSync(nd.filePath, 'utf-8'));
+                    const contact = parseJsonc(fs.readFileSync(nd.filePath, 'utf-8'));
                     email = contact.emailAddresses?.[0]?.value || '';
                 } catch { /* ignore */ }
             }

package/gfix.ts

@@ -19,14 +19,17 @@ import { mergeContacts as mergeContactData, collectSourcePhotos, type MergeEntry
 
 function loadDeleteQueue(paths: UserPaths): DeleteQueue {
     if (fs.existsSync(paths.deleteQueueFile)) {
-        return JSON.parse(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
+        return parseJsonc(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
     }
     return { updatedAt: '', entries: [] };
 }
 
 function saveDeleteQueue(paths: UserPaths, queue: DeleteQueue): void {
     queue.updatedAt = new Date().toISOString();
-    fs.writeFileSync(paths.deleteQueueFile, JSON.stringify(queue, null, 2));
+    
+    // Add helpful comments
+    const comment = `// _delete.json - Pending deletion queue\n// This file contains contacts marked for deletion that require review.\n// Run 'gcards push' to process deletions (will prompt for confirmation unless --yes flag is used).\n//\n// Fields:\n//   resourceName: Google resource name (people/xxxxx)\n//   displayName: Contact's display name\n//   reason: Reason for deletion (e.g., '*photo', '*starred')\n//   _delete: Deletion mode ('queue', 'force', etc.)\n//   queuedAt: ISO timestamp when added to queue\n//\n// To skip deletion: Remove the entry from this file\n// To force deletion: Change _delete value to 'force'\n//\n`;
+    fs.writeFileSync(paths.deleteQueueFile, comment + JSON.stringify(queue, null, 2));
 }
 
 interface BirthdayEntry {
@@ -323,7 +326,7 @@ async function runBirthdayExtract(user: string, mode: 'inspect' | 'apply'): Prom
 
     for (const file of files) {
         const filePath = path.join(paths.contactsDir, file);
-        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
 
         if (!contact.birthdays?.length) continue;
 
@@ -413,7 +416,7 @@ async function runFileAsFix(user: string, mode: 'inspect' | 'apply'): Promise<vo
 
     for (const file of files) {
         const filePath = path.join(paths.contactsDir, file);
-        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
 
         const name = contact.names?.[0];
         const givenName = name?.givenName || '';
@@ -1132,7 +1135,7 @@ async function runNamesFix(user: string, mode: 'inspect' | 'apply'): Promise<voi
                 const dst = path.join(paths.toDeleteDir, entry.file);
                 fs.renameSync(src, dst);
             }
-            const existing = fs.existsSync(emailOnlyFile) ? JSON.parse(fs.readFileSync(emailOnlyFile, 'utf-8')) : [];
+            const existing = fs.existsSync(emailOnlyFile) ? parseJsonc(fs.readFileSync(emailOnlyFile, 'utf-8')) : [];
             existing.push(...emailOnly.map(e => ({ file: e.file, resourceName: e.resourceName, email: e.email, movedAt: new Date().toISOString() })));
             fs.writeFileSync(emailOnlyFile, JSON.stringify(existing, null, 2));
         }
@@ -1143,7 +1146,7 @@ async function runNamesFix(user: string, mode: 'inspect' | 'apply'): Promise<voi
                 const dst = path.join(paths.toDeleteDir, entry.file);
                 fs.renameSync(src, dst);
             }
-            const existing = fs.existsSync(phoneOnlyFile) ? JSON.parse(fs.readFileSync(phoneOnlyFile, 'utf-8')) : [];
+            const existing = fs.existsSync(phoneOnlyFile) ? parseJsonc(fs.readFileSync(phoneOnlyFile, 'utf-8')) : [];
             existing.push(...phoneOnly.map(e => ({ file: e.file, resourceName: e.resourceName, phone: e.phone, movedAt: new Date().toISOString() })));
             fs.writeFileSync(phoneOnlyFile, JSON.stringify(existing, null, 2));
         }
@@ -1216,7 +1219,7 @@ async function runFix(user: string, mode: 'inspect' | 'apply'): Promise<void> {
 
     for (const file of files) {
         const filePath = path.join(paths.contactsDir, file);
-        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
         const changes = processContact(contact);
 
         if (changes.length > 0) {
@@ -1303,7 +1306,13 @@ async function runUndup(user: string): Promise<void> {
 
     for (const file of files) {
         const filePath = path.join(paths.contactsDir, file);
-        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        let contact: GooglePerson;
+        try {
+            contact = parseJsonc(fs.readFileSync(filePath, 'utf-8'));
+        } catch (e: any) {
+            console.error(`[PARSE ERROR] ${file}: ${e.message}`);
+            continue;
+        }
 
         const name = contact.names?.[0];
         if (!name) continue;
@@ -1438,14 +1447,14 @@ async function runMerge(user: string, limit: number): Promise<void> {
     const paths = getUserPaths(user);
     const mergerPath = path.join(paths.userDir, 'merger.json');
     const mergedPath = path.join(paths.userDir, 'merged.json');
-    const photosPath = path.join(paths.userDir, 'photos.json');
+    const photosPath = paths.photosFile;  // _photos.json
 
     if (!fs.existsSync(mergerPath)) {
         console.error(`No merger.json found. Run 'gfix undup -u ${user}' first.`);
         process.exit(1);
     }
 
-    let entries: MergeEntry[] = JSON.parse(fs.readFileSync(mergerPath, 'utf-8'));
+    let entries: MergeEntry[] = parseJsonc(fs.readFileSync(mergerPath, 'utf-8'));
 
     if (entries.length === 0) {
         console.log('No entries in merger.json');
@@ -1478,7 +1487,8 @@ async function runMerge(user: string, limit: number): Promise<void> {
     // Load existing files
     let savedPhotos: PhotoEntry[] = [];
     if (fs.existsSync(photosPath)) {
-        savedPhotos = JSON.parse(fs.readFileSync(photosPath, 'utf-8'));
+        const parsed = parseJsonc(fs.readFileSync(photosPath, 'utf-8'));
+        savedPhotos = Array.isArray(parsed) ? parsed : [];
     }
 
     const deleteQueue = loadDeleteQueue(paths);
@@ -1489,7 +1499,8 @@ async function runMerge(user: string, limit: number): Promise<void> {
         const content = fs.readFileSync(mergedPath, 'utf-8').trim();
         if (content) {
             try {
-                mergedEntries = JSON.parse(content);
+                const parsed = parseJsonc(content);
+                mergedEntries = Array.isArray(parsed) ? parsed : [];
             } catch { /* ignore parse errors, start fresh */ }
         }
     }
@@ -1509,7 +1520,7 @@ async function runMerge(user: string, limit: number): Promise<void> {
                 const id = rn.replace('people/', '');
                 const filePath = path.join(paths.contactsDir, `${id}.json`);
                 if (fs.existsSync(filePath)) {
-                    contacts.push(JSON.parse(fs.readFileSync(filePath, 'utf-8')));
+                    contacts.push(parseJsonc(fs.readFileSync(filePath, 'utf-8')));
                 } else {
                     throw new Error(`Contact file not found: ${filePath}`);
                 }
@@ -1586,7 +1597,7 @@ async function runMerge(user: string, limit: number): Promise<void> {
             const id = rn.replace('people/', '');
             const filePath = path.join(paths.contactsDir, `${id}.json`);
             if (fs.existsSync(filePath)) {
-                const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+                const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
                 const displayName = contact.names?.[0]?.displayName || entry.name;
                 deleteQueue.entries.push({
                     resourceName: rn,
@@ -1605,9 +1616,47 @@ async function runMerge(user: string, limit: number): Promise<void> {
         mergedEntries.push(entry);
     }
 
-    // Save photos.json
+    // Save photos (JSON data + HTML view)
     if (savedPhotos.length > 0) {
         fs.writeFileSync(photosPath, JSON.stringify(savedPhotos, null, 2));
+
+        // Generate HTML view
+        const htmlPath = paths.photosHtmlFile;
+        const html = `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Saved Photos from Merged Contacts</title>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 20px; }
+        h1 { color: #333; }
+        table { border-collapse: collapse; width: 100%; }
+        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; vertical-align: middle; }
+        th { background: #f5f5f5; }
+        tr:hover { background: #f9f9f9; }
+        img { width: 100px; height: 100px; object-fit: cover; border-radius: 4px; margin: 2px; }
+        a { color: #1a73e8; text-decoration: none; }
+        a:hover { text-decoration: underline; }
+    </style>
+</head>
+<body>
+    <h1>Saved Photos from Merged Contacts (${savedPhotos.length})</h1>
+    <table>
+        <tr><th>Photos</th><th>Name</th></tr>
+${savedPhotos.map(entry => {
+    const id = entry.contactId.replace('people/', '');
+    const contactUrl = `https://contacts.google.com/person/${id}`;
+    const photoImgs = entry.photos.map(url => `<img src="${url}" alt="${entry.name}" loading="lazy">`).join('');
+    return `        <tr>
+            <td>${photoImgs || '(no photo)'}</td>
+            <td><a href="${contactUrl}" target="_blank">${entry.name}</a></td>
+        </tr>`;
+}).join('\n')}
+    </table>
+</body>
+</html>`;
+        fs.writeFileSync(htmlPath, html);
+        console.log(`\nSaved ${savedPhotos.length} photo entries to ${htmlPath}`);
     }
 
     // Save merged.json (history of processed entries)
@@ -1620,7 +1669,7 @@ async function runMerge(user: string, limit: number): Promise<void> {
     fs.writeFileSync(paths.indexFile, JSON.stringify(index, null, 2));
 
     // Remove processed entries from merger.json
-    const remainingEntries = JSON.parse(fs.readFileSync(mergerPath, 'utf-8')) as MergeEntry[];
+    const remainingEntries = parseJsonc(fs.readFileSync(mergerPath, 'utf-8')) as MergeEntry[];
     const processedNames = new Set(entries.map(e => e.name));
     const newMerger = remainingEntries.filter(e => !processedNames.has(e.name));
     fs.writeFileSync(mergerPath, JSON.stringify(newMerger, null, 2));
@@ -1679,7 +1728,7 @@ async function runPhotos(user: string): Promise<void> {
 
     for (const file of files) {
         const filePath = path.join(paths.contactsDir, file);
-        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
 
         const photoUrl = getPhotoUrl(contact);
         if (!photoUrl) continue;
@@ -1766,7 +1815,7 @@ async function runPhotoCompare(user: string): Promise<void> {
     // First collect all contacts with photos
     for (const file of files) {
         const filePath = path.join(paths.contactsDir, file);
-        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
 
         const photoUrl = getPhotoUrl(contact);
         if (!photoUrl) continue;
@@ -1867,7 +1916,7 @@ function findContactById(paths: UserPaths, id: string): { contact: GooglePerson;
     const contactPath = path.join(paths.contactsDir, `${cleanId}.json`);
     if (fs.existsSync(contactPath)) {
         return {
-            contact: JSON.parse(fs.readFileSync(contactPath, 'utf-8')),
+            contact: parseJsonc(fs.readFileSync(contactPath, 'utf-8')),
             filePath: contactPath,
             source: 'contacts'
         };
@@ -1877,7 +1926,7 @@ function findContactById(paths: UserPaths, id: string): { contact: GooglePerson;
     const deletedPath = path.join(paths.deletedDir, `${cleanId}.json`);
     if (fs.existsSync(deletedPath)) {
         return {
-            contact: JSON.parse(fs.readFileSync(deletedPath, 'utf-8')),
+            contact: parseJsonc(fs.readFileSync(deletedPath, 'utf-8')),
             filePath: deletedPath,
             source: 'deleted'
         };
@@ -1906,7 +1955,7 @@ function searchContacts(paths: UserPaths, pattern: string): ContactMatch[] {
     if (fs.existsSync(paths.contactsDir)) {
         for (const file of fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'))) {
             const filePath = path.join(paths.contactsDir, file);
-            const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+            const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
             if (matchesContact(contact, regex)) {
                 matches.push({
                     id: file.replace(/\.json$/, ''),
@@ -1923,7 +1972,7 @@ function searchContacts(paths: UserPaths, pattern: string): ContactMatch[] {
     if (fs.existsSync(paths.deletedDir)) {
         for (const file of fs.readdirSync(paths.deletedDir).filter(f => f.endsWith('.json'))) {
             const filePath = path.join(paths.deletedDir, file);
-            const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+            const contact = parseJsonc(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
             if (matchesContact(contact, regex)) {
                 matches.push({
                     id: file.replace(/\.json$/, ''),
@@ -2167,7 +2216,7 @@ async function runReset(user: string): Promise<void> {
 
     // Clear from index.json
     if (fs.existsSync(paths.indexFile)) {
-        const index = JSON.parse(fs.readFileSync(paths.indexFile, 'utf-8'));
+        const index = parseJsonc(fs.readFileSync(paths.indexFile, 'utf-8'));
         for (const entry of Object.values(index.contacts) as any[]) {
             if (entry._delete) {
                 delete entry._delete;
@@ -2183,7 +2232,7 @@ async function runReset(user: string): Promise<void> {
         for (const file of files) {
             const filePath = path.join(paths.contactsDir, file);
             const stat = fs.statSync(filePath);
-            const content = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            const content = parseJsonc(fs.readFileSync(filePath, 'utf-8'));
             if (content._delete || content._deleted) {
                 delete content._delete;
                 delete content._deleted;
@@ -2197,7 +2246,7 @@ async function runReset(user: string): Promise<void> {
 
     // Clear _delete.json queue
     if (fs.existsSync(paths.deleteQueueFile)) {
-        const queue = JSON.parse(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
+        const queue = parseJsonc(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
         queueCleared = queue.entries?.length || 0;
         fs.unlinkSync(paths.deleteQueueFile);
     }

package/glib/gctypes.ts

@@ -93,13 +93,15 @@ export interface UserPaths {
     userDir: string;
     contactsDir: string;       /** Active contacts synced from Google */
     deletedDir: string;        /** Backup of deleted contact files */
+    orphansDir: string;        /** Dead files not in index (moved during sync --full) */
     toDeleteDir: string;       /** User requests to delete (move files here) */
     toAddDir: string;          /** User requests to add new contacts */
     fixLogDir: string;         /** Logs from gfix operations */
     indexFile: string;
     deletedFile: string;       /** Deleted contacts index (deleted.json) */
     deleteQueueFile: string;   /** Pending deletions (_delete.json) */
-    photosFile: string;        /** Photos from deleted contacts (photos.json) */
+    photosFile: string;        /** Photos data store (_photos.json) */
+    photosHtmlFile: string;    /** Photos HTML view (photos.html) */
     statusFile: string;
     syncTokenFile: string;
     tokenFile: string;

package/glib/gmerge.ts

@@ -261,8 +261,8 @@ export function collectSourcePhotos(sources: GooglePerson[]): string[] {
     const urls: string[] = [];
     for (const source of sources) {
         for (const photo of source.photos || []) {
-            // Only collect custom photos (default: false means custom)
-            if (photo.url && photo.default === false) {
+            // Only collect custom photos (!default means custom - undefined or false)
+            if (photo.url && !photo.default) {
                 urls.push(photo.url);
             }
         }

package/glib/gutils.ts

@@ -58,13 +58,15 @@ export function getUserPaths(user: string): UserPaths {
         userDir,
         contactsDir: path.join(userDir, 'contacts'),
         deletedDir: path.join(userDir, 'deleted'),
+        orphansDir: path.join(userDir, 'orphans'),
         toDeleteDir: path.join(userDir, '_delete'),
         toAddDir: path.join(userDir, '_add'),
         fixLogDir: path.join(userDir, 'fix-logs'),
         indexFile: path.join(userDir, 'index.json'),
         deletedFile: path.join(userDir, 'deleted.json'),
         deleteQueueFile: path.join(userDir, '_delete.json'),
-        photosFile: path.join(userDir, 'photos.json'),
+        photosFile: path.join(userDir, '_photos.json'),
+        photosHtmlFile: path.join(userDir, 'photos.html'),
         statusFile: path.join(userDir, 'status.json'),
         syncTokenFile: path.join(userDir, 'sync-token.json'),
         tokenFile: path.join(userDir, 'token.json'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/gcards",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Google Contacts cleanup and management tool",
   "type": "module",
   "main": "gcards.ts",