@bobfrankston/gcards 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(dir:*)",
+      "Bash(npm install)",
+      "Bash(tsc:*)",
+      "Bash(cat:*)",
+      "Bash(node -e:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "gcards sync",
+            "program": "${workspaceFolder}/gcards.ts",
+            "args": ["sync"],
+            "skipFiles": ["<node_internals>/**"]
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "gcards sync --full",
+            "program": "${workspaceFolder}/gcards.ts",
+            "args": ["sync", "--full"],
+            "skipFiles": ["<node_internals>/**"]
+        }
+    ]
+}

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "workbench.colorTheme": "Visual Studio 2019 Dark"
+}

package/.vscode/tasks.json

@@ -0,0 +1,20 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "tsc: check",
+            "type": "shell",
+            "command": "tsc",
+            "args": ["--watch"],
+            "runOptions": {
+                "runOn": "folderOpen"
+            },
+            "problemMatcher": "$tsc-watch",
+            "isBackground": true,
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

package/README.md

@@ -0,0 +1,61 @@
+# Google Contacts Cleanup Tool (gcards)
+
+## Goal
+Intelligent cleanup and merging of Google Contacts using the People API.
+
+## Roadmap
+- **Current**: CLI tool
+- **Future**: GUI interface
+- **Eventually**: Own contacts database (vcf as intermediate format)
+
+## Features
+- Fetch contacts via Google People API (preserves `resourceName` for reconciliation)
+- Convert to simplified JSON structure for analysis
+- Identify duplicates: **exact match first** (many blatant dupes), fuzzy matching optional/later
+- Flag test entries (pattern: `m-\d+@bob\.ma` for "Bob Frankston")
+- Generate merge candidates with confidence scores
+- Apply changes back via API using `resourceName`
+- Export to vCard format (`vcf/` directory)
+
+## Approach
+1. **Auth**: OAuth2 with Google People API scope
+2. **Fetch**: Full fetch first, save `syncToken` for incremental updates
+3. **Transform**: Convert `GooglePerson[]` → `LocalContact[]` (see `types.ts`)
+4. **Analyze**: Exact duplicate detection first, test entry flagging
+5. **Review**: Output candidates for user review
+6. **Apply**: Update/delete via API using `resourceName`
+7. **Export**: Save to `vcf/` as vCards for local backup/future DB
+8. **Log**: Track deletions in `deletion-log.json` to detect re-additions
+
+## Sync Token Usage
+- After full fetch, save `nextSyncToken`
+- Subsequent fetches: pass `syncToken` → get only new/changed/deleted
+- Deleted entries appear with `metadata.deleted: true`
+- Token expires ~30 days → fall back to full fetch (410 GONE error)
+
+## Deletion Logging
+Maintain `deletion-log.json` with:
+- `resourceName`, `displayName`, `reason`, `deletedAt`, `originalData`
+- Allows detecting if cleaned-up contact reappears (re-synced, re-added)
+
+## Setup
+1. Create Google Cloud project
+2. Enable People API
+3. Create OAuth2 credentials (Desktop app)
+4. Download `credentials.json` to this directory
+
+## Directory Structure
+```
+gcards/
+├── README.md
+├── types.ts           # TypeScript definitions
+├── credentials.json   # OAuth2 credentials (gitignored)
+├── token.json         # OAuth tokens (gitignored)
+├── sync-token.json    # Sync token for incremental fetch
+├── deletion-log.json  # Track deleted contacts
+└── vcf/               # vCard exports for future DB
+```
+
+## Test Entry Pattern
+
+Emails matching `m-[2506|2512]+@bob\.ma` with name "Bob Frankston" are test business cards to be flagged/removed. 

package/cli.ts

@@ -0,0 +1,73 @@
+/**
+ * CLI argument parsing for gcards
+ */
+
+export interface CliOptions {
+    command: string;
+    user: string;   /** User profile name (default: 'default') */
+    full: boolean;  /** Force full sync instead of incremental */
+    yes: boolean;   /** Skip confirmation prompt */
+    help: boolean;
+    verbose: boolean;
+}
+
+export function parseArgs(args: string[]): CliOptions {
+    const options: CliOptions = {
+        command: '',
+        user: 'default',
+        full: false,
+        yes: false,
+        help: false,
+        verbose: false
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--full' || arg === '-f') {
+            options.full = true;
+        } else if (arg === '--yes' || arg === '-y') {
+            options.yes = true;
+        } else if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        } else if (arg === '--verbose' || arg === '-v') {
+            options.verbose = true;
+        } else if ((arg === '--user' || arg === '-user' || arg === '-u') && i + 1 < args.length) {
+            options.user = args[++i];
+        } else if (!arg.startsWith('-') && !options.command) {
+            options.command = arg;
+        }
+    }
+
+    return options;
+}
+
+export function showHelp(): void {
+    console.log(`
+gcards - Google Contacts management tool
+
+Usage: gcards <command> [options]
+
+Commands:
+    sync        Sync contacts from Google (incremental by default)
+    push        Push local changes to Google (with confirmation)
+
+Options:
+    --user, -u NAME User profile (default: 'default')
+    --full, -f      Force full sync (ignore sync token)
+    --yes, -y       Skip confirmation prompt
+    --verbose, -v   Verbose output
+    --help, -h      Show this help
+
+Deletion:
+    To delete a contact from Google, either:
+    - Edit the contact's JSON and add the field: "_deleted": true
+    - Or move the JSON file to the <user>/deleted/ folder
+    Then run 'gcards push' to apply the deletion
+
+Examples:
+    gcards sync                    # Sync default user
+    gcards sync -u bob             # Sync bob's contacts
+    gcards sync --full -u alice    # Full sync for alice
+    gcards push -u bob             # Push bob's changes
+`);
+}

package/gcards.ts

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+/**
+ * gcards - Google Contacts management tool
+ * Downloads and manages Google Contacts with incremental sync support
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parseArgs, showHelp } from './cli.ts';
+import { authenticateOAuth } from '../../../projects/oauth/oauthsupport/index.ts';
+import type { GooglePerson, GoogleConnectionsResponse } from './types.ts';
+
+const APP_DIR = import.meta.dirname;
+const DATA_DIR = path.join(APP_DIR, 'data');
+const CREDENTIALS_FILE = path.join(APP_DIR, 'credentials.json');
+const CONFIG_FILE = path.join(DATA_DIR, 'config.json');
+
+const PEOPLE_API_BASE = 'https://people.googleapis.com/v1';
+const CONTACTS_SCOPE_READ = 'https://www.googleapis.com/auth/contacts.readonly';
+const CONTACTS_SCOPE_WRITE = 'https://www.googleapis.com/auth/contacts';
+
+interface AppConfig {
+    lastUser?: string;
+}
+
+interface UserPaths {
+    userDir: string;
+    contactsDir: string;
+    deletedDir: string;
+    indexFile: string;
+    statusFile: string;
+    syncTokenFile: string;
+    tokenFile: string;
+    tokenWriteFile: string;
+}
+
+function loadConfig(): AppConfig {
+    if (fs.existsSync(CONFIG_FILE)) {
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    }
+    return {};
+}
+
+function saveConfig(config: AppConfig): void {
+    if (!fs.existsSync(DATA_DIR)) {
+        fs.mkdirSync(DATA_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/** Normalize Gmail username: lowercase, remove dots, strip +suffix and @domain */
+function normalizeUser(user: string): string {
+    return user.toLowerCase().split(/[+@]/)[0].replace(/\./g, '');
+}
+
+function getUserPaths(user: string): UserPaths {
+    const userDir = path.join(DATA_DIR, user);
+    return {
+        userDir,
+        contactsDir: path.join(userDir, 'contacts'),
+        deletedDir: path.join(userDir, 'deleted'),
+        indexFile: path.join(userDir, 'index.json'),
+        statusFile: path.join(userDir, 'status.json'),
+        syncTokenFile: path.join(userDir, 'sync-token.json'),
+        tokenFile: path.join(userDir, 'token.json'),
+        tokenWriteFile: path.join(userDir, 'token-write.json')
+    };
+}
+
+function ensureUserDir(user: string): void {
+    const paths = getUserPaths(user);
+    if (!fs.existsSync(paths.userDir)) {
+        fs.mkdirSync(paths.userDir, { recursive: true });
+    }
+}
+
+interface ContactIndex {
+    contacts: Record<string, IndexEntry>;  /** resourceName -> entry */
+    lastSync: string;
+    syncToken?: string;
+}
+
+interface IndexEntry {
+    resourceName: string;
+    displayName: string;
+    etag?: string;
+    deleted: boolean;
+    deletedAt?: string;
+    updatedAt: string;
+}
+
+interface PushStatus {
+    lastPush: string;  /** ISO timestamp of last push */
+}
+
+interface PendingChange {
+    type: 'update' | 'delete';
+    resourceName: string;
+    displayName: string;
+    filePath: string;
+}
+
+async function getAccessToken(user: string, writeAccess = false): Promise<string> {
+    if (!fs.existsSync(CREDENTIALS_FILE)) {
+        throw new Error(`Credentials file not found: ${CREDENTIALS_FILE}`);
+    }
+
+    const paths = getUserPaths(user);
+    ensureUserDir(user);
+
+    const scope = writeAccess ? CONTACTS_SCOPE_WRITE : CONTACTS_SCOPE_READ;
+    const tokenFileName = writeAccess ? 'token-write.json' : 'token.json';
+
+    const token = await authenticateOAuth(CREDENTIALS_FILE, {
+        scope,
+        tokenDirectory: paths.userDir,
+        tokenFileName,
+        credentialsKey: 'web',
+        includeOfflineAccess: true
+    });
+
+    if (!token) {
+        throw new Error('OAuth authentication failed');
+    }
+
+    return token.access_token;
+}
+
+function loadIndex(paths: UserPaths): ContactIndex {
+    if (fs.existsSync(paths.indexFile)) {
+        return JSON.parse(fs.readFileSync(paths.indexFile, 'utf-8'));
+    }
+    return { contacts: {}, lastSync: '' };
+}
+
+function saveIndex(paths: UserPaths, index: ContactIndex): void {
+    fs.writeFileSync(paths.indexFile, JSON.stringify(index, null, 2));
+}
+
+function loadSyncToken(paths: UserPaths): string | null {
+    if (fs.existsSync(paths.syncTokenFile)) {
+        const data = JSON.parse(fs.readFileSync(paths.syncTokenFile, 'utf-8'));
+        return data.syncToken || null;
+    }
+    return null;
+}
+
+function saveSyncToken(paths: UserPaths, token: string): void {
+    fs.writeFileSync(paths.syncTokenFile, JSON.stringify({ syncToken: token, savedAt: new Date().toISOString() }, null, 2));
+}
+
+async function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function fetchContactsWithRetry(
+    accessToken: string,
+    syncToken?: string,
+    pageToken?: string,
+    retryCount = 0
+): Promise<GoogleConnectionsResponse> {
+    const MAX_RETRIES = 10;
+    const BASE_DELAY = 5000;  /** 5 seconds base delay */
+
+    const params = new URLSearchParams({
+        personFields: 'names,emailAddresses,phoneNumbers,addresses,organizations,biographies,urls,birthdays,photos,memberships,metadata',
+        pageSize: '100'  /** Smaller page size to avoid quota issues */
+    });
+
+    if (syncToken) {
+        params.set('syncToken', syncToken);
+    }
+    params.set('requestSyncToken', 'true');
+
+    if (pageToken) {
+        params.set('pageToken', pageToken);
+    }
+
+    const url = `${PEOPLE_API_BASE}/people/me/connections?${params}`;
+    const response = await fetch(url, {
+        headers: { Authorization: `Bearer ${accessToken}` }
+    });
+
+    if (response.status === 410) {
+        console.log('Sync token expired, performing full sync...');
+        return fetchContactsWithRetry(accessToken, undefined, pageToken, 0);
+    }
+
+    if (response.status === 429) {
+        if (retryCount >= MAX_RETRIES) {
+            throw new Error(`Rate limit exceeded after ${MAX_RETRIES} retries`);
+        }
+        const delay = BASE_DELAY * Math.pow(2, retryCount);  /** Exponential backoff */
+        console.log(`Rate limited, waiting ${delay / 1000}s before retry ${retryCount + 1}/${MAX_RETRIES}...`);
+        await sleep(delay);
+        return fetchContactsWithRetry(accessToken, syncToken, pageToken, retryCount + 1);
+    }
+
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${await response.text()}`);
+    }
+
+    return await response.json() as GoogleConnectionsResponse;
+}
+
+function saveContact(paths: UserPaths, person: GooglePerson): void {
+    if (!fs.existsSync(paths.contactsDir)) {
+        fs.mkdirSync(paths.contactsDir, { recursive: true });
+    }
+
+    const id = person.resourceName.replace('people/', '');
+    const filePath = path.join(paths.contactsDir, `${id}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(person, null, 2));
+}
+
+function deleteContactFile(paths: UserPaths, resourceName: string): void {
+    const id = resourceName.replace('people/', '');
+    const filePath = path.join(paths.contactsDir, `${id}.json`);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}
+
+async function syncContacts(user: string, options: { full: boolean; verbose: boolean }): Promise<void> {
+    const paths = getUserPaths(user);
+    ensureUserDir(user);
+
+    console.log(`Syncing contacts for user: ${user}`);
+    console.log('Getting access token...');
+    const accessToken = await getAccessToken(user);
+
+    const index = loadIndex(paths);
+    let syncToken = options.full ? null : loadSyncToken(paths);
+
+    if (syncToken) {
+        console.log('Performing incremental sync...');
+    } else {
+        console.log('Performing full sync...');
+    }
+
+    let pageToken: string | undefined;
+    let totalProcessed = 0;
+    let added = 0;
+    let updated = 0;
+    let deleted = 0;
+    let pageNum = 0;
+
+    do {
+        pageNum++;
+        process.stdout.write(`\rFetching page ${pageNum}... (${totalProcessed} contacts so far)`);
+
+        const response = await fetchContactsWithRetry(accessToken, syncToken || undefined, pageToken);
+
+        if (response.connections) {
+            for (const person of response.connections) {
+                const isDeleted = person.metadata?.deleted === true;
+                const displayName = person.names?.[0]?.displayName || 'Unknown';
+
+                if (isDeleted) {
+                    if (index.contacts[person.resourceName]) {
+                        index.contacts[person.resourceName].deleted = true;
+                        index.contacts[person.resourceName].deletedAt = new Date().toISOString();
+                        deleteContactFile(paths, person.resourceName);
+                        deleted++;
+                        if (options.verbose) console.log(`\n  Deleted: ${displayName}`);
+                    }
+                } else {
+                    const existed = !!index.contacts[person.resourceName];
+                    saveContact(paths, person);
+
+                    index.contacts[person.resourceName] = {
+                        resourceName: person.resourceName,
+                        displayName,
+                        etag: person.etag,
+                        deleted: false,
+                        updatedAt: new Date().toISOString()
+                    };
+
+                    if (existed) {
+                        updated++;
+                        if (options.verbose) console.log(`\n  Updated: ${displayName}`);
+                    } else {
+                        added++;
+                        if (options.verbose) console.log(`\n  Added: ${displayName}`);
+                    }
+                }
+                totalProcessed++;
+            }
+        }
+
+        if (response.nextSyncToken) {
+            saveSyncToken(paths, response.nextSyncToken);
+            index.syncToken = response.nextSyncToken;
+        }
+
+        pageToken = response.nextPageToken;
+
+        // Save index after each page in case of interruption
+        index.lastSync = new Date().toISOString();
+        saveIndex(paths, index);
+
+        // Small delay between pages to be nice to the API
+        if (pageToken) {
+            await sleep(500);
+        }
+    } while (pageToken);
+
+    const activeContacts = Object.values(index.contacts).filter(c => !c.deleted).length;
+    const tombstones = Object.values(index.contacts).filter(c => c.deleted).length;
+
+    console.log(`\n\nSync complete:`);
+    console.log(`  Processed: ${totalProcessed}`);
+    console.log(`  Added: ${added}`);
+    console.log(`  Updated: ${updated}`);
+    console.log(`  Deleted: ${deleted}`);
+    console.log(`  Active contacts: ${activeContacts}`);
+    console.log(`  Tombstones: ${tombstones}`);
+}
+
+function loadStatus(paths: UserPaths): PushStatus {
+    if (fs.existsSync(paths.statusFile)) {
+        return JSON.parse(fs.readFileSync(paths.statusFile, 'utf-8'));
+    }
+    return { lastPush: '' };
+}
+
+function saveStatus(paths: UserPaths, status: PushStatus): void {
+    fs.writeFileSync(paths.statusFile, JSON.stringify(status, null, 2));
+}
+
+function findPendingChanges(paths: UserPaths): PendingChange[] {
+    const status = loadStatus(paths);
+    const lastPush = status.lastPush ? new Date(status.lastPush).getTime() : 0;
+    const changes: PendingChange[] = [];
+
+    // Check contacts/ for modified files and _deleted markers
+    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 modTime = stat.mtimeMs;
+
+            if (modTime > lastPush) {
+                const content = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson & { _deleted?: boolean };
+                const displayName = content.names?.[0]?.displayName || 'Unknown';
+
+                if (content._deleted) {
+                    changes.push({
+                        type: 'delete',
+                        resourceName: content.resourceName,
+                        displayName,
+                        filePath
+                    });
+                } else {
+                    changes.push({
+                        type: 'update',
+                        resourceName: content.resourceName,
+                        displayName,
+                        filePath
+                    });
+                }
+            }
+        }
+    }
+
+    // Check deleted/ folder
+    if (fs.existsSync(paths.deletedDir)) {
+        const files = fs.readdirSync(paths.deletedDir).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+            const filePath = path.join(paths.deletedDir, file);
+            const content = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as GooglePerson;
+            const displayName = content.names?.[0]?.displayName || 'Unknown';
+
+            changes.push({
+                type: 'delete',
+                resourceName: content.resourceName,
+                displayName,
+                filePath
+            });
+        }
+    }
+
+    return changes;
+}
+
+async function confirm(message: string): Promise<boolean> {
+    const readline = await import('readline');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+
+    return new Promise(resolve => {
+        rl.question(`${message} (y/N): `, answer => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+
+async function updateContactOnGoogle(accessToken: string, person: GooglePerson): Promise<void> {
+    const updateMask = 'names,emailAddresses,phoneNumbers,addresses,organizations,biographies,urls,birthdays';
+
+    const response = await fetch(`${PEOPLE_API_BASE}/${person.resourceName}:updateContact?updatePersonFields=${updateMask}`, {
+        method: 'PATCH',
+        headers: {
+            'Authorization': `Bearer ${accessToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(person)
+    });
+
+    if (!response.ok) {
+        throw new Error(`Update failed for ${person.resourceName}: ${response.status} ${await response.text()}`);
+    }
+}
+
+async function deleteContactOnGoogle(accessToken: string, resourceName: string): Promise<void> {
+    const response = await fetch(`${PEOPLE_API_BASE}/${resourceName}:deleteContact`, {
+        method: 'DELETE',
+        headers: { 'Authorization': `Bearer ${accessToken}` }
+    });
+
+    if (!response.ok) {
+        throw new Error(`Delete failed for ${resourceName}: ${response.status} ${await response.text()}`);
+    }
+}
+
+async function pushContacts(user: string, options: { yes: boolean; verbose: boolean }): Promise<void> {
+    const paths = getUserPaths(user);
+    ensureUserDir(user);
+
+    console.log(`Pushing contacts for user: ${user}`);
+    const changes = findPendingChanges(paths);
+
+    if (changes.length === 0) {
+        console.log('No pending changes to push.');
+        return;
+    }
+
+    const updates = changes.filter(c => c.type === 'update');
+    const deletes = changes.filter(c => c.type === 'delete');
+
+    console.log('\nPending changes:');
+    if (updates.length > 0) {
+        console.log(`\n  Updates (${updates.length}):`);
+        for (const c of updates) {
+            console.log(`    - ${c.displayName} (${c.resourceName})`);
+        }
+    }
+    if (deletes.length > 0) {
+        console.log(`\n  Deletions (${deletes.length}):`);
+        for (const c of deletes) {
+            console.log(`    - ${c.displayName} (${c.resourceName})`);
+        }
+    }
+
+    if (!options.yes) {
+        const confirmed = await confirm(`\nPush ${changes.length} change(s) to Google?`);
+        if (!confirmed) {
+            console.log('Aborted.');
+            return;
+        }
+    }
+
+    console.log('\nGetting access token (write access)...');
+    const accessToken = await getAccessToken(user, true);
+
+    const index = loadIndex(paths);
+    let successCount = 0;
+    let errorCount = 0;
+
+    for (const change of changes) {
+        try {
+            if (change.type === 'update') {
+                const content = JSON.parse(fs.readFileSync(change.filePath, 'utf-8')) as GooglePerson;
+                process.stdout.write(`Updating ${change.displayName}...`);
+                await updateContactOnGoogle(accessToken, content);
+                console.log(' done');
+                successCount++;
+            } else {
+                process.stdout.write(`Deleting ${change.displayName}...`);
+                await deleteContactOnGoogle(accessToken, change.resourceName);
+
+                // Update index
+                if (index.contacts[change.resourceName]) {
+                    index.contacts[change.resourceName].deleted = true;
+                    index.contacts[change.resourceName].deletedAt = new Date().toISOString();
+                }
+
+                // Remove from deleted/ folder if it was there
+                if (change.filePath.startsWith(paths.deletedDir)) {
+                    fs.unlinkSync(change.filePath);
+                }
+
+                console.log(' done');
+                successCount++;
+            }
+
+            await sleep(200);  // Be nice to the API
+        } catch (error: any) {
+            console.log(` ERROR: ${error.message}`);
+            errorCount++;
+            debugger;
+        }
+    }
+
+    // Save status with new timestamp
+    saveStatus(paths, { lastPush: new Date().toISOString() });
+    saveIndex(paths, index);
+
+    console.log(`\nPush complete: ${successCount} succeeded, ${errorCount} failed`);
+}
+
+function resolveUser(cliUser: string): string {
+    // 1. Use CLI-specified user if provided (and not 'default')
+    if (cliUser && cliUser !== 'default') {
+        const normalized = normalizeUser(cliUser);
+        const config = loadConfig();
+        config.lastUser = normalized;
+        saveConfig(config);
+        return normalized;
+    }
+
+    // 2. Use lastUser from config (already normalized)
+    const config = loadConfig();
+    if (config.lastUser) {
+        return config.lastUser;
+    }
+
+    // 3. No user - require --user on first use
+    console.error('No user specified. Use --user <name> on first run (e.g., your Gmail username).');
+    console.error('This will be remembered for future runs.');
+    process.exit(1);
+}
+
+async function main(): Promise<void> {
+    const args = process.argv.slice(2);
+    const options = parseArgs(args);
+
+    if (options.help || !options.command) {
+        showHelp();
+        return;
+    }
+
+    try {
+        const user = resolveUser(options.user);
+
+        switch (options.command) {
+            case 'sync':
+                await syncContacts(user, { full: options.full, verbose: options.verbose });
+                break;
+            case 'push':
+                await pushContacts(user, { yes: options.yes, verbose: options.verbose });
+                break;
+            default:
+                console.error(`Unknown command: ${options.command}`);
+                showHelp();
+                process.exit(1);
+        }
+
+        // Update lastUser in config
+        const config = loadConfig();
+        config.lastUser = user;
+        saveConfig(config);
+
+    } catch (error: any) {
+        console.error(`Error: ${error.message}`);
+        debugger;
+        process.exit(1);
+    }
+}
+
+if (import.meta.main) {
+    await main();
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bobfrankston/gcards",
+  "version": "0.1.0",
+  "description": "Google Contacts cleanup and management tool",
+  "type": "module",
+  "main": "gcards.ts",
+  "bin": {
+    "gcards": "gcards.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bobfrankston/gcards.git"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "prerelease:local": "git add -A && (git diff-index --quiet HEAD || git commit -m \"Pre-release commit\")",
+    "preversion": "npm run check && git add -A",
+    "postversion": "git push && git push --tags",
+    "release": "npm run prerelease:local && npm version patch && npm publish --access public"
+  },
+  "keywords": [
+    "google",
+    "contacts",
+    "cleanup",
+    "oauth"
+  ],
+  "author": "Bob Frankston",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.1"
+  },
+  "dependencies": {
+    "@bobfrankston/miscassists": "file:../../../projects/NodeJS/miscassists"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "strictNullChecks": false,
+    "noImplicitAny": true,
+    "noImplicitReturns": false,
+    "noImplicitThis": true,
+    "newLine": "lf"
+  },
+  "exclude": [
+    "node_modules",
+    "cruft",
+    ".git",
+    "tests",
+    "prev"
+  ]
+}

package/types.ts

@@ -0,0 +1,305 @@
+/**
+ * Google People API Type Definitions
+ * Reference: https://developers.google.com/people/api/rest/v1/people
+ */
+
+// ============================================================
+// Google People API Response Types (from API)
+// ============================================================
+
+export interface GooglePersonMetadata {
+    sources?: Array<{
+        type: string;              // "CONTACT", "PROFILE", "DOMAIN_PROFILE"
+        id: string;
+        etag?: string;
+        updateTime?: string;
+    }>;
+    previousResourceNames?: string[];
+    linkedPeopleResourceNames?: string[];
+    deleted?: boolean;
+}
+
+export interface GoogleName {
+    metadata?: FieldMetadata;
+    displayName?: string;
+    displayNameLastFirst?: string;
+    familyName?: string;
+    givenName?: string;
+    middleName?: string;
+    honorificPrefix?: string;
+    honorificSuffix?: string;
+    phoneticFullName?: string;
+    phoneticFamilyName?: string;
+    phoneticGivenName?: string;
+    phoneticMiddleName?: string;
+    phoneticHonorificPrefix?: string;
+    phoneticHonorificSuffix?: string;
+    unstructuredName?: string;
+}
+
+export interface GoogleNickname {
+    metadata?: FieldMetadata;
+    value?: string;
+    type?: string;  // "DEFAULT", "MAIDEN_NAME", "INITIALS", etc.
+}
+
+export interface GoogleEmailAddress {
+    metadata?: FieldMetadata;
+    value?: string;
+    type?: string;           // "home", "work", "other"
+    formattedType?: string;
+    displayName?: string;
+}
+
+export interface GooglePhoneNumber {
+    metadata?: FieldMetadata;
+    value?: string;
+    canonicalForm?: string;  // E.164 format
+    type?: string;           // "home", "work", "mobile", etc.
+    formattedType?: string;
+}
+
+export interface GoogleAddress {
+    metadata?: FieldMetadata;
+    formattedValue?: string;
+    type?: string;
+    formattedType?: string;
+    poBox?: string;
+    streetAddress?: string;
+    extendedAddress?: string;
+    city?: string;
+    region?: string;
+    postalCode?: string;
+    country?: string;
+    countryCode?: string;
+}
+
+export interface GoogleOrganization {
+    metadata?: FieldMetadata;
+    type?: string;
+    formattedType?: string;
+    name?: string;
+    department?: string;
+    title?: string;
+    jobDescription?: string;
+    symbol?: string;
+    phoneticName?: string;
+    location?: string;
+    startDate?: GoogleDate;
+    endDate?: GoogleDate;
+    current?: boolean;
+}
+
+export interface GoogleBiography {
+    metadata?: FieldMetadata;
+    value?: string;
+    contentType?: string;  // "TEXT_PLAIN", "TEXT_HTML"
+}
+
+export interface GoogleUrl {
+    metadata?: FieldMetadata;
+    value?: string;
+    type?: string;
+    formattedType?: string;
+}
+
+export interface GooglePhoto {
+    metadata?: FieldMetadata;
+    url?: string;
+    default?: boolean;
+}
+
+export interface GoogleBirthday {
+    metadata?: FieldMetadata;
+    date?: GoogleDate;
+    text?: string;
+}
+
+export interface GoogleDate {
+    year?: number;
+    month?: number;
+    day?: number;
+}
+
+export interface GoogleEvent {
+    metadata?: FieldMetadata;
+    date?: GoogleDate;
+    type?: string;
+    formattedType?: string;
+}
+
+export interface GoogleRelation {
+    metadata?: FieldMetadata;
+    person?: string;
+    type?: string;
+    formattedType?: string;
+}
+
+export interface GoogleMembership {
+    metadata?: FieldMetadata;
+    contactGroupMembership?: {
+        contactGroupId?: string;
+        contactGroupResourceName?: string;
+    };
+    domainMembership?: {
+        inViewerDomain?: boolean;
+    };
+}
+
+export interface GoogleUserDefined {
+    metadata?: FieldMetadata;
+    key?: string;
+    value?: string;
+}
+
+export interface FieldMetadata {
+    primary?: boolean;
+    verified?: boolean;
+    source?: {
+        type: string;
+        id: string;
+    };
+    sourcePrimary?: boolean;
+}
+
+/**
+ * Full Google Person resource as returned by People API
+ */
+export interface GooglePerson {
+    resourceName: string;          // e.g., "people/c1234567890"
+    etag?: string;
+    metadata?: GooglePersonMetadata;
+    names?: GoogleName[];
+    nicknames?: GoogleNickname[];
+    photos?: GooglePhoto[];
+    birthdays?: GoogleBirthday[];
+    addresses?: GoogleAddress[];
+    emailAddresses?: GoogleEmailAddress[];
+    phoneNumbers?: GooglePhoneNumber[];
+    organizations?: GoogleOrganization[];
+    biographies?: GoogleBiography[];
+    urls?: GoogleUrl[];
+    events?: GoogleEvent[];
+    relations?: GoogleRelation[];
+    memberships?: GoogleMembership[];
+    userDefined?: GoogleUserDefined[];
+    imClients?: Array<{
+        metadata?: FieldMetadata;
+        username?: string;
+        type?: string;
+        formattedType?: string;
+        protocol?: string;
+        formattedProtocol?: string;
+    }>;
+    sipAddresses?: Array<{
+        metadata?: FieldMetadata;
+        value?: string;
+        type?: string;
+        formattedType?: string;
+    }>;
+    fileAses?: Array<{
+        metadata?: FieldMetadata;
+        value?: string;
+    }>;
+}
+
+export interface GoogleConnectionsResponse {
+    connections?: GooglePerson[];
+    nextPageToken?: string;
+    nextSyncToken?: string;
+    totalPeople?: number;
+    totalItems?: number;
+}
+
+// ============================================================
+// Local Simplified Format (for analysis/cleanup)
+// ============================================================
+
+export interface LocalContact {
+    // Identity & reconciliation
+    resourceName: string;          // From Google - used for updates
+    etag?: string;                 // For conflict detection
+
+    // Core identity
+    displayName: string;
+    givenName?: string;
+    familyName?: string;
+    nickname?: string;
+
+    // Contact info (flattened, typed arrays)
+    emails: Array<{ value: string; type?: string; primary?: boolean }>;
+    phones: Array<{ value: string; type?: string; primary?: boolean }>;
+    addresses: Array<{
+        formatted?: string;
+        street?: string;
+        city?: string;
+        region?: string;
+        postalCode?: string;
+        country?: string;
+        type?: string;
+    }>;
+
+    // Professional
+    organizations: Array<{
+        name?: string;
+        title?: string;
+        department?: string;
+    }>;
+
+    // Social/web
+    urls: Array<{ value: string; type?: string }>;
+
+    // Dates
+    birthday?: { year?: number; month?: number; day?: number };
+
+    // Notes
+    notes?: string;
+
+    // Groups
+    groups: string[];              // contactGroupResourceNames
+
+    // Metadata for cleanup
+    _meta: {
+        sourceType: string;        // "CONTACT", "PROFILE", etc.
+        updateTime?: string;
+        isTestEntry?: boolean;     // Flagged as test (m-XXXX@bob.ma pattern)
+        duplicateOf?: string[];    // resourceNames of potential duplicates
+        mergeConfidence?: number;  // 0-1 confidence for merge candidates
+    };
+}
+
+// ============================================================
+// Cleanup Analysis Types
+// ============================================================
+
+export interface DuplicateGroup {
+    primary: string;               // resourceName of "best" contact
+    duplicates: string[];          // resourceNames to merge into primary
+    confidence: number;            // 0-1 merge confidence
+    matchReasons: string[];        // Why these are considered duplicates
+}
+
+export interface CleanupReport {
+    totalContacts: number;
+    testEntries: LocalContact[];   // To be deleted
+    duplicateGroups: DuplicateGroup[];
+    emptyContacts: LocalContact[]; // No useful info
+    suggestions: string[];         // Human-readable recommendations
+}
+
+// ============================================================
+// Deletion Logging (for tracking cleanup history)
+// ============================================================
+
+export interface DeletionRecord {
+    resourceName: string;
+    displayName: string;
+    reason: string;                // "test_entry", "duplicate_of:people/cXXX", "empty", etc.
+    deletedAt: string;             // ISO timestamp
+    originalData: LocalContact;    // Snapshot before deletion
+}
+
+export interface DeletionLog {
+    deletions: DeletionRecord[];
+    lastUpdated: string;           // ISO timestamp
+}