@bobfrankston/gcards 0.1.0 → 0.1.4

package/gfix.ts

@@ -0,0 +1,1472 @@
+#!/usr/bin/env node
+/**
+ * gfix - One-time fix routines for gcards contacts
+ * Inspects and cleans up name fields with placeholder characters
+ *
+ * Usage:
+ *   gfix inspect -u <user>     Show what would be changed (no modifications)
+ *   gfix apply -u <user>       Apply changes and create log file
+ */
+
+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 { mergeContacts as mergeContactData, collectSourcePhotos, type MergeEntry, type PhotoEntry } from './glib/gmerge.ts';
+
+interface BirthdayEntry {
+    name: string;
+    date: string;
+}
+
+interface FileAsEntry {
+    givenName: string;
+    familyName: string;
+    fileAs: string;
+    jsonFile: string;
+}
+
+interface NameChangeLog {
+    jsonFile: string;
+    displayName: string;
+    changes: string[];
+}
+
+interface FieldChange {
+    field: string;
+    oldValue: string;
+    newValue: string;  /** null = delete field */
+}
+
+interface PhoneRemoval {
+    field: 'phoneNumbers';
+    removed: string[];  /** Phone values that were removed as duplicates */
+}
+
+interface EmailRemoval {
+    field: 'emailAddresses';
+    removed: string[];  /** Email values that were removed as duplicates */
+}
+
+type Change = FieldChange | PhoneRemoval | EmailRemoval;
+
+interface ContactChange {
+    resourceName: string;
+    displayName: string;
+    filePath: string;
+    changes: Change[];
+}
+
+interface FixLog {
+    timestamp: string;
+    user: string;
+    mode: 'inspect' | 'apply';
+    totalContacts: number;
+    contactsChanged: number;
+    changes: ContactChange[];
+}
+
+// Characters to strip from beginning/end of name fields
+const STRIP_CHARS = /^[\s\-']+|[\s\-']+$/g;
+// Collapse multiple dashes/spaces in middle to single space
+const MIDDLE_JUNK = /[\s\-]+/g;
+// Match honorific prefix (Dr., Prof., etc.) at start - may repeat many times
+const HONORIFIC_PREFIX = /^((dr|prof)\.?\s*)+/i;
+
+// Fields in GoogleName to clean (excludes honorificPrefix - handled specially)
+const NAME_FIELDS: (keyof GoogleName)[] = [
+    'displayName',
+    'givenName',
+    'familyName',
+    'middleName',
+    'displayNameLastFirst',
+    'unstructuredName',
+    'honorificSuffix'
+];
+
+interface CleanResult {
+    value: string;
+    extractedPrefix: string;
+}
+
+function cleanNameValue(value: string, extractHonorific = false): CleanResult {
+    if (!value) return { value: null, extractedPrefix: null };
+
+    let extractedPrefix: string = null;
+    let cleaned = value;
+
+    // Extract honorific prefix if requested
+    if (extractHonorific) {
+        const match = cleaned.match(HONORIFIC_PREFIX);
+        if (match) {
+            // Find unique honorifics in the matched string (handles "dr dr dr prof dr")
+            const matchedStr = match[0].toLowerCase();
+            const hasProf = /prof/i.test(matchedStr);
+            const hasDr = /dr/i.test(matchedStr);
+            // Prof takes precedence if both present, otherwise Dr
+            if (hasProf) {
+                extractedPrefix = 'Prof.';
+            } else if (hasDr) {
+                extractedPrefix = 'Dr.';
+            }
+            cleaned = cleaned.replace(HONORIFIC_PREFIX, '');
+        }
+    }
+
+    // Strip leading/trailing junk, collapse middle dashes/spaces to single space
+    cleaned = cleaned.replace(STRIP_CHARS, '').replace(MIDDLE_JUNK, ' ').trim();
+    // If only whitespace/dashes/quotes remain, delete the field
+    if (!cleaned || cleaned === '-' || cleaned === "'" || cleaned === '- -') {
+        return { value: null, extractedPrefix };
+    }
+    return { value: cleaned, extractedPrefix };
+}
+
+/** Normalize phone number for comparison (strip non-digits) */
+function normalizePhone(phone: string): string {
+    return (phone || '').replace(/\D/g, '');
+}
+
+/** Find duplicate phone numbers and return indices to remove */
+function findDuplicatePhones(phones: GooglePhoneNumber[]): string[] {
+    if (!phones || phones.length < 2) return [];
+
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+
+    for (const phone of phones) {
+        const normalized = normalizePhone(phone.value || phone.canonicalForm);
+        if (!normalized) continue;
+
+        if (seen.has(normalized)) {
+            duplicates.push(phone.value || phone.canonicalForm);
+        } else {
+            seen.add(normalized);
+        }
+    }
+
+    return duplicates;
+}
+
+/** Normalize email for comparison (lowercase, trim) */
+function normalizeEmail(email: string): string {
+    return (email || '').toLowerCase().trim();
+}
+
+/** Find duplicate email addresses and return values to remove */
+function findDuplicateEmails(emails: GoogleEmailAddress[]): string[] {
+    if (!emails || emails.length < 2) return [];
+
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+
+    for (const email of emails) {
+        const normalized = normalizeEmail(email.value);
+        if (!normalized) continue;
+
+        if (seen.has(normalized)) {
+            duplicates.push(email.value);
+        } else {
+            seen.add(normalized);
+        }
+    }
+
+    return duplicates;
+}
+
+function processContact(contact: GooglePerson): Change[] {
+    const changes: Change[] = [];
+
+    // Process name fields if present
+    for (const name of contact.names || []) {
+        const currentHonorific = name.honorificPrefix;
+        let extractedHonorific: string = null;
+
+        // Process name fields, extracting honorific from givenName/displayName/unstructuredName
+        for (const field of NAME_FIELDS) {
+            const oldValue = name[field] as string;
+            if (oldValue) {
+                const shouldExtract = !currentHonorific &&
+                    (field === 'givenName' || field === 'displayName' || field === 'unstructuredName');
+                const result = cleanNameValue(oldValue, shouldExtract);
+
+                if (result.extractedPrefix && !extractedHonorific) {
+                    extractedHonorific = result.extractedPrefix;
+                }
+
+                if (result.value !== oldValue) {
+                    changes.push({ field, oldValue, newValue: result.value });
+                }
+            }
+        }
+
+        // Clean existing honorificPrefix
+        if (currentHonorific) {
+            const result = cleanNameValue(currentHonorific, false);
+            if (result.value !== currentHonorific) {
+                changes.push({ field: 'honorificPrefix', oldValue: currentHonorific, newValue: result.value });
+            }
+        } else if (extractedHonorific) {
+            // Set honorificPrefix from extracted value
+            changes.push({ field: 'honorificPrefix', oldValue: '', newValue: extractedHonorific });
+        }
+    }
+
+    // Check for duplicate phone numbers
+    const duplicatePhones = findDuplicatePhones(contact.phoneNumbers);
+    if (duplicatePhones.length > 0) {
+        changes.push({ field: 'phoneNumbers', removed: duplicatePhones });
+    }
+
+    // Check for duplicate email addresses
+    const duplicateEmails = findDuplicateEmails(contact.emailAddresses);
+    if (duplicateEmails.length > 0) {
+        changes.push({ field: 'emailAddresses', removed: duplicateEmails });
+    }
+
+    return changes;
+}
+
+function applyChangesToContact(contact: GooglePerson, changes: Change[]): void {
+    for (const change of changes) {
+        if (change.field === 'phoneNumbers') {
+            // Remove duplicate phones
+            if (contact.phoneNumbers) {
+                const seen = new Set<string>();
+                contact.phoneNumbers = contact.phoneNumbers.filter(phone => {
+                    const normalized = normalizePhone(phone.value || phone.canonicalForm);
+                    if (seen.has(normalized)) {
+                        return false;  // Duplicate - remove
+                    }
+                    seen.add(normalized);
+                    return true;
+                });
+            }
+        } else if (change.field === 'emailAddresses') {
+            // Remove duplicate emails
+            if (contact.emailAddresses) {
+                const seen = new Set<string>();
+                contact.emailAddresses = contact.emailAddresses.filter(email => {
+                    const normalized = normalizeEmail(email.value);
+                    if (seen.has(normalized)) {
+                        return false;  // Duplicate - remove
+                    }
+                    seen.add(normalized);
+                    return true;
+                });
+            }
+        } else {
+            // Name field change
+            const fieldChange = change as FieldChange;
+            if (!contact.names) continue;
+            for (const name of contact.names) {
+                const field = fieldChange.field as keyof GoogleName;
+                if (!fieldChange.newValue) {
+                    delete name[field];
+                } else {
+                    (name as any)[field] = fieldChange.newValue;
+                }
+            }
+        }
+    }
+}
+
+
+/** Format birthday date as string (with or without year) */
+function formatBirthdayDate(birthday: GoogleBirthday): string {
+    if (birthday.text) return birthday.text;
+    if (!birthday.date) return '';
+
+    const { year, month, day } = birthday.date;
+    if (!month || !day) return '';
+
+    const mm = String(month).padStart(2, '0');
+    const dd = String(day).padStart(2, '0');
+
+    if (year) {
+        return `${year}-${mm}-${dd}`;
+    }
+    return `${mm}-${dd}`;
+}
+
+/** Extract and remove birthdays from contacts, return sorted CSV data */
+async function runBirthdayExtract(user: string, mode: 'inspect' | 'apply'): Promise<void> {
+    const paths = getUserPaths(user);
+
+    if (!fs.existsSync(paths.contactsDir)) {
+        console.error(`No contacts directory for user: ${user}`);
+        console.error(`Expected: ${paths.contactsDir}`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+    console.log(`\n${mode === 'inspect' ? 'INSPECT' : 'APPLY'} birthday extraction for user: ${user}`);
+    console.log(`Found ${files.length} contact files\n`);
+
+    const birthdays: BirthdayEntry[] = [];
+    let contactsModified = 0;
+
+    for (const file of files) {
+        const filePath = path.join(paths.contactsDir, file);
+        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+
+        if (!contact.birthdays?.length) continue;
+
+        const displayName = contact.names?.[0]?.displayName || 'Unknown';
+
+        for (const birthday of contact.birthdays) {
+            const dateStr = formatBirthdayDate(birthday);
+            if (dateStr) {
+                birthdays.push({ name: displayName, date: dateStr });
+                console.log(`  ${displayName}: ${dateStr}`);
+            }
+        }
+
+        if (mode === 'apply') {
+            delete contact.birthdays;
+            fs.writeFileSync(filePath, JSON.stringify(contact, null, 2));
+            contactsModified++;
+        }
+    }
+
+    // Write CSV (append to existing)
+    const csvPath = path.join(paths.userDir, 'birthdays.csv');
+
+    // Load existing birthdays
+    const existingBirthdays: { name: string; date: string }[] = [];
+    if (fs.existsSync(csvPath)) {
+        const lines = fs.readFileSync(csvPath, 'utf-8').split('\n').slice(1); // skip header
+        for (const line of lines) {
+            const match = line.match(/^"(.+)",(.+)$/);
+            if (match) {
+                existingBirthdays.push({ name: match[1].replace(/""/g, '"'), date: match[2] });
+            }
+        }
+    }
+
+    // Merge, avoiding duplicates (by name)
+    const existingNames = new Set(existingBirthdays.map(b => b.name.toLowerCase()));
+    let newCount = 0;
+    for (const b of birthdays) {
+        if (!existingNames.has(b.name.toLowerCase())) {
+            existingBirthdays.push(b);
+            newCount++;
+        }
+    }
+
+    // Sort by name
+    existingBirthdays.sort((a, b) => a.name.localeCompare(b.name));
+
+    const csvContent = 'name,date\n' + existingBirthdays.map(b => `"${b.name.replace(/"/g, '""')}",${b.date}`).join('\n');
+
+    if (mode === 'apply') {
+        fs.writeFileSync(csvPath, csvContent);
+        console.log(`  New birthdays added: ${newCount} (${existingBirthdays.length} total)`);
+    }
+
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Summary:`);
+    console.log(`  Contacts with birthdays: ${birthdays.length}`);
+    if (mode === 'apply') {
+        console.log(`  Contacts modified: ${contactsModified}`);
+        console.log(`  CSV file: ${csvPath}`);
+        console.log(`\nAfter review, run: gcards push -u ${user}`);
+    } else {
+        console.log(`\nTo extract birthdays, run: gfix birthday -u ${user} --apply`);
+    }
+}
+
+/** Fix fileAs fields: normalize "Last, First" to "First Last"
+ *  Also fix displayNameLastFirst to proper "Last, First" format */
+async function runFileAsFix(user: string, mode: 'inspect' | 'apply'): Promise<void> {
+    const paths = getUserPaths(user);
+
+    if (!fs.existsSync(paths.contactsDir)) {
+        console.error(`No contacts directory for user: ${user}`);
+        console.error(`Expected: ${paths.contactsDir}`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+    console.log(`\n${mode === 'inspect' ? 'INSPECT' : 'APPLY'} fileAs/displayNameLastFirst normalization for user: ${user}`);
+    console.log(`Found ${files.length} contact files\n`);
+
+    const needsReview: FileAsEntry[] = [];
+    let fileAsFixedCount = 0;
+    let displayNameLastFirstFixedCount = 0;
+    let skippedCount = 0;
+
+    for (const file of files) {
+        const filePath = path.join(paths.contactsDir, file);
+        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+
+        const name = contact.names?.[0];
+        const givenName = name?.givenName || '';
+        const familyName = name?.familyName || '';
+        const displayName = name?.displayName || '';
+        let modified = false;
+
+        // Fix displayNameLastFirst if we have givenName and familyName
+        if (name && givenName && familyName) {
+            const expectedLastFirst = `${familyName}, ${givenName}`;
+            if (name.displayNameLastFirst !== expectedLastFirst) {
+                console.log(`  ${displayName}: displayNameLastFirst "${name.displayNameLastFirst || ''}" -> "${expectedLastFirst}"`);
+                if (mode === 'apply') {
+                    name.displayNameLastFirst = expectedLastFirst;
+                    modified = true;
+                }
+                displayNameLastFirstFixedCount++;
+            }
+        }
+
+        // Fix fileAs: "Last, First" -> "First Last"
+        if (contact.fileAses?.length) {
+            const fileAs = contact.fileAses[0].value || '';
+
+            // Check if fileAs is "Last, First" format
+            const commaMatch = fileAs.match(/^(.+),\s*(.+)$/);
+            if (commaMatch) {
+                const [, lastPart, firstPart] = commaMatch;
+
+                // If we have givenName and familyName, we can auto-fix
+                if (givenName && familyName) {
+                    // Verify the parts match (case-insensitive)
+                    const firstMatches = firstPart.toLowerCase().startsWith(givenName.toLowerCase()) ||
+                                         givenName.toLowerCase().startsWith(firstPart.toLowerCase());
+                    const lastMatches = lastPart.toLowerCase() === familyName.toLowerCase();
+
+                    if (firstMatches && lastMatches) {
+                        const newFileAs = `${givenName} ${familyName}`;
+                        console.log(`  ${displayName}: fileAs "${fileAs}" -> "${newFileAs}"`);
+
+                        if (mode === 'apply') {
+                            contact.fileAses[0].value = newFileAs;
+                            modified = true;
+                        }
+                        fileAsFixedCount++;
+                    } else {
+                        // Mismatch - add to review
+                        needsReview.push({ givenName, familyName, fileAs, jsonFile: file });
+                        skippedCount++;
+                    }
+                } else {
+                    // No familyName - need manual review
+                    needsReview.push({ givenName: givenName || displayName, familyName, fileAs, jsonFile: file });
+                    skippedCount++;
+                }
+            }
+        }
+
+        if (modified) {
+            fs.writeFileSync(filePath, JSON.stringify(contact, null, 2));
+        }
+    }
+
+    // Write CSV for entries needing review
+    if (needsReview.length > 0) {
+        needsReview.sort((a, b) => a.fileAs.localeCompare(b.fileAs));
+        const csvPath = path.join(paths.userDir, 'namefix.csv');
+        const csvContent = 'givenName,familyName,fileAs,jsonFile\n' +
+            needsReview.map(e =>
+                `"${e.givenName.replace(/"/g, '""')}","${e.familyName.replace(/"/g, '""')}","${e.fileAs.replace(/"/g, '""')}","${e.jsonFile}"`
+            ).join('\n');
+
+        if (mode === 'apply') {
+            fs.writeFileSync(csvPath, csvContent);
+        }
+
+        console.log(`\nEntries needing manual review:`);
+        for (const entry of needsReview) {
+            console.log(`  ${entry.fileAs} (${entry.jsonFile})`);
+        }
+        if (mode === 'apply') {
+            console.log(`\nCSV for review: ${csvPath}`);
+        }
+    }
+
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Summary:`);
+    console.log(`  fileAs fixed: ${fileAsFixedCount}`);
+    console.log(`  displayNameLastFirst fixed: ${displayNameLastFirstFixedCount}`);
+    console.log(`  Needs review: ${skippedCount}`);
+    if (mode === 'inspect' && (fileAsFixedCount > 0 || displayNameLastFirstFixedCount > 0)) {
+        console.log(`\nTo apply fixes, run: gfix fileas -u ${user} --apply`);
+    }
+    if (mode === 'apply' && (fileAsFixedCount > 0 || displayNameLastFirstFixedCount > 0)) {
+        console.log(`\nAfter review, run: gcards push -u ${user}`);
+    }
+}
+
+/** Clean fileAs value - strip leading/trailing junk */
+function cleanFileAs(value: string): string {
+    if (!value) return null;
+    return value.replace(/^[\s\-,]+|[\s\-,]+$/g, '').replace(/[\s\-,]+/g, ' ').trim() || null;
+}
+
+/** Surname particles that are part of the family name */
+const SURNAME_PARTICLES = new Set([
+    'de', 'da', 'di', 'del', 'della', 'dei', 'dos', 'das', 'do',  // Romance
+    'von', 'van', 'vander', 'vanden', 'ver',                       // Germanic
+    'le', 'la', 'les', 'du', "d'",                                 // French
+    'el', 'al', 'bin', 'ibn', 'ben', 'bint',                       // Arabic/Hebrew
+    'mac', 'mc', "o'",                                             // Celtic
+    'ter', 'ten', 'op', 'den', 'het',                              // Dutch
+    'af', 'av',                                                     // Scandinavian
+]);
+
+/** Honorific prefixes (Mr., Dr., etc.)
+ *  IMPORTANT: Only include unambiguous honorifics that are unlikely to be first names.
+ *  Excluded: don (common name Don), sir (could be name), etc.
+ */
+const HONORIFIC_PREFIXES = new Set([
+    // English - require period to avoid false positives on names
+    'mr.', 'mrs.', 'ms.', 'miss', 'mx.',
+    'dr.', 'prof.', 'professor',
+    'dame', 'lady', 'lord',
+    'rev.', 'reverend', 'fr.', 'father', 'pastor', 'bishop',
+    'rabbi', 'imam', 'elder',
+    'judge', 'justice', 'hon.', 'honorable',
+    'sen.', 'senator', 'rep.', 'representative',
+    'gov.', 'governor', 'mayor', 'pres.', 'president',
+    'gen.', 'general', 'col.', 'colonel',
+    'capt.', 'captain', 'lt.', 'lieutenant',
+    'sgt.', 'sergeant', 'cpl.', 'corporal',
+    'adm.', 'admiral', 'cmdr.', 'commander',
+    // Other languages
+    'herr', 'frau', 'fräulein',  // German
+    'monsieur', 'm.', 'madame', 'mme.', 'mademoiselle', 'mlle.',  // French
+    'señor', 'sr.', 'señora', 'sra.', 'señorita', 'srta.',  // Spanish
+    'signor', 'sig.', 'signora', 'signore',  // Italian
+    'doña', 'dona',  // Spanish/Italian (but NOT 'don' - it's a common name)
+]);
+
+/** Known name suffixes (after comma) */
+const NAME_SUFFIXES = new Set([
+    // Generational
+    'jr', 'jr.', 'sr', 'sr.', 'i', 'ii', 'iii', 'iv', 'v',
+    // Academic
+    'phd', 'ph.d', 'ph.d.', 'md', 'm.d', 'm.d.', 'do', 'd.o', 'd.o.',
+    'dds', 'd.d.s', 'd.d.s.', 'dmd', 'd.m.d', 'd.m.d.',
+    'jd', 'j.d', 'j.d.', 'llb', 'll.b', 'll.b.', 'llm', 'll.m', 'll.m.',
+    'mba', 'm.b.a', 'm.b.a.', 'ma', 'm.a', 'm.a.', 'ms', 'm.s', 'm.s.',
+    'ba', 'b.a', 'b.a.', 'bs', 'b.s', 'b.s.', 'bsc', 'b.sc', 'b.sc.',
+    'edd', 'ed.d', 'ed.d.',
+    // Professional certifications
+    'cpa', 'c.p.a', 'c.p.a.', 'cfa', 'c.f.a', 'c.f.a.',
+    'pe', 'p.e', 'p.e.', 'esq', 'esq.',
+    'rn', 'r.n', 'r.n.', 'lpn', 'l.p.n', 'l.p.n.',
+    'cae', 'c.a.e', 'c.a.e.', 'pmp', 'p.m.p', 'p.m.p.',
+    'cissp', 'ccna', 'mcse', 'aws',
+    // Military/Religious
+    'ret', 'ret.', 'usn', 'usa', 'usaf', 'usmc',
+    'sj', 's.j', 's.j.', 'op', 'o.p', 'o.p.', 'osb', 'o.s.b', 'o.s.b.',
+]);
+
+/** Convert ALL CAPS to Title Case, preserve mixed case */
+function fixCase(name: string): string {
+    if (!name) return name;
+    // Only fix if entirely uppercase (allow for McName, O'Brien etc.)
+    if (name === name.toUpperCase() && name.length > 1) {
+        return name.charAt(0).toUpperCase() + name.slice(1).toLowerCase();
+    }
+    return name;
+}
+
+/** Words that suggest a company name rather than a person */
+const COMPANY_INDICATORS = new Set([
+    'inc', 'inc.', 'incorporated', 'llc', 'l.l.c', 'l.l.c.',
+    'corp', 'corp.', 'corporation', 'co', 'co.', 'company',
+    'ltd', 'ltd.', 'limited', 'plc', 'p.l.c', 'p.l.c.',
+    'gmbh', 'ag', 'sa', 'nv', 'bv', 'pty',
+    'associates', 'association', 'assoc', 'assoc.',
+    'foundation', 'institute', 'university', 'college', 'school',
+    'hospital', 'clinic', 'medical', 'health', 'healthcare',
+    'services', 'service', 'solutions', 'consulting', 'consultants',
+    'group', 'partners', 'partnership', 'holdings', 'enterprises',
+    'systems', 'technologies', 'technology', 'tech', 'software',
+    'bank', 'insurance', 'financial', 'investments', 'capital',
+    'international', 'global', 'national', 'regional',
+    'support', 'helpdesk', 'customer',
+    'department', 'dept', 'dept.', 'division', 'office', 'bureau',
+    'council', 'committee', 'board', 'commission', 'agency',
+    'church', 'ministry', 'ministries', 'temple', 'mosque', 'synagogue',
+]);
+
+/** Check if a name looks like a company/organization rather than a person */
+function looksLikeCompany(name: string): boolean {
+    const words = name.toLowerCase().split(/\s+/);
+
+    // Check for company indicator words
+    for (const word of words) {
+        if (COMPANY_INDICATORS.has(word.replace(/[.,]/g, ''))) {
+            return true;
+        }
+    }
+
+    // Note: We don't flag all-caps names as companies anymore.
+    // "MR DAVID MORRIS" is a valid person name that just needs case conversion.
+    // fixCase() will handle converting ALL CAPS to Title Case.
+
+    return false;
+}
+
+interface ParsedName {
+    prefix: string;
+    first: string;
+    middle: string;
+    last: string;
+    suffix: string;
+    ambiguous: boolean;
+    isCompany: boolean;
+}
+
+/** Normalize honorific prefix - just capitalize first letter, don't expand */
+function normalizePrefix(prefix: string): string {
+    // Capitalize first letter, preserve rest as-is
+    const normalized = prefix.charAt(0).toUpperCase() + prefix.slice(1).toLowerCase();
+    // Ensure period at end for abbreviations (but not full words like "Miss")
+    const fullWords = new Set(['miss', 'dame', 'lady', 'lord', 'father', 'pastor', 'bishop',
+        'rabbi', 'imam', 'elder', 'judge', 'justice', 'honorable', 'senator', 'representative',
+        'governor', 'mayor', 'president', 'general', 'colonel', 'captain', 'lieutenant',
+        'sergeant', 'corporal', 'admiral', 'commander', 'professor', 'reverend',
+        'herr', 'frau', 'fräulein', 'monsieur', 'madame', 'mademoiselle',
+        'señor', 'señora', 'señorita', 'signor', 'signora', 'signore', 'doña', 'dona']);
+    const lower = prefix.toLowerCase().replace(/\./g, '');
+    if (fullWords.has(lower)) {
+        return normalized.replace(/\.$/, '');  // No trailing period for full words
+    }
+    return normalized.endsWith('.') ? normalized : normalized + '.';
+}
+
+/** Parse a full name into prefix, first, middle, last, suffix components */
+function parseFullName(fullName: string): ParsedName {
+    let prefix = '';
+    let suffix = '';
+    let namePart = fullName.trim();
+    let ambiguous = false;
+    const isCompany = looksLikeCompany(fullName);
+
+    // Check for comma - could be "Last, First" or "First Last, Suffix"
+    const commaIndex = namePart.indexOf(',');
+    if (commaIndex > 0) {
+        const beforeComma = namePart.substring(0, commaIndex).trim();
+        const afterComma = namePart.substring(commaIndex + 1).trim();
+
+        // Check if after-comma part is a known suffix
+        const afterLower = afterComma.toLowerCase().replace(/\./g, '');
+        if (NAME_SUFFIXES.has(afterLower) || NAME_SUFFIXES.has(afterLower.replace(/\s+/g, ''))) {
+            suffix = afterComma;
+            namePart = beforeComma;
+        } else {
+            // Could be "Last, First" format or unknown suffix
+            const beforeParts = beforeComma.split(/\s+/);
+            const afterParts = afterComma.split(/\s+/);
+
+            if (beforeParts.length === 1 && afterParts.length >= 1) {
+                // Ambiguous: could be "Smith, John" or "John Smith, UnknownSuffix"
+                ambiguous = true;
+            }
+            // For now, assume it's a suffix if short and all caps
+            if (afterComma.length <= 10 && afterComma === afterComma.toUpperCase()) {
+                suffix = afterComma;
+                namePart = beforeComma;
+            } else {
+                ambiguous = true;
+            }
+        }
+    }
+
+    let rawParts = namePart.split(/\s+/);
+
+    // Check for honorific prefix at the start BEFORE case normalization
+    // Recognize if: has a period (e.g., "Mr."), is a full word (e.g., "Miss"),
+    // or is ALL CAPS short abbreviation (e.g., "MR" -> "Mr.")
+    if (rawParts.length > 1) {
+        const firstWord = rawParts[0];
+        const firstLower = firstWord.toLowerCase();
+        // Check with period (e.g., "mr." matches "mr.")
+        // Or without period for full words (e.g., "miss")
+        // Or ALL CAPS short abbreviation (e.g., "MR" -> recognized as "mr.")
+        const withPeriod = firstLower.endsWith('.') ? firstLower : firstLower + '.';
+        if (HONORIFIC_PREFIXES.has(firstLower) ||
+            HONORIFIC_PREFIXES.has(firstLower.replace(/\.$/, '')) ||
+            (firstWord === firstWord.toUpperCase() && firstWord.length <= 4 && HONORIFIC_PREFIXES.has(withPeriod))) {
+            prefix = normalizePrefix(firstWord);
+            rawParts = rawParts.slice(1);
+        }
+    }
+
+    // Now apply case normalization
+    const parts = rawParts.map(fixCase);
+
+    if (parts.length === 0) {
+        return { prefix, first: '', middle: '', last: '', suffix, ambiguous, isCompany };
+    }
+    if (parts.length === 1) {
+        return { prefix, first: parts[0], middle: '', last: '', suffix, ambiguous, isCompany };
+    }
+    if (parts.length === 2) {
+        return { prefix, first: parts[0], middle: '', last: parts[1], suffix, ambiguous, isCompany };
+    }
+
+    // 3+ parts: check for surname particles
+    let familyStartIndex = parts.length - 1;
+
+    for (let i = parts.length - 2; i >= 1; i--) {
+        const lower = parts[i].toLowerCase().replace(/[.']/g, '');
+        if (SURNAME_PARTICLES.has(lower)) {
+            familyStartIndex = i;
+        } else {
+            break;
+        }
+    }
+
+    return {
+        prefix,
+        first: parts[0],
+        middle: parts.slice(1, familyStartIndex).join(' '),
+        last: parts.slice(familyStartIndex).join(' '),
+        suffix,
+        ambiguous,
+        isCompany
+    };
+}
+
+/** Fix names: parse givenName into first/middle/last, clean fileAs */
+async function runNamesFix(user: string, mode: 'inspect' | 'apply'): Promise<void> {
+    const paths = getUserPaths(user);
+
+    if (!fs.existsSync(paths.contactsDir)) {
+        console.error(`No contacts directory for user: ${user}`);
+        console.error(`Expected: ${paths.contactsDir}`);
+        process.exit(1);
+    }
+
+    let files = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+    console.log(`\n${mode === 'inspect' ? 'INSPECT' : 'APPLY'} name parsing for user: ${user}`);
+    console.log(`Found ${files.length} contact files\n`);
+
+    // Apply limit if set
+    if (processLimit > 0 && files.length > processLimit) {
+        files = files.slice(0, processLimit);
+    }
+
+    const changeLogs: NameChangeLog[] = [];
+    const problems: string[] = [];
+    let contactsModified = 0;
+
+    for (const file of files) {
+        const filePath = path.join(paths.contactsDir, file);
+        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+
+        const name = contact.names?.[0];
+        if (!name) continue;
+
+        const changes: string[] = [];
+        let modified = false;
+        let parsedFirst = '';
+        let parsedLast = '';
+
+        // Check displayName for corruption (repeated words like "Dr. Dr. Dr. Dr.")
+        const displayName = name.displayName || name.givenName || 'Unknown';
+        const displayWords = displayName.split(/\s+/);
+        if (displayWords.length > 4) {
+            const wordCounts = new Map<string, number>();
+            for (const w of displayWords) {
+                wordCounts.set(w.toLowerCase(), (wordCounts.get(w.toLowerCase()) || 0) + 1);
+            }
+            const maxCount = Math.max(...wordCounts.values());
+            if (maxCount > 3) {
+                problems.push(`${file}: repeated words in displayName (${maxCount}x) - corrupted data`);
+                console.log(`  [CORRUPTED] ${displayName.slice(0, 60)}... (${file})`);
+                continue;
+            }
+        }
+
+        // If givenName exists but no familyName, parse it
+        if (name.givenName && !name.familyName) {
+            // Check for repeated words (corrupted data like "Smith Smith Smith...")
+            const words = name.givenName.split(/\s+/);
+            if (words.length > 4) {
+                const wordCounts = new Map<string, number>();
+                for (const w of words) {
+                    wordCounts.set(w.toLowerCase(), (wordCounts.get(w.toLowerCase()) || 0) + 1);
+                }
+                const maxCount = Math.max(...wordCounts.values());
+                if (maxCount > 3) {
+                    const displayName = name.displayName || name.givenName.slice(0, 50) + '...' || 'Unknown';
+                    problems.push(`${file}: repeated words (${maxCount}x) - corrupted data`);
+                    console.log(`  [CORRUPTED] ${displayName} (${file})`);
+                    continue;
+                }
+            }
+
+            // Check for email addresses
+            if (name.givenName.includes('@')) {
+                const displayName = name.displayName || name.givenName || 'Unknown';
+                problems.push(`${file}: "${name.givenName}" - email address, not a name`);
+                console.log(`  [EMAIL] ${displayName} (${file}): "${name.givenName}"`);
+                continue;
+            }
+
+            const parsed = parseFullName(name.givenName);
+
+            // Check for company names first
+            if (parsed.isCompany) {
+                const displayName = name.displayName || name.givenName || 'Unknown';
+                problems.push(`${file}: "${name.givenName}" - looks like a company name`);
+                console.log(`  [COMPANY] ${displayName} (${file}): "${name.givenName}"`);
+                continue;
+            }
+
+            // Check for ambiguous cases
+            if (parsed.ambiguous) {
+                const displayName = name.displayName || name.givenName || 'Unknown';
+                problems.push(`${file}: "${name.givenName}" - ambiguous (could be "Last, First" or unknown suffix)`);
+                console.log(`  [AMBIGUOUS] ${displayName} (${file}): "${name.givenName}"`);
+                continue;
+            }
+
+            // Check if no parseable last name
+            if (!parsed.last) {
+                const displayName = name.displayName || name.givenName || 'Unknown';
+                problems.push(`${file}: "${name.givenName}" - no last name detected`);
+                console.log(`  [NO LAST NAME] ${displayName} (${file}): "${name.givenName}"`);
+                continue;
+            }
+
+            parsedFirst = parsed.first;
+            parsedLast = parsed.last;
+
+            // We can split this name
+            const oldGiven = name.givenName;
+            changes.push(`givenName: "${oldGiven}" -> "${parsed.first}"`);
+            if (parsed.prefix) {
+                changes.push(`honorificPrefix: "${name.honorificPrefix || ''}" -> "${parsed.prefix}"`);
+            }
+            if (parsed.middle) {
+                changes.push(`middleName: "" -> "${parsed.middle}"`);
+            }
+            changes.push(`familyName: "" -> "${parsed.last}"`);
+            if (parsed.suffix) {
+                changes.push(`honorificSuffix: "" -> "${parsed.suffix}"`);
+            }
+
+            if (mode === 'apply') {
+                name.givenName = parsed.first;
+                if (parsed.prefix) {
+                    name.honorificPrefix = parsed.prefix;
+                }
+                if (parsed.middle) {
+                    name.middleName = parsed.middle;
+                }
+                name.familyName = parsed.last;
+                if (parsed.suffix) {
+                    name.honorificSuffix = parsed.suffix;
+                }
+                // Update displayNameLastFirst
+                name.displayNameLastFirst = `${parsed.last}, ${parsed.first}${parsed.middle ? ' ' + parsed.middle : ''}`;
+                modified = true;
+            }
+        }
+
+        // Get the final familyName and givenName (may have been set above or already exist)
+        const finalGivenName = mode === 'apply' ? name.givenName : (parsedFirst || name.givenName);
+        const finalFamilyName = mode === 'apply' ? name.familyName : (parsedLast || name.familyName);
+
+        // Clean and fix fileAs entries - should be "Last, First" format
+        if (contact.fileAses?.length) {
+            for (let i = 0; i < contact.fileAses.length; i++) {
+                const fileAs = contact.fileAses[i];
+                const oldValue = fileAs.value || '';
+
+                // If we have givenName and familyName, set fileAs to proper "Last, First"
+                if (finalFamilyName && finalGivenName) {
+                    const expectedFileAs = `${finalFamilyName}, ${finalGivenName}`;
+                    if (oldValue !== expectedFileAs) {
+                        changes.push(`fileAs[${i}]: "${oldValue}" -> "${expectedFileAs}"`);
+                        if (mode === 'apply') {
+                            fileAs.value = expectedFileAs;
+                            modified = true;
+                        }
+                    }
+                } else {
+                    // No proper names - just clean junk
+                    const cleanedValue = cleanFileAs(oldValue);
+                    if (cleanedValue !== oldValue) {
+                        if (cleanedValue) {
+                            changes.push(`fileAs[${i}]: "${oldValue}" -> "${cleanedValue}"`);
+                            if (mode === 'apply') {
+                                fileAs.value = cleanedValue;
+                                modified = true;
+                            }
+                        } else {
+                            changes.push(`fileAs[${i}]: "${oldValue}" -> [DELETE]`);
+                            if (mode === 'apply') {
+                                contact.fileAses.splice(i, 1);
+                                i--;
+                                modified = true;
+                            }
+                        }
+                    }
+                }
+            }
+
+            // Remove empty fileAses array
+            if (mode === 'apply' && contact.fileAses.length === 0) {
+                delete contact.fileAses;
+            }
+        }
+
+        // Check for duplicate phone numbers
+        const duplicatePhones = findDuplicatePhones(contact.phoneNumbers);
+        if (duplicatePhones.length > 0) {
+            changes.push(`phoneNumbers: remove duplicates: ${duplicatePhones.join(', ')}`);
+            if (mode === 'apply') {
+                const seen = new Set<string>();
+                contact.phoneNumbers = contact.phoneNumbers.filter(phone => {
+                    const normalized = normalizePhone(phone.value || phone.canonicalForm);
+                    if (seen.has(normalized)) return false;
+                    seen.add(normalized);
+                    return true;
+                });
+                modified = true;
+            }
+        }
+
+        // Check for duplicate email addresses
+        const duplicateEmails = findDuplicateEmails(contact.emailAddresses);
+        if (duplicateEmails.length > 0) {
+            changes.push(`emailAddresses: remove duplicates: ${duplicateEmails.join(', ')}`);
+            if (mode === 'apply') {
+                const seen = new Set<string>();
+                contact.emailAddresses = contact.emailAddresses.filter(email => {
+                    const normalized = normalizeEmail(email.value);
+                    if (seen.has(normalized)) return false;
+                    seen.add(normalized);
+                    return true;
+                });
+                modified = true;
+            }
+        }
+
+        if (changes.length > 0) {
+            const displayName = name.displayName || name.givenName || 'Unknown';
+            changeLogs.push({ jsonFile: file, displayName, changes });
+
+            console.log(`\n${displayName} (${file})`);
+            for (const change of changes) {
+                console.log(`   ${change}`);
+            }
+
+            if (modified) {
+                fs.writeFileSync(filePath, JSON.stringify(contact, null, 2));
+                contactsModified++;
+            }
+        }
+    }
+
+    // Write changes.log
+    if (changeLogs.length > 0 && mode === 'apply') {
+        const logPath = path.join(paths.userDir, 'changes.log');
+        const logContent = changeLogs.map(log =>
+            `=== ${log.jsonFile} (${log.displayName}) ===\n${log.changes.map(c => '  ' + c).join('\n')}`
+        ).join('\n\n');
+        fs.writeFileSync(logPath, logContent);
+        console.log(`\nLog file: ${logPath}`);
+    }
+
+    // Write problems.txt for ambiguous cases
+    if (problems.length > 0) {
+        const problemsPath = path.join(paths.userDir, 'problems.txt');
+        fs.writeFileSync(problemsPath, problems.join('\n'));
+        console.log(`\nProblems file: ${problemsPath}`);
+    }
+
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Summary:`);
+    console.log(`  Contacts with changes: ${changeLogs.length}`);
+    console.log(`  Ambiguous (see problems.txt): ${problems.length}`);
+    if (mode === 'apply') {
+        console.log(`  Contacts modified: ${contactsModified}`);
+    }
+    if (mode === 'inspect' && changeLogs.length > 0) {
+        console.log(`\nTo apply fixes, run: gfix names -u ${user} --apply`);
+    }
+    if (mode === 'apply' && contactsModified > 0) {
+        console.log(`\nAfter review, run: gcards push -u ${user}`);
+    }
+}
+
+async function runFix(user: string, mode: 'inspect' | 'apply'): Promise<void> {
+    const paths = getUserPaths(user);
+
+    if (!fs.existsSync(paths.contactsDir)) {
+        console.error(`No contacts directory for user: ${user}`);
+        console.error(`Expected: ${paths.contactsDir}`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+
+    console.log(`\n${mode === 'inspect' ? 'INSPECT' : 'APPLY'} mode for user: ${user}`);
+    console.log(`Found ${files.length} contact files\n`);
+
+    const allChanges: ContactChange[] = [];
+
+    for (const file of files) {
+        const filePath = path.join(paths.contactsDir, file);
+        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+        const changes = processContact(contact);
+
+        if (changes.length > 0) {
+            const displayName = contact.names?.[0]?.displayName || 'Unknown';
+            allChanges.push({
+                resourceName: contact.resourceName,
+                displayName,
+                filePath,
+                changes
+            });
+
+            console.log(`\n${displayName} (${contact.resourceName})`);
+            for (const change of changes) {
+                if (change.field === 'phoneNumbers') {
+                    const phoneChange = change as PhoneRemoval;
+                    console.log(`   phoneNumbers: remove duplicates: ${phoneChange.removed.join(', ')}`);
+                } else if (change.field === 'emailAddresses') {
+                    const emailChange = change as EmailRemoval;
+                    console.log(`   emailAddresses: remove duplicates: ${emailChange.removed.join(', ')}`);
+                } else {
+                    const fieldChange = change as FieldChange;
+                    if (!fieldChange.newValue) {
+                        console.log(`   ${fieldChange.field}: "${fieldChange.oldValue}" -> [DELETE]`);
+                    } else {
+                        console.log(`   ${fieldChange.field}: "${fieldChange.oldValue}" -> "${fieldChange.newValue}"`);
+                    }
+                }
+            }
+
+            if (mode === 'apply') {
+                applyChangesToContact(contact, changes);
+                fs.writeFileSync(filePath, JSON.stringify(contact, null, 2));
+                console.log(`   ✅ Applied`);
+            }
+        }
+    }
+
+    // Create log file
+    const log: FixLog = {
+        timestamp: new Date().toISOString(),
+        user,
+        mode,
+        totalContacts: files.length,
+        contactsChanged: allChanges.length,
+        changes: allChanges
+    };
+
+    if (!fs.existsSync(paths.fixLogDir)) {
+        fs.mkdirSync(paths.fixLogDir, { recursive: true });
+    }
+
+    const logFileName = `fix-names-${mode}-${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
+    const logPath = path.join(paths.fixLogDir, logFileName);
+    fs.writeFileSync(logPath, JSON.stringify(log, null, 2));
+
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Summary:`);
+    console.log(`  Total contacts: ${files.length}`);
+    console.log(`  Contacts with changes: ${allChanges.length}`);
+    console.log(`  Total field changes: ${allChanges.reduce((sum, c) => sum + c.changes.length, 0)}`);
+    console.log(`  Log file: ${logPath}`);
+
+    if (mode === 'inspect' && allChanges.length > 0) {
+        console.log(`\nTo apply changes, run: gfix apply -u ${user}`);
+        console.log(`After applying, run: gcards push -u ${user}`);
+    }
+}
+
+
+/** Find duplicate contacts by name + email overlap */
+async function runUndup(user: string): Promise<void> {
+    const paths = getUserPaths(user);
+
+    if (!fs.existsSync(paths.contactsDir)) {
+        console.error(`No contacts directory for user: ${user}`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(paths.contactsDir).filter(f => f.endsWith('.json'));
+    console.log(`\nScanning ${files.length} contacts for duplicates...\n`);
+
+    // Build map of name -> contacts with that name
+    const byName = new Map<string, { resourceName: string; emails: string[]; displayName: string }[]>();
+
+    for (const file of files) {
+        const filePath = path.join(paths.contactsDir, file);
+        const contact = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+
+        const name = contact.names?.[0];
+        if (!name) continue;
+
+        // Normalize name for matching: lowercase, remove punctuation
+        const displayName = name.displayName || `${name.givenName || ''} ${name.familyName || ''}`.trim();
+        const normalizedName = displayName.toLowerCase().replace(/[^a-z0-9\s]/g, '').replace(/\s+/g, ' ').trim();
+
+        if (!normalizedName) continue;
+
+        // Get all emails
+        const emails = (contact.emailAddresses || [])
+            .map(e => e.value?.toLowerCase().trim())
+            .filter((e): e is string => !!e);
+
+        if (!byName.has(normalizedName)) {
+            byName.set(normalizedName, []);
+        }
+        byName.get(normalizedName)!.push({
+            resourceName: contact.resourceName,
+            emails,
+            displayName
+        });
+    }
+
+    // Find merge candidates: same name AND overlapping email
+    const mergeEntries: MergeEntry[] = [];
+
+    for (const [normalizedName, contacts] of byName) {
+        if (contacts.length < 2) continue;
+
+        // Group contacts that share at least one email (union-find style)
+        const clusters: typeof contacts[] = [];
+
+        for (const contact of contacts) {
+            // Find clusters that share an email with this contact
+            const matchingClusters: number[] = [];
+            for (let i = 0; i < clusters.length; i++) {
+                const cluster = clusters[i];
+                const clusterEmails = new Set(cluster.flatMap(c => c.emails));
+                if (contact.emails.some(e => clusterEmails.has(e))) {
+                    matchingClusters.push(i);
+                }
+            }
+
+            if (matchingClusters.length === 0) {
+                // No overlap - start new cluster
+                clusters.push([contact]);
+            } else if (matchingClusters.length === 1) {
+                // Add to existing cluster
+                clusters[matchingClusters[0]].push(contact);
+            } else {
+                // Merge multiple clusters + add contact
+                const merged = [contact];
+                for (const idx of matchingClusters.sort((a, b) => b - a)) {
+                    merged.push(...clusters[idx]);
+                    clusters.splice(idx, 1);
+                }
+                clusters.push(merged);
+            }
+        }
+
+        // Only keep clusters with 2+ contacts (duplicates)
+        for (const cluster of clusters) {
+            if (cluster.length >= 2) {
+                const allEmails = [...new Set(cluster.flatMap(c => c.emails))].sort();
+                mergeEntries.push({
+                    name: cluster[0].displayName,
+                    emails: allEmails,
+                    resourceNames: cluster.map(c => c.resourceName)
+                });
+            }
+        }
+    }
+
+    // Sort by name, then first email
+    mergeEntries.sort((a, b) => {
+        const nameComp = a.name.localeCompare(b.name);
+        if (nameComp !== 0) return nameComp;
+        return (a.emails[0] || '').localeCompare(b.emails[0] || '');
+    });
+
+    // Write merger.json
+    const mergerPath = path.join(paths.userDir, 'merger.json');
+    fs.writeFileSync(mergerPath, JSON.stringify(mergeEntries, null, 2));
+
+    console.log(`Found ${mergeEntries.length} merge groups:`);
+    for (const entry of mergeEntries) {
+        console.log(`  ${entry.name} (${entry.resourceNames.length} contacts, ${entry.emails.length} emails)`);
+    }
+
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Merger file: ${mergerPath}`);
+    console.log(`\nEdit merger.json to remove entries you don't want to merge.`);
+    console.log(`Then run: gfix merge -u ${user}`);
+}
+
+/** Merge duplicate contacts locally (prepares for gcards push) */
+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');
+
+    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'));
+
+    if (entries.length === 0) {
+        console.log('No entries in merger.json');
+        return;
+    }
+
+    // Apply limit if specified
+    if (limit > 0 && entries.length > limit) {
+        console.log(`[DEBUG] Limiting to first ${limit} of ${entries.length} entries\n`);
+        entries = entries.slice(0, limit);
+    }
+
+    const toMerge = entries.filter(e => !e._delete);
+    const toDelete = entries.filter(e => e._delete);
+
+    console.log(`\nProcessing ${entries.length} groups for user: ${user}\n`);
+    if (toMerge.length > 0) {
+        console.log(`Merge (${toMerge.length}):`);
+        for (const entry of toMerge) {
+            console.log(`  ${entry.name}: ${entry.resourceNames.length} contacts -> 1`);
+        }
+    }
+    if (toDelete.length > 0) {
+        console.log(`Delete (${toDelete.length}):`);
+        for (const entry of toDelete) {
+            console.log(`  ${entry.name}: ${entry.resourceNames.length} contacts`);
+        }
+    }
+
+    // Load existing photos.json and merged.json
+    let savedPhotos: PhotoEntry[] = [];
+    if (fs.existsSync(photosPath)) {
+        savedPhotos = JSON.parse(fs.readFileSync(photosPath, 'utf-8'));
+    }
+
+    let mergedEntries: MergeEntry[] = [];
+    if (fs.existsSync(mergedPath)) {
+        mergedEntries = JSON.parse(fs.readFileSync(mergedPath, 'utf-8'));
+    }
+
+    let mergeSuccess = 0;
+    let deleteSuccess = 0;
+
+    // Process merges - update local files only
+    for (const entry of toMerge) {
+        console.log(`\nMerging ${entry.name}...`);
+
+        try {
+            // Load all contacts from local files
+            const contacts: GooglePerson[] = [];
+            for (const rn of entry.resourceNames) {
+                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')));
+                } else {
+                    throw new Error(`Contact file not found: ${filePath}`);
+                }
+            }
+
+            if (contacts.length < 2) {
+                console.log('  Skipped (need 2+ contacts)');
+                continue;
+            }
+
+            // Target is first, sources are rest
+            const [target, ...sources] = contacts;
+
+            // Collect photos from sources before marking for deletion
+            const sourcePhotoUrls = collectSourcePhotos(sources);
+            if (sourcePhotoUrls.length > 0) {
+                const displayName = target.names?.[0]?.displayName || entry.name;
+                savedPhotos.push({
+                    contactId: target.resourceName,
+                    name: displayName,
+                    photos: sourcePhotoUrls
+                });
+                console.log(`  Saved ${sourcePhotoUrls.length} photo(s) to photos.json`);
+            }
+
+            // Merge data into target
+            const mergedData = mergeContactData(target, sources);
+            const updatedTarget = { ...target, ...mergedData };
+
+            // Save updated target
+            const targetId = target.resourceName.replace('people/', '');
+            const targetPath = path.join(paths.contactsDir, `${targetId}.json`);
+            fs.writeFileSync(targetPath, JSON.stringify(updatedTarget, null, 2));
+            console.log(`  Updated ${targetPath}`);
+
+            // Mark sources for deletion
+            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));
+                console.log(`  Marked ${sourceId} for deletion`);
+            }
+
+            mergeSuccess++;
+            mergedEntries.push(entry);
+
+        } catch (error: any) {
+            console.log(`  ERROR: ${error.message}`);
+        }
+    }
+
+    // Process deletes - just mark files
+    for (const entry of toDelete) {
+        console.log(`\nMarking for deletion: ${entry.name}...`);
+
+        for (const rn of entry.resourceNames) {
+            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));
+                console.log(`  Marked ${id} for deletion`);
+                deleteSuccess++;
+            }
+        }
+        mergedEntries.push(entry);
+    }
+
+    // Save photos.json
+    if (savedPhotos.length > 0) {
+        fs.writeFileSync(photosPath, JSON.stringify(savedPhotos, null, 2));
+    }
+
+    // Save merged.json (history of processed entries)
+    fs.writeFileSync(mergedPath, JSON.stringify(mergedEntries, 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));
+    const newMerger = remainingEntries.filter(e => !processedNames.has(e.name));
+    fs.writeFileSync(mergerPath, JSON.stringify(newMerger, null, 2));
+
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Summary:`);
+    console.log(`  Merged: ${mergeSuccess}`);
+    console.log(`  Marked for deletion: ${deleteSuccess}`);
+    console.log(`  Remaining in merger.json: ${newMerger.length}`);
+    console.log(`\nRun 'gcards push -u ${user}' to apply changes to Google.`);
+}
+
+function showUsage(): void {
+    console.log(`
+gfix - One-time fix routines for gcards contacts
+
+Usage: gfix <command> -u <user> [options]
+
+Commands:
+    inspect     Show what would be changed (no modifications)
+    apply       Apply changes and create log file
+    birthday    Extract birthdays to CSV and remove from contacts
+    fileas      Normalize "Last, First" fileAs to "First Last"
+    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)
+
+Options:
+    -u, --user <name>   User profile to process
+    --apply             For birthday/fileas/names: actually apply changes
+    -limit <n>          Process only first n contacts (for testing)
+
+Fixes applied (inspect/apply):
+  - Remove leading/trailing dashes, quotes, spaces from names
+  - Extract repeated Dr./Prof. prefixes to honorificPrefix field
+  - Remove duplicate phone numbers
+  - Remove duplicate email addresses
+  - Example: "Dr. Dr. Sandy Rotter - -" → "Sandy Rotter" + honorificPrefix: "Dr."
+
+Birthday extraction:
+  - gfix birthday -u bob           # Preview birthdays found
+  - gfix birthday -u bob --apply   # Extract to birthdays.csv and remove
+
+FileAs normalization:
+  - gfix fileas -u bob             # Preview changes
+  - gfix fileas -u bob --apply     # Fix and create namefix.csv for manual review
+
+Name parsing (when givenName has full name but no familyName):
+  - gfix names -u bob              # Preview name splits
+  - gfix names -u bob --apply      # Split names and create changes.log
+
+Duplicate detection and merge:
+  - gfix undup -u bob              # Find duplicates -> merger.json
+  - Edit merger.json (remove false positives, add "_delete": true for spam)
+  - gfix merge -u bob              # Merge locally (updates files, marks for deletion)
+  - gcards push -u bob             # Push changes to Google
+  - gcards sync -u bob --full      # Resync to get updated contacts
+
+Workflow:
+  1. gfix inspect -u bob     # Review proposed changes
+  2. gfix apply -u bob       # Apply changes to local files
+  3. gcards push -u bob      # Push to Google
+`);
+}
+
+// Global limit for testing
+let processLimit = 0;
+
+async function main(): Promise<void> {
+    const args = process.argv.slice(2);
+
+    let command = '';
+    let user = '';
+    let applyFlag = false;
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if ((arg === '-u' || arg === '--user' || arg === '-user') && i + 1 < args.length) {
+            user = args[++i];
+        } else if (arg === '--apply') {
+            applyFlag = true;
+        } else if ((arg === '-limit' || arg === '--limit') && i + 1 < args.length) {
+            processLimit = parseInt(args[++i], 10) || 0;
+        } else if (!arg.startsWith('-') && !command) {
+            command = arg;
+        }
+    }
+
+    if (!command) {
+        showUsage();
+        return;
+    }
+
+    const resolvedUser = resolveUser(user);
+
+    if (processLimit > 0) {
+        console.log(`[DEBUG] Processing limited to first ${processLimit} contacts\n`);
+    }
+
+    if (command === 'birthday') {
+        await runBirthdayExtract(resolvedUser, applyFlag ? 'apply' : 'inspect');
+    } else if (command === 'fileas') {
+        await runFileAsFix(resolvedUser, applyFlag ? 'apply' : 'inspect');
+    } else if (command === 'names') {
+        await runNamesFix(resolvedUser, applyFlag ? 'apply' : 'inspect');
+    } else if (command === 'inspect' || command === 'apply') {
+        await runFix(resolvedUser, command);
+    } else if (command === 'undup') {
+        await runUndup(resolvedUser);
+    } else if (command === 'merge') {
+        await runMerge(resolvedUser, processLimit);
+    } else {
+        console.error(`Unknown command: ${command}`);
+        showUsage();
+        process.exit(1);
+    }
+}
+
+if (import.meta.main) {
+    await main();
+}