@bobfrankston/gcards 0.1.0 → 0.1.4

package/glib/gctypes.ts

@@ -0,0 +1,110 @@
+/**
+ * gcards Type Definitions
+ * Types for gcards index, config, and related structures
+ * Other tools can import these to work with gcards data
+ */
+
+// Re-export Google types for convenience
+export * from './types.ts';
+
+// ============================================================
+// gcards Configuration
+// ============================================================
+
+export interface GcardsConfig {
+    lastUser?: string;
+}
+
+// ============================================================
+// Contact Index (index.json)
+// ============================================================
+
+export interface ContactIndex {
+    contacts: Record<string, IndexEntry>;  /** resourceName -> entry */
+    lastSync: string;
+    syncToken?: string;
+}
+
+export interface IndexEntry {
+    resourceName: string;
+    displayName: string;
+    etag?: string;
+    deleted: boolean;      /** Google deleted this contact */
+    deletedAt?: string;
+    updatedAt: string;
+    _delete?: boolean;     /** Request to delete on next push */
+    guids?: string[];      /** User-defined GUIDs for cross-account tracking */
+}
+
+// ============================================================
+// Push Status (status.json)
+// ============================================================
+
+export interface PushStatus {
+    lastPush: string;  /** ISO timestamp of last push */
+}
+
+// ============================================================
+// Sync Token (sync-token.json)
+// ============================================================
+
+export interface SyncTokenData {
+    syncToken: string;
+    savedAt: string;
+}
+
+// ============================================================
+// Pending Changes (for push operations)
+// ============================================================
+
+export interface PendingChange {
+    type: 'update' | 'delete' | 'add';
+    resourceName: string;
+    displayName: string;
+    filePath: string;
+}
+
+// ============================================================
+// User Paths
+// ============================================================
+
+export interface UserPaths {
+    userDir: string;
+    contactsDir: string;       /** Active contacts synced from Google */
+    deletedDir: string;        /** Google-deleted tombstones */
+    toDeleteDir: string;       /** User requests to delete */
+    toAddDir: string;          /** User requests to add new contacts */
+    fixLogDir: string;         /** Logs from gfix operations */
+    indexFile: string;
+    deletedFile: string;       /** Deleted contacts index (deleted.json) */
+    statusFile: string;
+    syncTokenFile: string;
+    tokenFile: string;
+    tokenWriteFile: string;
+}
+
+// ============================================================
+// Extended Contact (with gcards-specific fields)
+// ============================================================
+
+import type { GooglePerson } from './types.ts';
+
+/** GooglePerson with optional gcards deletion marker */
+export interface GcardsContact extends GooglePerson {
+    _deleted?: boolean;  /** Mark for deletion in contact JSON */
+}
+
+// ============================================================
+// Helper: GUID in userDefined
+// ============================================================
+
+/** Standard key for gcards GUIDs in userDefined */
+export const GCARDS_GUID_KEY = 'gcards_guid';
+
+/** Extract gcards GUIDs from a contact's userDefined fields */
+export function extractGuids(contact: GooglePerson): string[] {
+    return contact.userDefined
+        ?.filter(u => u.key === GCARDS_GUID_KEY)
+        .map(u => u.value || '')
+        .filter(v => v) || [];
+}

package/glib/gmerge.ts

@@ -0,0 +1,290 @@
+/**
+ * gmerge - Contact merge utilities
+ * Merges multiple Google contacts into one
+ */
+
+import type {
+    GooglePerson,
+    GoogleEmailAddress,
+    GooglePhoneNumber,
+    GoogleAddress,
+    GoogleOrganization,
+    GoogleUrl,
+    GoogleMembership,
+    GoogleBiography,
+    GooglePhoto,
+    GoogleUserDefined
+} from './types.ts';
+
+export interface MergeEntry {
+    name: string;
+    emails: string[];
+    resourceNames: string[];
+    _delete?: boolean;
+}
+
+/**
+ * Normalize email for deduplication
+ */
+function normalizeEmail(email: string | undefined): string {
+    return (email || '').toLowerCase().trim();
+}
+
+/**
+ * Normalize phone for deduplication (digits only)
+ */
+function normalizePhone(phone: string | undefined): string {
+    return (phone || '').replace(/\D/g, '');
+}
+
+/**
+ * Normalize address for deduplication
+ */
+function normalizeAddress(addr: GoogleAddress): string {
+    return (addr.formattedValue || '').toLowerCase().trim();
+}
+
+/**
+ * Normalize organization for deduplication
+ */
+function normalizeOrg(org: GoogleOrganization): string {
+    return `${(org.name || '').toLowerCase()}|${(org.title || '').toLowerCase()}`.trim();
+}
+
+/**
+ * Normalize URL for deduplication
+ */
+function normalizeUrl(url: string | undefined): string {
+    return (url || '').toLowerCase().replace(/\/+$/, '').trim();
+}
+
+/**
+ * Get membership group resource name for deduplication
+ */
+function getMembershipKey(m: GoogleMembership): string {
+    return m.contactGroupMembership?.contactGroupResourceName || '';
+}
+
+/**
+ * Union arrays with deduplication
+ */
+function unionEmails(target: GoogleEmailAddress[], source: GoogleEmailAddress[]): GoogleEmailAddress[] {
+    const seen = new Set<string>();
+    const result: GoogleEmailAddress[] = [];
+    for (const e of [...target, ...source]) {
+        const key = normalizeEmail(e.value);
+        if (key && !seen.has(key)) {
+            seen.add(key);
+            result.push(e);
+        }
+    }
+    return result;
+}
+
+function unionPhones(target: GooglePhoneNumber[], source: GooglePhoneNumber[]): GooglePhoneNumber[] {
+    const seen = new Set<string>();
+    const result: GooglePhoneNumber[] = [];
+    for (const p of [...target, ...source]) {
+        const key = normalizePhone(p.value || p.canonicalForm);
+        if (key && !seen.has(key)) {
+            seen.add(key);
+            result.push(p);
+        }
+    }
+    return result;
+}
+
+function unionAddresses(target: GoogleAddress[], source: GoogleAddress[]): GoogleAddress[] {
+    const seen = new Set<string>();
+    const result: GoogleAddress[] = [];
+    for (const a of [...target, ...source]) {
+        const key = normalizeAddress(a);
+        if (key && !seen.has(key)) {
+            seen.add(key);
+            result.push(a);
+        }
+    }
+    return result;
+}
+
+function unionOrganizations(target: GoogleOrganization[], source: GoogleOrganization[]): GoogleOrganization[] {
+    const seen = new Set<string>();
+    const result: GoogleOrganization[] = [];
+    for (const o of [...target, ...source]) {
+        const key = normalizeOrg(o);
+        if (key && key !== '|' && !seen.has(key)) {
+            seen.add(key);
+            result.push(o);
+        }
+    }
+    return result;
+}
+
+function unionUrls(target: GoogleUrl[], source: GoogleUrl[]): GoogleUrl[] {
+    const seen = new Set<string>();
+    const result: GoogleUrl[] = [];
+    for (const u of [...target, ...source]) {
+        const key = normalizeUrl(u.value);
+        if (key && !seen.has(key)) {
+            seen.add(key);
+            result.push(u);
+        }
+    }
+    return result;
+}
+
+function unionMemberships(target: GoogleMembership[], source: GoogleMembership[]): GoogleMembership[] {
+    const seen = new Set<string>();
+    const result: GoogleMembership[] = [];
+    for (const m of [...target, ...source]) {
+        const key = getMembershipKey(m);
+        if (key && !seen.has(key)) {
+            seen.add(key);
+            result.push(m);
+        }
+    }
+    return result;
+}
+
+function unionUserDefined(target: GoogleUserDefined[], source: GoogleUserDefined[]): GoogleUserDefined[] {
+    const seen = new Set<string>();
+    const result: GoogleUserDefined[] = [];
+    for (const u of [...target, ...source]) {
+        const key = `${u.key}:${u.value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(u);
+        }
+    }
+    return result;
+}
+
+/**
+ * Concatenate biographies/notes
+ */
+function mergeBiographies(target: GoogleBiography[], source: GoogleBiography[]): GoogleBiography[] {
+    const targetText = target.map(b => b.value || '').filter(v => v).join('\n\n');
+    const sourceText = source.map(b => b.value || '').filter(v => v).join('\n\n');
+
+    if (!sourceText) return target;
+    if (!targetText) return source;
+
+    const merged = `${targetText}\n\n[Merged]:\n${sourceText}`;
+    return [{ value: merged, contentType: 'TEXT_PLAIN' }];
+}
+
+/**
+ * Merge photos - prefer custom (non-default) over default
+ */
+function mergePhotos(target: GooglePhoto[], source: GooglePhoto[]): GooglePhoto[] {
+    const targetHasCustom = target.some(p => p.default === false);
+    const sourceHasCustom = source.some(p => p.default === false);
+
+    // If source has custom and target doesn't, use source
+    if (sourceHasCustom && !targetHasCustom) {
+        return source.filter(p => p.default === false);
+    }
+
+    // Otherwise keep target
+    return target;
+}
+
+/**
+ * Merge multiple contacts into one
+ * Returns the merged contact data (without resourceName/etag - caller handles that)
+ */
+export function mergeContacts(target: GooglePerson, sources: GooglePerson[]): Partial<GooglePerson> {
+    // Start with target data
+    // Note: photos excluded - can't update via updateContact API
+    const merged: Partial<GooglePerson> = {
+        names: target.names,
+        nicknames: target.nicknames,
+        birthdays: target.birthdays,
+        addresses: target.addresses || [],
+        emailAddresses: target.emailAddresses || [],
+        phoneNumbers: target.phoneNumbers || [],
+        organizations: target.organizations || [],
+        biographies: target.biographies || [],
+        urls: target.urls || [],
+        memberships: target.memberships || [],
+        userDefined: target.userDefined || [],
+        fileAses: target.fileAses
+    };
+
+    // Merge each source
+    for (const source of sources) {
+        // Union arrays
+        merged.emailAddresses = unionEmails(merged.emailAddresses || [], source.emailAddresses || []);
+        merged.phoneNumbers = unionPhones(merged.phoneNumbers || [], source.phoneNumbers || []);
+        merged.addresses = unionAddresses(merged.addresses || [], source.addresses || []);
+        merged.organizations = unionOrganizations(merged.organizations || [], source.organizations || []);
+        merged.urls = unionUrls(merged.urls || [], source.urls || []);
+        merged.memberships = unionMemberships(merged.memberships || [], source.memberships || []);
+        merged.userDefined = unionUserDefined(merged.userDefined || [], source.userDefined || []);
+
+        // Concatenate biographies
+        merged.biographies = mergeBiographies(merged.biographies || [], source.biographies || []);
+
+        // Note: photos skipped - can't update via updateContact API
+
+        // Use name if target is empty
+        if (!merged.names?.length && source.names?.length) {
+            merged.names = source.names;
+        }
+
+        // Merge birthdays (keep first non-empty)
+        if (!merged.birthdays?.length && source.birthdays?.length) {
+            merged.birthdays = source.birthdays;
+        }
+
+        // Merge events, relations (union would be complex, just keep target for now)
+        // These are less common fields
+    }
+
+    return merged;
+}
+
+/**
+ * Photo entry for photos.json - preserves photos from deleted contacts
+ */
+export interface PhotoEntry {
+    contactId: string;      // resourceName of surviving contact
+    name: string;           // display name
+    photos: string[];       // URLs from deleted contacts
+}
+
+/**
+ * Collect photo URLs from source contacts being deleted
+ * Returns URLs of non-default (custom) photos only
+ */
+export function collectSourcePhotos(sources: GooglePerson[]): string[] {
+    const urls: string[] = [];
+    for (const source of sources) {
+        for (const photo of source.photos || []) {
+            // Only collect custom photos (default: false means custom)
+            if (photo.url && photo.default === false) {
+                urls.push(photo.url);
+            }
+        }
+    }
+    return urls;
+}
+
+/**
+ * Fields mask for update - all fields we might have modified
+ * Note: photos cannot be updated via updateContact (use separate photo API)
+ */
+export const MERGE_UPDATE_MASK = [
+    'names',
+    'nicknames',
+    'birthdays',
+    'addresses',
+    'emailAddresses',
+    'phoneNumbers',
+    'organizations',
+    'biographies',
+    'urls',
+    'memberships',
+    'userDefined',
+    'fileAses'
+].join(',');

package/glib/gutils.ts

@@ -0,0 +1,141 @@
+/**
+ * Shared utilities for gcards tools
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import type { GcardsConfig, ContactIndex, UserPaths } from './gctypes.ts';
+
+export const APP_DIR = path.dirname(import.meta.dirname);  // Parent of glib/
+
+/** Get the app directory (%APPDATA%\gcards or ~/.config/gcards) */
+export function getAppDir(): string {
+    if (process.platform === 'win32') {
+        return path.join(process.env.APPDATA || os.homedir(), 'gcards');
+    }
+    return path.join(os.homedir(), '.config', 'gcards');
+}
+
+/** Get the data directory (app directory/data, or local data/ symlink for dev) */
+export function getDataDir(): string {
+    // Check for local data/ symlink first (for development)
+    // This should point to %APPDATA%\gcards\data (the data directory)
+    const localData = path.join(APP_DIR, 'data');
+    if (fs.existsSync(localData)) {
+        return localData;
+    }
+    return path.join(getAppDir(), 'data');
+}
+
+export const DATA_DIR = getDataDir();
+export const CONFIG_FILE = path.join(getAppDir(), 'config.json');
+export const CREDENTIALS_FILE = path.join(APP_DIR, 'credentials.json');
+
+export function loadConfig(): GcardsConfig {
+    if (fs.existsSync(CONFIG_FILE)) {
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    }
+    return {};
+}
+
+export function saveConfig(config: GcardsConfig): void {
+    const appDir = getAppDir();
+    if (!fs.existsSync(appDir)) {
+        fs.mkdirSync(appDir, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+export function getUserPaths(user: string): UserPaths {
+    const userDir = path.join(DATA_DIR, user);
+    return {
+        userDir,
+        contactsDir: path.join(userDir, 'contacts'),
+        deletedDir: path.join(userDir, 'deleted'),
+        toDeleteDir: path.join(userDir, '_delete'),
+        toAddDir: path.join(userDir, '_add'),
+        fixLogDir: path.join(userDir, 'fix-logs'),
+        indexFile: path.join(userDir, 'index.json'),
+        deletedFile: path.join(userDir, 'deleted.json'),
+        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')
+    };
+}
+
+export function ensureUserDir(user: string): void {
+    const paths = getUserPaths(user);
+    if (!fs.existsSync(paths.userDir)) {
+        fs.mkdirSync(paths.userDir, { recursive: true });
+    }
+}
+
+export function loadIndex(paths: UserPaths): ContactIndex {
+    if (fs.existsSync(paths.indexFile)) {
+        return JSON.parse(fs.readFileSync(paths.indexFile, 'utf-8'));
+    }
+    return { contacts: {}, lastSync: '' };
+}
+
+export function resolveUser(cliUser: string, setAsDefault = false): string {
+    // 1. Use CLI-specified user if provided (and not 'default')
+    if (cliUser && cliUser !== 'default') {
+        const normalized = normalizeUser(cliUser);
+        if (setAsDefault) {
+            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);
+}
+
+export function normalizeUser(user: string): string {
+    return user.toLowerCase().split(/[+@]/)[0].replace(/\./g, '');
+}
+
+export function getAllUsers(): string[] {
+    if (!fs.existsSync(DATA_DIR)) {
+        return [];
+    }
+    return fs.readdirSync(DATA_DIR)
+        .filter(f => {
+            const fullPath = path.join(DATA_DIR, f);
+            return fs.statSync(fullPath).isDirectory() && !f.startsWith('.');
+        });
+}
+
+/** Logger that writes to both console and a file */
+export class FileLogger {
+    private filePath: string;
+
+    constructor(filePath: string, clear = true) {
+        this.filePath = filePath;
+        if (clear && fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+
+    log(message: string): void {
+        console.log(message);
+        fs.appendFileSync(this.filePath, message + '\n');
+    }
+
+    error(message: string): void {
+        console.log(message);
+        fs.appendFileSync(this.filePath, message + '\n');
+    }
+}

package/{cli.ts → glib/parsecli.ts}

@@ -7,8 +7,10 @@ export interface CliOptions {
     user: string;   /** User profile name (default: 'default') */
     full: boolean;  /** Force full sync instead of incremental */
     yes: boolean;   /** Skip confirmation prompt */
+    all: boolean;   /** Process all users */
     help: boolean;
     verbose: boolean;
+    limit: number;  /** Process only first n entries (0 = no limit) */
 }
 
 export function parseArgs(args: string[]): CliOptions {
@@ -17,8 +19,10 @@ export function parseArgs(args: string[]): CliOptions {
         user: 'default',
         full: false,
         yes: false,
+        all: false,
         help: false,
-        verbose: false
+        verbose: false,
+        limit: 0
     };
 
     for (let i = 0; i < args.length; i++) {
@@ -31,8 +35,12 @@ export function parseArgs(args: string[]): CliOptions {
             options.help = true;
         } else if (arg === '--verbose' || arg === '-v') {
             options.verbose = true;
+        } else if (arg === '--all' || arg === '-all' || arg === '-a') {
+            options.all = true;
         } else if ((arg === '--user' || arg === '-user' || arg === '-u') && i + 1 < args.length) {
             options.user = args[++i];
+        } else if ((arg === '--limit' || arg === '-limit') && i + 1 < args.length) {
+            options.limit = parseInt(args[++i], 10) || 0;
         } else if (!arg.startsWith('-') && !options.command) {
             options.command = arg;
         }
@@ -41,6 +49,19 @@ export function parseArgs(args: string[]): CliOptions {
     return options;
 }
 
+export function showUsage(): void {
+    console.log(`
+gcards - Google Contacts management tool
+
+Usage: gcards <command> [options]
+
+Commands: sync, push
+Options:  -u <user>, -a (all), -f (full), -y (yes), -v (verbose), -limit <n>
+
+Use --help or -h for detailed help including deletion instructions.
+`);
+}
+
 export function showHelp(): void {
     console.log(`
 gcards - Google Contacts management tool
@@ -52,22 +73,37 @@ Commands:
     push        Push local changes to Google (with confirmation)
 
 Options:
-    --user, -u NAME User profile (default: 'default')
+    --user, -u NAME User profile (required on first run)
+    --all, -a       Process all users
     --full, -f      Force full sync (ignore sync token)
     --yes, -y       Skip confirmation prompt
     --verbose, -v   Verbose output
+    --limit, -limit N  Process only first N entries (for debugging)
     --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
+    - In index.json, add "_delete": true to the contact's entry
+    - In the contact's JSON, add "_deleted": true
+    - Or move the JSON file to the <user>/_delete/ folder
     Then run 'gcards push' to apply the deletion
 
+Folders:
+    contacts/   Active contacts synced from Google
+    deleted/    Tombstones (contacts Google has deleted)
+    _delete/    Contacts you want to delete (pending push)
+    _add/       New contacts to create (pending push)
+
 Examples:
-    gcards sync                    # Sync default user
+    gcards sync                    # Sync with last used 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
+
+Workflow for merging duplicates:
+    gfix undup -u bob              # Detect duplicates -> merger.json
+    (edit merger.json to add _delete for unwanted contacts)
+    gfix merge -u bob              # Apply merge locally
+    gcards push -u bob             # Push changes to Google
 `);
 }