@bobfrankston/gcards 0.1.4 → 0.1.5

package/.claude/settings.local.json

@@ -19,7 +19,9 @@
       "Bash(node gfix.ts:*)",
       "Bash(node --import tsx gcards.ts:*)",
       "Bash(npm install:*)",
-      "Bash(npx tsx:*)"
+      "Bash(npx tsx:*)",
+      "WebFetch(domain:lh3.googleusercontent.com)",
+      "Bash(curl:*)"
     ],
     "deny": [],
     "ask": []

package/README.md

@@ -119,18 +119,19 @@ gcards/                   # App directory (%APPDATA%\gcards or ~/.config/gcards)
   data/                   # User data directory
     <username>/
       contacts/           # Active contacts (*.json)
+      deleted/            # Backup of deleted contact files
       _delete/            # User requests to delete (move files here)
       _add/               # User requests to add new contacts
       fix-logs/           # Logs from gfix operations
-      index.json          # Active contact index
-      deleted.json        # Deleted contacts index (tombstones)
+      index.json          # Active contact index (hasPhoto, starred flags)
+      deleted.json        # Deleted contacts index
+      notdeleted.json     # Contacts skipped due to photo/starred
       token.json          # OAuth token (read-only)
       token-write.json    # OAuth token (read-write)
       changes.log         # Log from gfix names
       birthdays.csv       # Extracted birthdays
       merger.json         # Duplicates to merge (from gfix undup)
       merged.json         # Processed merges (history)
-      photos.json         # Photos from deleted contacts
 ```
 
 ## Fixes Applied by `gfix inspect/apply`
@@ -158,13 +159,26 @@ When a contact has a full name in `givenName` but no `familyName`:
 
 ## Deleting Contacts
 
-Three ways to delete contacts:
+Three ways to mark contacts for deletion:
 
 1. **In index.json**: Add `"_delete": true` to an entry
 2. **In contact JSON**: Add `"_delete": true` to the contact file
 3. **Move to _delete/**: Move the contact file to the `_delete/` folder
 
-Then run `gcards push` to apply deletions. Deleted contacts are moved to `deleted.json`.
+Then run `gcards push` to apply deletions.
+
+### Photo/Starred Protection
+
+Contacts with photos or starred status are **not deleted** from Google to prevent data loss:
+- Contacts with non-default photos: `_delete` set to `"photo"`
+- Starred/favorite contacts: `_delete` set to `"starred"`
+
+These remain in Google and `index.json` with the skip reason. Review `notdeleted.json` after push.
+
+### Backup
+
+All deleted contact files are moved to `deleted/` folder as backup (not permanently deleted).
+Index entries move to `deleted.json`.
 
 ## Duplicate Contact Merging
 

package/gcards.ts

@@ -12,7 +12,7 @@ import { parseArgs, showUsage, showHelp } from './glib/parsecli.ts';
 import { authenticateOAuth } from '../../../projects/oauth/oauthsupport/index.ts';
 import type { GooglePerson, GoogleConnectionsResponse } from './glib/types.ts';
 import { GCARDS_GUID_KEY, extractGuids } from './glib/gctypes.ts';
-import type { ContactIndex, IndexEntry, PushStatus, PendingChange, UserPaths } from './glib/gctypes.ts';
+import type { ContactIndex, IndexEntry, DeletedEntry, DeleteQueue, DeleteQueueEntry, PushStatus, PendingChange, UserPaths } from './glib/gctypes.ts';
 import { DATA_DIR, CREDENTIALS_FILE, loadConfig, saveConfig, getUserPaths, ensureUserDir, loadIndex, normalizeUser, getAllUsers, resolveUser, FileLogger } from './glib/gutils.ts';
 
 const PEOPLE_API_BASE = 'https://people.googleapis.com/v1';
@@ -112,7 +112,7 @@ function saveIndex(paths: UserPaths, index: ContactIndex): void {
 
 /** Deleted contacts index (separate from active index) */
 interface DeletedIndex {
-    deleted: Record<string, IndexEntry>;
+    deleted: Record<string, DeletedEntry>;
 }
 
 function loadDeleted(paths: UserPaths): DeletedIndex {
@@ -124,7 +124,7 @@ function loadDeleted(paths: UserPaths): DeletedIndex {
 
 function saveDeleted(paths: UserPaths, deletedIndex: DeletedIndex): void {
     // Sort by displayName
-    const sorted: Record<string, IndexEntry> = {};
+    const sorted: Record<string, DeletedEntry> = {};
     const entries = Object.entries(deletedIndex.deleted);
     entries.sort((a, b) => a[1].displayName.localeCompare(b[1].displayName));
     for (const [key, value] of entries) {
@@ -134,6 +134,72 @@ function saveDeleted(paths: UserPaths, deletedIndex: DeletedIndex): void {
     fs.writeFileSync(paths.deletedFile, JSON.stringify(deletedIndex, null, 2));
 }
 
+interface SavedPhoto {
+    url: string;
+    sourceType: 'CONTACT' | 'PROFILE';
+}
+
+interface PhotoEntry {
+    displayName: string;
+    photos: SavedPhoto[];
+    deletedAt: string;
+}
+
+interface PhotosIndex {
+    photos: Record<string, PhotoEntry>;  // resourceName -> PhotoEntry
+}
+
+function loadPhotos(paths: UserPaths): PhotosIndex {
+    if (fs.existsSync(paths.photosFile)) {
+        return JSON.parse(fs.readFileSync(paths.photosFile, 'utf-8'));
+    }
+    return { photos: {} };
+}
+
+function savePhotos(paths: UserPaths, photosIndex: PhotosIndex): void {
+    // Sort by displayName
+    const sorted: Record<string, PhotoEntry> = {};
+    const entries = Object.entries(photosIndex.photos);
+    entries.sort((a, b) => a[1].displayName.localeCompare(b[1].displayName));
+    for (const [key, value] of entries) {
+        sorted[key] = value;
+    }
+    photosIndex.photos = sorted;
+    fs.writeFileSync(paths.photosFile, JSON.stringify(photosIndex, null, 2));
+}
+
+function loadDeleteQueue(paths: UserPaths): DeleteQueue {
+    if (fs.existsSync(paths.deleteQueueFile)) {
+        return JSON.parse(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));
+}
+
+function extractNonDefaultPhotos(contact: GooglePerson): SavedPhoto[] {
+    if (!contact.photos) return [];
+    return contact.photos
+        .filter(p => !p.default)
+        .map(p => ({
+            url: p.url,
+            sourceType: (p.metadata?.source?.type || 'CONTACT') as 'CONTACT' | 'PROFILE'
+        }));
+}
+
+function hasNonDefaultPhoto(contact: GooglePerson): boolean {
+    return contact.photos?.some(p => !p.default) || false;
+}
+
+function isStarred(contact: GooglePerson): boolean {
+    return contact.memberships?.some(m =>
+        m.contactGroupMembership?.contactGroupId === 'starred'
+    ) || false;
+}
+
 function generateGuid(): string {
     return crypto.randomUUID();
 }
@@ -232,20 +298,37 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
 
     const index = loadIndex(paths);
     const deletedIndex = loadDeleted(paths);
+    const photosIndex = loadPhotos(paths);
     let syncToken = options.full ? null : loadSyncToken(paths);
 
-    // Migrate any deleted entries from index.json to deleted.json
+    // Migrate any old deleted entries from index.json to deleted.json
+    // Also clean up old fields (deleted: false, etag)
     let migrated = 0;
+    let cleaned = 0;
     for (const [rn, entry] of Object.entries(index.contacts)) {
-        if (entry.deleted) {
-            deletedIndex.deleted[rn] = entry;
+        const oldEntry = entry as any;
+        if (oldEntry.deleted === true) {
+            deletedIndex.deleted[rn] = { ...entry, deletedAt: oldEntry.deletedAt || new Date().toISOString() };
             delete index.contacts[rn];
             migrated++;
+        } else {
+            // Clean up old fields
+            if ('deleted' in oldEntry) {
+                delete oldEntry.deleted;
+                cleaned++;
+            }
+            if ('etag' in oldEntry) {
+                delete oldEntry.etag;
+                cleaned++;
+            }
         }
     }
     if (migrated > 0) {
         console.log(`Migrated ${migrated} deleted entries to deleted.json`);
     }
+    if (cleaned > 0) {
+        console.log(`Cleaned ${cleaned} old fields from index entries`);
+    }
 
     if (syncToken) {
         console.log('Performing incremental sync...');
@@ -275,12 +358,42 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
                 if (isDeleted) {
                     const entry = index.contacts[person.resourceName];
                     if (entry) {
+                        const id = person.resourceName.replace('people/', '');
+                        const contactFile = path.join(paths.contactsDir, `${id}.json`);
+
+                        // Save photos before deleting
+                        if (fs.existsSync(contactFile)) {
+                            try {
+                                const contact = JSON.parse(fs.readFileSync(contactFile, 'utf-8')) as GooglePerson;
+                                const photos = extractNonDefaultPhotos(contact);
+                                if (photos.length > 0) {
+                                    photosIndex.photos[person.resourceName] = {
+                                        displayName: entry.displayName,
+                                        photos,
+                                        deletedAt: new Date().toISOString()
+                                    };
+                                }
+                            } catch { /* ignore read errors */ }
+                        }
+
                         // Move to deleted.json
-                        entry.deleted = true;
-                        entry.deletedAt = new Date().toISOString();
-                        deletedIndex.deleted[person.resourceName] = entry;
+                        const deletedEntry = { ...entry, deletedAt: new Date().toISOString(), _delete: 'server' };
+                        deletedIndex.deleted[person.resourceName] = deletedEntry;
                         delete index.contacts[person.resourceName];
-                        deleteContactFile(paths, person.resourceName);
+
+                        // Backup contact file to deleted/ folder
+                        if (fs.existsSync(contactFile)) {
+                            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);
+                        }
+
                         deleted++;
                         if (options.verbose) console.log(`\n  Deleted: ${displayName}`);
                     }
@@ -307,14 +420,20 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
 
                     // Extract GUIDs from userDefined fields
                     const guids = extractGuids(person);
+                    const hasPhoto = hasNonDefaultPhoto(person);
+                    const starred = isStarred(person);
+
+                    // Preserve _delete flag from existing entry
+                    const existingDelete = index.contacts[person.resourceName]?._delete;
 
                     index.contacts[person.resourceName] = {
                         resourceName: person.resourceName,
                         displayName,
-                        etag: person.etag,
-                        deleted: false,
                         updatedAt: new Date().toISOString(),
-                        guids: guids.length > 0 ? guids : undefined
+                        ...(hasPhoto && { hasPhoto }),
+                        ...(starred && { starred }),
+                        ...(guids.length > 0 && { guids }),
+                        ...(existingDelete && { _delete: existingDelete })
                     };
 
                     if (existed) {
@@ -340,6 +459,7 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
         index.lastSync = new Date().toISOString();
         saveIndex(paths, index);
         saveDeleted(paths, deletedIndex);
+        savePhotos(paths, photosIndex);
 
         // Small delay between pages to be nice to the API
         if (pageToken) {
@@ -383,23 +503,27 @@ interface PendingChangesResult {
     parseErrors: string[];
 }
 
-async function findPendingChanges(paths: UserPaths, logger: FileLogger): Promise<PendingChangesResult> {
+async function findPendingChanges(paths: UserPaths, logger: FileLogger, since?: string): Promise<PendingChangesResult> {
     const changes: PendingChange[] = [];
     const parseErrors: string[] = [];
     const index = loadIndex(paths);
-    const lastSync = index.lastSync ? new Date(index.lastSync).getTime() : 0;
+    // Use -since override if provided, otherwise use lastSync
+    const sinceTime = since ? new Date(since).getTime() : (index.lastSync ? new Date(index.lastSync).getTime() : 0);
+    if (since) {
+        console.log(`Using -since override: ${since}`);
+    }
 
-    // Check index.json for _delete requests
-    for (const [resourceName, entry] of Object.entries(index.contacts)) {
-        if (entry._delete && !entry.deleted) {
-            const filePath = path.join(paths.contactsDir, `${resourceName.replace(/\//g, '_')}.json`);
-            changes.push({
-                type: 'delete',
-                resourceName,
-                displayName: entry.displayName,
-                filePath
-            });
-        }
+    // Check _delete.json for deletion requests
+    const deleteQueue = loadDeleteQueue(paths);
+    for (const entry of deleteQueue.entries) {
+        const filePath = path.join(paths.contactsDir, `${entry.resourceName.replace('people/', '')}.json`);
+        changes.push({
+            type: 'delete',
+            resourceName: entry.resourceName,
+            displayName: entry.displayName,
+            filePath,
+            _delete: entry._delete || 'queued'
+        });
     }
 
     // Check contacts/ for modified files and _delete markers
@@ -413,8 +537,8 @@ async function findPendingChanges(paths: UserPaths, logger: FileLogger): Promise
             const stat = await fp.stat(filePath);
             const modTime = stat.mtimeMs;
 
-            // Skip files not modified since last sync
-            if (modTime <= lastSync + 1000) continue;
+            // Skip files not modified since last sync (or -since override)
+            if (modTime <= sinceTime + 1000) continue;
 
             checked++;
             let content: GooglePerson & { _delete?: boolean };
@@ -645,7 +769,7 @@ async function createContactOnGoogle(person: GooglePerson, retryCount = 0, token
     return await response.json();
 }
 
-async function pushContacts(user: string, options: { yes: boolean; verbose: boolean; limit: number }): Promise<void> {
+async function pushContacts(user: string, options: { yes: boolean; verbose: boolean; limit: number; since: string }): Promise<void> {
     const paths = getUserPaths(user);
     ensureUserDir(user);
 
@@ -654,7 +778,7 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
     const logger = new FileLogger(problemsFile, true);
 
     console.log(`Pushing contacts for user: ${user}`);
-    let { changes, parseErrors } = await findPendingChanges(paths, logger);
+    let { changes, parseErrors } = await findPendingChanges(paths, logger, options.since || undefined);
 
     if (parseErrors.length > 0) {
         console.log(`\n${parseErrors.length} files had parse errors (see pushproblems.txt)`);
@@ -665,9 +789,28 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
         return;
     }
 
-    const adds = changes.filter(c => c.type === 'add');
-    const updates = changes.filter(c => c.type === 'update');
-    const deletes = changes.filter(c => c.type === 'delete');
+    const adds = changes.filter(c => c.type === 'add').sort((a, b) => a.displayName.localeCompare(b.displayName));
+    const updates = changes.filter(c => c.type === 'update').sort((a, b) => a.displayName.localeCompare(b.displayName));
+    const deletes = changes.filter(c => c.type === 'delete').sort((a, b) => a.displayName.localeCompare(b.displayName));
+
+    // Write to toPush.txt for debugging
+    const toPushLines: string[] = [];
+    if (adds.length > 0) {
+        toPushLines.push(`New contacts (${adds.length}):`);
+        for (const c of adds) toPushLines.push(`  ${c.displayName}`);
+        toPushLines.push('');
+    }
+    if (updates.length > 0) {
+        toPushLines.push(`Updates (${updates.length}):`);
+        for (const c of updates) toPushLines.push(`  ${c.displayName} (${c.resourceName})`);
+        toPushLines.push('');
+    }
+    if (deletes.length > 0) {
+        toPushLines.push(`Deletions (${deletes.length}):`);
+        for (const c of deletes) toPushLines.push(`  ${c.displayName} (${c.resourceName})`);
+    }
+    const toPushFile = path.join(paths.userDir, 'toPush.txt');
+    fs.writeFileSync(toPushFile, toPushLines.join('\n'));
 
     console.log('\nPending changes:');
     if (adds.length > 0) {
@@ -688,6 +831,10 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
             console.log(`    - ${c.displayName} (${c.resourceName})`);
         }
     }
+    console.log(`\n(List written to ${toPushFile})`);
+
+    // Reorder changes to process in sorted order
+    changes = [...adds, ...updates, ...deletes];
 
     if (!options.yes) {
         const confirmed = await confirm(`\nPush ${changes.length} change(s) to Google?`);
@@ -703,6 +850,8 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
 
     const index = loadIndex(paths);
     const deletedIndex = loadDeleted(paths);
+    const deleteQueue = loadDeleteQueue(paths);
+    const completedDeletions = new Set<string>();  // Track successful deletions
     // Apply limit if specified
     if (options.limit > 0 && changes.length > options.limit) {
         console.log(`[DEBUG] Limiting to first ${options.limit} of ${changes.length} changes\n`);
@@ -711,9 +860,12 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
 
     let successCount = 0;
     let errorCount = 0;
+    let skippedPhoto = 0;
+    let skippedStarred = 0;
     let processed = 0;
     const total = changes.length;
     const problems: string[] = [];
+    const notDeleted: { resourceName: string; displayName: string; filePath: string; reason: string }[] = [];
 
     for (const change of changes) {
         if (escapePressed) {
@@ -728,17 +880,19 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 process.stdout.write(`${ts()} [${String(processed).padStart(5)}/${total}] Creating ${change.displayName}...`);
                 const created = await createContactOnGoogle(content);
 
-                // Extract GUIDs from userDefined
+                // Extract GUIDs and flags from created contact
                 const guids = extractGuids(created);
+                const hasPhoto = hasNonDefaultPhoto(created);
+                const starred = isStarred(created);
 
                 // Add to index
                 index.contacts[created.resourceName] = {
                     resourceName: created.resourceName,
                     displayName: change.displayName,
-                    etag: created.etag,
-                    deleted: false,
                     updatedAt: new Date().toISOString(),
-                    guids: guids.length > 0 ? guids : undefined
+                    ...(hasPhoto && { hasPhoto }),
+                    ...(starred && { starred }),
+                    ...(guids.length > 0 && { guids })
                 };
 
                 // Save new contact to contacts/ folder
@@ -766,32 +920,85 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 console.log(' done');
                 successCount++;
             } else if (change.type === 'delete') {
-                process.stdout.write(`${ts()} [${String(processed).padStart(5)}/${total}] Deleting ${change.displayName}...`);
-                await deleteContactOnGoogle(change.resourceName);
-
-                // Move to deleted.json
-                const entry = index.contacts[change.resourceName];
-                if (entry) {
-                    entry.deleted = true;
-                    entry.deletedAt = new Date().toISOString();
-                    delete entry._delete;  // Clear the delete request
-                    deletedIndex.deleted[change.resourceName] = entry;
-                    delete index.contacts[change.resourceName];
-                }
-
-                // Remove contact file from contacts/
                 const contactFile = path.join(paths.contactsDir, `${change.resourceName.replace('people/', '')}.json`);
-                if (fs.existsSync(contactFile)) {
-                    fs.unlinkSync(contactFile);
+                const fileToRead = fs.existsSync(contactFile) ? contactFile : change.filePath;
+
+                // Check if contact has a real photo or is starred - skip deletion if so
+                let contactHasPhoto = false;
+                let contactIsStarred = false;
+                if (fs.existsSync(fileToRead)) {
+                    try {
+                        const contact = JSON.parse(fs.readFileSync(fileToRead, 'utf-8')) as GooglePerson;
+                        contactHasPhoto = hasNonDefaultPhoto(contact);
+                        contactIsStarred = isStarred(contact);
+                    } catch { /* ignore read errors */ }
                 }
 
-                // Remove from _delete/ folder if it was there
-                if (change.filePath.startsWith(paths.toDeleteDir) && fs.existsSync(change.filePath)) {
-                    fs.unlinkSync(change.filePath);
-                }
+                // Determine skip reason (photo takes precedence over starred)
+                // Use * prefix to indicate "skipped, not deleted"
+                // 'force' overrides photo/starred protection
+                const isForced = change._delete === 'force' || index.contacts[change.resourceName]?._delete === 'force';
+                const skipReason = isForced ? null : (contactHasPhoto ? '*photo' : (contactIsStarred ? '*starred' : null));
+
+                if (skipReason) {
+                    // Skip Google deletion - mark why in index.json
+                    notDeleted.push({
+                        resourceName: change.resourceName,
+                        displayName: change.displayName,
+                        filePath: fileToRead,
+                        reason: skipReason
+                    });
+                    if (skipReason === '*photo') skippedPhoto++;
+                    else if (skipReason === '*starred') skippedStarred++;
+                    console.log(`${ts()} [${String(processed).padStart(5)}/${total}] SKIPPED ${change.displayName} (${skipReason})`);
+
+                    // Update _delete to show skip reason
+                    if (index.contacts[change.resourceName]) {
+                        index.contacts[change.resourceName]._delete = skipReason;
+                    }
 
-                console.log(' done');
-                successCount++;
+                    // Remove from _delete/ folder if it was there (keep in contacts/)
+                    if (change.filePath !== fileToRead && change.filePath.startsWith(paths.toDeleteDir) && fs.existsSync(change.filePath)) {
+                        fs.unlinkSync(change.filePath);
+                    }
+
+                    completedDeletions.add(change.resourceName);  // Remove from queue even if skipped
+                } else {
+                    process.stdout.write(`${ts()} [${String(processed).padStart(5)}/${total}] Deleting ${change.displayName}...`);
+                    await deleteContactOnGoogle(change.resourceName);
+
+                    // Move to deleted.json (preserve _delete reason)
+                    const entry = index.contacts[change.resourceName];
+                    if (entry) {
+                        const deletedEntry = { ...entry, deletedAt: new Date().toISOString() };
+                        // Keep _delete reason in deleted entry (it's the reason for deletion)
+                        deletedIndex.deleted[change.resourceName] = deletedEntry;
+                        delete index.contacts[change.resourceName];
+                    }
+
+                    // Move contact file to deleted/ folder (backup with timestamp)
+                    if (!fs.existsSync(paths.deletedDir)) {
+                        fs.mkdirSync(paths.deletedDir, { recursive: true });
+                    }
+                    if (fs.existsSync(contactFile)) {
+                        // Add deletion metadata to the JSON file
+                        const contactData = JSON.parse(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));
+                        fs.writeFileSync(destPath, JSON.stringify(contactData, null, 2));
+                        fs.unlinkSync(contactFile);
+                    }
+
+                    // Remove from _delete/ folder if it was there
+                    if (change.filePath.startsWith(paths.toDeleteDir) && fs.existsSync(change.filePath)) {
+                        fs.unlinkSync(change.filePath);
+                    }
+
+                    completedDeletions.add(change.resourceName);
+                    console.log(' done');
+                    successCount++;
+                }
             }
 
             await sleep(700);  // 90 writes/min limit = ~700ms between ops
@@ -811,12 +1018,27 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
         console.log(`\nErrors written to: ${problemsFile}`);
     }
 
+    // Write notdeleted file if any contacts were skipped due to photos
+    if (notDeleted.length > 0) {
+        const notDeletedFile = path.join(paths.userDir, 'notdeleted.json');
+        fs.writeFileSync(notDeletedFile, JSON.stringify(notDeleted, null, 2));
+        console.log(`\n${notDeleted.length} contacts with photos not deleted from Google (see notdeleted.json)`);
+    }
+
+    // Remove completed deletions from queue
+    if (completedDeletions.size > 0) {
+        deleteQueue.entries = deleteQueue.entries.filter(e => !completedDeletions.has(e.resourceName));
+        saveDeleteQueue(paths, deleteQueue);
+    }
+
     // Save status with new timestamp
     saveStatus(paths, { lastPush: new Date().toISOString() });
     saveIndex(paths, index);
     saveDeleted(paths, deletedIndex);
 
-    console.log(`\nPush complete: ${successCount} succeeded, ${errorCount} failed`);
+    const skipped = skippedPhoto + skippedStarred;
+    const skippedDetails = skipped > 0 ? ` (${skippedPhoto} photo, ${skippedStarred} starred)` : '';
+    console.log(`\nPush complete: ${successCount} succeeded, ${errorCount} failed, ${skipped} skipped${skippedDetails}`);
 }
 
 async function main(): Promise<void> {
@@ -861,7 +1083,7 @@ async function main(): Promise<void> {
                     await syncContacts(user, { full: options.full, verbose: options.verbose });
                     break;
                 case 'push':
-                    await pushContacts(user, { yes: options.yes, verbose: options.verbose, limit: options.limit });
+                    await pushContacts(user, { yes: options.yes, verbose: options.verbose, limit: options.limit, since: options.since });
                     break;
                 default:
                     console.error(`Unknown command: ${options.command}`);

package/gfix.ts

@@ -11,9 +11,22 @@
 import fs from 'fs';
 import path from 'path';
 import type { GooglePerson, GoogleName, GooglePhoneNumber, GoogleEmailAddress, GoogleBirthday } from './glib/types.ts';
-import { DATA_DIR, resolveUser, getUserPaths } from './glib/gutils.ts';
+import type { DeleteQueue, DeleteQueueEntry, UserPaths } from './glib/gctypes.ts';
+import { DATA_DIR, resolveUser, getUserPaths, loadIndex } from './glib/gutils.ts';
 import { mergeContacts as mergeContactData, collectSourcePhotos, type MergeEntry, type PhotoEntry } from './glib/gmerge.ts';
 
+function loadDeleteQueue(paths: UserPaths): DeleteQueue {
+    if (fs.existsSync(paths.deleteQueueFile)) {
+        return JSON.parse(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));
+}
+
 interface BirthdayEntry {
     name: string;
     date: string;
@@ -1243,15 +1256,23 @@ async function runMerge(user: string, limit: number): Promise<void> {
         }
     }
 
-    // Load existing photos.json and merged.json
+    // Load existing files
     let savedPhotos: PhotoEntry[] = [];
     if (fs.existsSync(photosPath)) {
         savedPhotos = JSON.parse(fs.readFileSync(photosPath, 'utf-8'));
     }
 
+    const deleteQueue = loadDeleteQueue(paths);
+    const index = loadIndex(paths);
+
     let mergedEntries: MergeEntry[] = [];
     if (fs.existsSync(mergedPath)) {
-        mergedEntries = JSON.parse(fs.readFileSync(mergedPath, 'utf-8'));
+        const content = fs.readFileSync(mergedPath, 'utf-8').trim();
+        if (content) {
+            try {
+                mergedEntries = JSON.parse(content);
+            } catch { /* ignore parse errors, start fresh */ }
+        }
     }
 
     let mergeSuccess = 0;
@@ -1304,12 +1325,20 @@ async function runMerge(user: string, limit: number): Promise<void> {
             fs.writeFileSync(targetPath, JSON.stringify(updatedTarget, null, 2));
             console.log(`  Updated ${targetPath}`);
 
-            // Mark sources for deletion
+            // Add sources to delete queue and set _delete reason in index
             for (const source of sources) {
                 const sourceId = source.resourceName.replace('people/', '');
-                const sourcePath = path.join(paths.contactsDir, `${sourceId}.json`);
-                const markedSource = { _delete: true, ...source };
-                fs.writeFileSync(sourcePath, JSON.stringify(markedSource, null, 2));
+                const displayName = source.names?.[0]?.displayName || 'Unknown';
+                deleteQueue.entries.push({
+                    resourceName: source.resourceName,
+                    displayName,
+                    addedAt: new Date().toISOString(),
+                    _delete: 'duplicate'
+                });
+                // Set _delete reason in index.json
+                if (index.contacts[source.resourceName]) {
+                    index.contacts[source.resourceName]._delete = 'duplicate';
+                }
                 console.log(`  Marked ${sourceId} for deletion`);
             }
 
@@ -1321,7 +1350,7 @@ async function runMerge(user: string, limit: number): Promise<void> {
         }
     }
 
-    // Process deletes - just mark files
+    // Process deletes - add to delete queue and set _delete reason
     for (const entry of toDelete) {
         console.log(`\nMarking for deletion: ${entry.name}...`);
 
@@ -1329,9 +1358,18 @@ 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'));
-                const markedContact = { _delete: true, ...contact };
-                fs.writeFileSync(filePath, JSON.stringify(markedContact, null, 2));
+                const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+                const displayName = contact.names?.[0]?.displayName || entry.name;
+                deleteQueue.entries.push({
+                    resourceName: rn,
+                    displayName,
+                    addedAt: new Date().toISOString(),
+                    _delete: 'duplicate'
+                });
+                // Set _delete reason in index.json
+                if (index.contacts[rn]) {
+                    index.contacts[rn]._delete = 'duplicate';
+                }
                 console.log(`  Marked ${id} for deletion`);
                 deleteSuccess++;
             }
@@ -1347,6 +1385,12 @@ async function runMerge(user: string, limit: number): Promise<void> {
     // Save merged.json (history of processed entries)
     fs.writeFileSync(mergedPath, JSON.stringify(mergedEntries, null, 2));
 
+    // Save delete queue
+    saveDeleteQueue(paths, deleteQueue);
+
+    // Save index.json with _delete reasons
+    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 processedNames = new Set(entries.map(e => e.name));
@@ -1361,6 +1405,72 @@ async function runMerge(user: string, limit: number): Promise<void> {
     console.log(`\nRun 'gcards push -u ${user}' to apply changes to Google.`);
 }
 
+/** Reset ALL delete markers: index.json, contact files, _delete.json, _delete/ folder */
+async function runReset(user: string): Promise<void> {
+    const paths = getUserPaths(user);
+
+    let indexCleared = 0;
+    let filesCleared = 0;
+    let queueCleared = 0;
+    let folderMoved = 0;
+
+    // Clear from index.json
+    if (fs.existsSync(paths.indexFile)) {
+        const index = JSON.parse(fs.readFileSync(paths.indexFile, 'utf-8'));
+        for (const entry of Object.values(index.contacts) as any[]) {
+            if (entry._delete) {
+                delete entry._delete;
+                indexCleared++;
+            }
+        }
+        fs.writeFileSync(paths.indexFile, JSON.stringify(index, null, 2));
+    }
+
+    // Clear from contact JSON files (preserve mtime to avoid false "modified" detection)
+    if (fs.existsSync(paths.contactsDir)) {
+        const files = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+        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'));
+            if (content._delete || content._deleted) {
+                delete content._delete;
+                delete content._deleted;
+                fs.writeFileSync(filePath, JSON.stringify(content, null, 2));
+                // Restore original mtime so file doesn't appear modified
+                fs.utimesSync(filePath, stat.atime, stat.mtime);
+                filesCleared++;
+            }
+        }
+    }
+
+    // Clear _delete.json queue
+    if (fs.existsSync(paths.deleteQueueFile)) {
+        const queue = JSON.parse(fs.readFileSync(paths.deleteQueueFile, 'utf-8'));
+        queueCleared = queue.entries?.length || 0;
+        fs.unlinkSync(paths.deleteQueueFile);
+    }
+
+    // Move files from _delete/ folder back to contacts/
+    if (fs.existsSync(paths.toDeleteDir)) {
+        const files = fs.readdirSync(paths.toDeleteDir).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+            const src = path.join(paths.toDeleteDir, file);
+            const dest = path.join(paths.contactsDir, file);
+            fs.renameSync(src, dest);
+            folderMoved++;
+        }
+    }
+
+    console.log(`Reset complete for user: ${user}`);
+    console.log(`  Index entries: ${indexCleared}`);
+    console.log(`  Contact files: ${filesCleared}`);
+    console.log(`  Queue entries: ${queueCleared}`);
+    if (folderMoved > 0) {
+        console.log(`  Moved from _delete/: ${folderMoved}`);
+    }
+}
+
 function showUsage(): void {
     console.log(`
 gfix - One-time fix routines for gcards contacts
@@ -1375,6 +1485,7 @@ Commands:
     names       Parse givenName into first/middle/last, clean fileAs, remove dup phones/emails
     undup       Find duplicate contacts (same name + overlapping email) -> merger.json
     merge       Merge duplicates locally (then use gcards push)
+    reset       Clear all _delete flags from index.json
 
 Options:
     -u, --user <name>   User profile to process
@@ -1460,6 +1571,8 @@ async function main(): Promise<void> {
         await runUndup(resolvedUser);
     } else if (command === 'merge') {
         await runMerge(resolvedUser, processLimit);
+    } else if (command === 'reset') {
+        await runReset(resolvedUser);
     } else {
         console.error(`Unknown command: ${command}`);
         showUsage();

package/glib/gctypes.ts

@@ -28,14 +28,33 @@ export interface ContactIndex {
 export interface IndexEntry {
     resourceName: string;
     displayName: string;
-    etag?: string;
-    deleted: boolean;      /** Google deleted this contact */
-    deletedAt?: string;
     updatedAt: string;
-    _delete?: boolean;     /** Request to delete on next push */
+    hasPhoto?: boolean;    /** Has non-default photo */
+    starred?: boolean;     /** In starred/favorites group */
+    _delete?: string;      /** Deletion reason. *prefix means skipped (e.g., *photo, *starred) */
     guids?: string[];      /** User-defined GUIDs for cross-account tracking */
 }
 
+export interface DeletedEntry extends IndexEntry {
+    deletedAt: string;
+}
+
+// ============================================================
+// Delete Queue (_delete.json)
+// ============================================================
+
+export interface DeleteQueueEntry {
+    resourceName: string;
+    displayName: string;
+    addedAt: string;
+    _delete: string;  /** Reason for deletion (e.g., 'duplicate') */
+}
+
+export interface DeleteQueue {
+    updatedAt: string;
+    entries: DeleteQueueEntry[];
+}
+
 // ============================================================
 // Push Status (status.json)
 // ============================================================
@@ -62,6 +81,7 @@ export interface PendingChange {
     resourceName: string;
     displayName: string;
     filePath: string;
+    _delete?: string;  /** Deletion reason (for type='delete') */
 }
 
 // ============================================================
@@ -71,12 +91,14 @@ export interface PendingChange {
 export interface UserPaths {
     userDir: string;
     contactsDir: string;       /** Active contacts synced from Google */
-    deletedDir: string;        /** Google-deleted tombstones */
-    toDeleteDir: string;       /** User requests to delete */
+    deletedDir: string;        /** Backup of deleted contact files */
+    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) */
     statusFile: string;
     syncTokenFile: string;
     tokenFile: string;

package/glib/gutils.ts

@@ -58,6 +58,8 @@ export function getUserPaths(user: string): UserPaths {
         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'),
         statusFile: path.join(userDir, 'status.json'),
         syncTokenFile: path.join(userDir, 'sync-token.json'),
         tokenFile: path.join(userDir, 'token.json'),

package/glib/parsecli.ts

@@ -11,6 +11,7 @@ export interface CliOptions {
     help: boolean;
     verbose: boolean;
     limit: number;  /** Process only first n entries (0 = no limit) */
+    since: string;  /** Override lastSync - check files since this datetime */
 }
 
 export function parseArgs(args: string[]): CliOptions {
@@ -22,7 +23,8 @@ export function parseArgs(args: string[]): CliOptions {
         all: false,
         help: false,
         verbose: false,
-        limit: 0
+        limit: 0,
+        since: ''
     };
 
     for (let i = 0; i < args.length; i++) {
@@ -41,6 +43,8 @@ export function parseArgs(args: string[]): CliOptions {
             options.user = args[++i];
         } else if ((arg === '--limit' || arg === '-limit') && i + 1 < args.length) {
             options.limit = parseInt(args[++i], 10) || 0;
+        } else if ((arg === '--since' || arg === '-since') && i + 1 < args.length) {
+            options.since = args[++i];
         } else if (!arg.startsWith('-') && !options.command) {
             options.command = arg;
         }

package/package.json

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