npm - @bobfrankston/gcards - Versions diffs - 0.1.22 → 0.1.24 - Mend

@bobfrankston/gcards 0.1.22 → 0.1.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/gcards.ts CHANGED Viewed

@@ -129,7 +129,7 @@ async function refreshAccessToken(): Promise<string> {
     return currentAccessToken;
 }
-/** Get sort key from contact: fileAs > displayNameLastFirst > displayName */
+/** Get sort key from contact: fileAs (First Last) > displayNameLastFirst (Last, First) > displayName */
 function getSortKey(person: GooglePerson): string {
     const fileAs = person.fileAses?.[0]?.value;
     if (fileAs) return fileAs;
@@ -139,7 +139,7 @@ function getSortKey(person: GooglePerson): string {
 }
 function saveIndex(paths: UserPaths, index: ContactIndex): void {
-    // Sort contacts by sortKey (fileAs > displayNameLastFirst > displayName)
+    // Sort contacts by sortKey (fileAs='First Last' > displayNameLastFirst='Last, First' > displayName)
     const sortedContacts: Record<string, IndexEntry> = {};
     const entries = Object.entries(index.contacts);
     entries.sort((a, b) => {
@@ -151,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) */
@@ -179,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 {
@@ -218,8 +245,23 @@ function savePhotos(paths: UserPaths, photosIndex: PhotosIndex): void {
     }
     photosIndex.photos = sorted;
+    // Add helpful comments
+    const comment = `// _photos.json - Photos preserved during merge operations
+// This file saves photo URLs when duplicate contacts are merged.
+// Photos are collected from source contacts before they're marked for deletion.
+// Also captures photos from contacts deleted by Google during sync.
+//
+// Generated by: 'gfix merge' (primary), 'gcards sync' (deleted contacts)
+// View: photos.html is generated alongside this file
+//
+// 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, JSON.stringify(photosIndex, null, 2));
+    fs.writeFileSync(paths.photosFile, comment + JSON.stringify(photosIndex, null, 2));
     // Generate HTML view
     const html = `<!DOCTYPE html>
@@ -272,7 +314,24 @@ function loadDeleteQueue(paths: UserPaths): DeleteQueue {
 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[] {
@@ -312,7 +371,12 @@ function loadSyncToken(paths: UserPaths): string {
 }
 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> {
@@ -390,7 +454,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 {
@@ -614,6 +685,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}`);
@@ -622,6 +717,9 @@ 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}`);
 }

package/gfix.ts CHANGED Viewed

@@ -26,7 +26,10 @@ function loadDeleteQueue(paths: UserPaths): DeleteQueue {
 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 {
@@ -2326,8 +2329,9 @@ Duplicate detection and merge:
   Note: merge prefers contacts with photos. If all have same photo URL, safe to merge.
 Photo review and comparison:
-  - gfix photos -u bob             # Generate photos.html for visual review
+  - gfix photos -u bob             # Generate photos.html showing ALL contacts with photos
   - gfix photocompare -u bob       # Find duplicates by URL and content hash
+  - gfix merge -u bob              # Generates photos.html with saved photos from merged contacts
   Output: photos.html with 100x100 photos, names, and links to Google Contacts
 Export contacts to another user:

package/glib/gctypes.ts CHANGED Viewed

@@ -93,6 +93,7 @@ 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 */

package/glib/gutils.ts CHANGED Viewed

@@ -58,6 +58,7 @@ 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'),

package/package.json CHANGED Viewed

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