@bobfrankston/gcards 0.1.11 → 0.1.13

package/README.md

@@ -242,11 +242,36 @@ After export, run `gcards push -u <target>` to upload.
 
 ## Setup
 
+### Google API Setup
+
 1. Create Google Cloud project
 2. Enable People API
 3. Create OAuth2 credentials (Desktop app type)
 4. Download `credentials.json` to the gcards directory
 
+### AI Error Explanations (Optional)
+
+When API errors occur, gcards can use AI to explain what went wrong and suggest fixes.
+
+1. Create `keys.env` in your gcards app directory:
+   - **Windows**: `%APPDATA%\gcards\keys.env`
+   - **Linux/Mac**: `~/.config/gcards/keys.env`
+
+2. Add your API key(s):
+   ```
+   ANTHROPIC_API_KEY=sk-ant-api03-...
+   ```
+   or
+   ```
+   OPENAI_API_KEY=sk-...
+   ```
+
+**Get API keys:**
+- Anthropic: https://console.anthropic.com/settings/keys
+- OpenAI: https://platform.openai.com/api-keys
+
+The tool tries Anthropic first, then falls back to OpenAI if available.
+
 ## License
 
 MIT

package/gcards.ts

@@ -14,7 +14,7 @@ import type { GooglePerson, GoogleConnectionsResponse } from './glib/types.ts';
 import { GCARDS_GUID_KEY, extractGuids } from './glib/gctypes.ts';
 import type { ContactIndex, IndexEntry, DeletedEntry, DeleteQueue, DeleteQueueEntry, PushStatus, PendingChange, UserPaths } from './glib/gctypes.ts';
 import { DATA_DIR, CREDENTIALS_FILE, loadConfig, saveConfig, getUserPaths, ensureUserDir, loadIndex, normalizeUser, getAllUsers, resolveUser, FileLogger } from './glib/gutils.ts';
-import { explainApiError, isAIAvailable } from './glib/aihelper.ts';
+import { explainApiError, isAIAvailable, showAISetupHint } from './glib/aihelper.ts';
 
 const PEOPLE_API_BASE = 'https://people.googleapis.com/v1';
 const CONTACTS_SCOPE_READ = 'https://www.googleapis.com/auth/contacts.readonly';
@@ -77,6 +77,7 @@ function cleanupEscapeHandler(): void {
     if (process.stdin.isTTY) {
         process.stdin.setRawMode(false);
         process.stdin.pause();
+        process.stdin.removeAllListeners('data');
     }
 }
 
@@ -124,11 +125,24 @@ async function refreshAccessToken(): Promise<string> {
     return currentAccessToken;
 }
 
+/** Get sort key from contact: fileAs > displayNameLastFirst > displayName */
+function getSortKey(person: GooglePerson): string {
+    const fileAs = person.fileAses?.[0]?.value;
+    if (fileAs) return fileAs;
+    const name = person.names?.[0];
+    if (name?.displayNameLastFirst) return name.displayNameLastFirst;
+    return name?.displayName || '';
+}
+
 function saveIndex(paths: UserPaths, index: ContactIndex): void {
-    // Sort contacts by displayName for convenience
+    // Sort contacts by sortKey (fileAs > displayNameLastFirst > displayName)
     const sortedContacts: Record<string, IndexEntry> = {};
     const entries = Object.entries(index.contacts);
-    entries.sort((a, b) => a[1].displayName.localeCompare(b[1].displayName));
+    entries.sort((a, b) => {
+        const keyA = a[1].sortKey || a[1].displayName || '';
+        const keyB = b[1].sortKey || b[1].displayName || '';
+        return keyA.localeCompare(keyB);
+    });
     for (const [key, value] of entries) {
         sortedContacts[key] = value;
     }
@@ -452,10 +466,12 @@ async function syncContacts(user: string, options: { full: boolean; verbose: boo
                     // Preserve _delete flag from existing entry
                     const existingDelete = index.contacts[person.resourceName]?._delete;
 
+                    const sortKey = getSortKey(person);
                     index.contacts[person.resourceName] = {
                         resourceName: person.resourceName,
                         displayName,
                         updatedAt: new Date().toISOString(),
+                        sortKey,
                         ...(hasPhoto && { hasPhoto }),
                         ...(starred && { starred }),
                         ...(guids.length > 0 && { guids }),
@@ -912,10 +928,12 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
                 const starred = isStarred(created);
 
                 // Add to index
+                const sortKey = getSortKey(created);
                 index.contacts[created.resourceName] = {
                     resourceName: created.resourceName,
                     displayName: change.displayName,
                     updatedAt: new Date().toISOString(),
+                    sortKey,
                     ...(hasPhoto && { hasPhoto }),
                     ...(starred && { starred }),
                     ...(guids.length > 0 && { guids })
@@ -1036,23 +1054,27 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
             errorCount++;
 
             // Get AI explanation if available and error is from API
-            if (error instanceof ApiError && error.payload && isAIAvailable()) {
-                try {
-                    const explanation = await explainApiError(error.message, error.payload);
-                    if (explanation) {
-                        console.log(`\n    AI Analysis:`);
-                        if (explanation.explanation) {
-                            console.log(`      Problem: ${explanation.explanation}`);
-                        }
-                        if (explanation.suggestedFix) {
-                            console.log(`      Fix: ${explanation.suggestedFix}`);
-                        }
-                        if (explanation.correctedJson) {
-                            console.log(`      Corrected JSON:\n${explanation.correctedJson.split('\n').map(l => '        ' + l).join('\n')}`);
+            if (error instanceof ApiError && error.payload) {
+                if (isAIAvailable()) {
+                    try {
+                        const explanation = await explainApiError(error.message, error.payload);
+                        if (explanation) {
+                            console.log(`\n    AI Analysis:`);
+                            if (explanation.explanation) {
+                                console.log(`      Problem: ${explanation.explanation}`);
+                            }
+                            if (explanation.suggestedFix) {
+                                console.log(`      Fix: ${explanation.suggestedFix}`);
+                            }
+                            if (explanation.correctedJson) {
+                                console.log(`      Corrected JSON:\n${explanation.correctedJson.split('\n').map(l => '        ' + l).join('\n')}`);
+                            }
+                            problems.push(`  AI: ${explanation.explanation || ''} Fix: ${explanation.suggestedFix || ''}`);
                         }
-                        problems.push(`  AI: ${explanation.explanation || ''} Fix: ${explanation.suggestedFix || ''}`);
-                    }
-                } catch { /* ignore AI errors */ }
+                    } catch { /* ignore AI errors */ }
+                } else {
+                    showAISetupHint();
+                }
             }
         }
     }

package/gfix.ts

@@ -1898,12 +1898,12 @@ async function main(): Promise<void> {
             console.error('Usage: gfix export -u <source> -to <target> <pattern>');
             process.exit(1);
         }
-        const resolvedSource = resolveUser(user);
+        const resolvedSource = resolveUser(user, true);
         await runExport(resolvedSource, targetUser, positionalArgs[0]);
         return;
     }
 
-    const resolvedUser = resolveUser(user);
+    const resolvedUser = resolveUser(user, true);
 
     if (processLimit > 0) {
         console.log(`[DEBUG] Processing limited to first ${processLimit} contacts\n`);

package/glib/aihelper.ts

@@ -194,3 +194,22 @@ export async function explainApiError(errorMessage: string, payload: unknown): P
 export function isAIAvailable(): boolean {
     return !!(process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY);
 }
+
+/**
+ * Get the expected keys.env path for the current platform
+ */
+export function getKeysEnvPath(): string {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const appData = process.env.APPDATA || path.join(home, '.config');
+    return path.join(appData, 'gcards', 'keys.env');
+}
+
+/**
+ * Show instructions for setting up AI keys (call when AI could have helped but wasn't available)
+ */
+export function showAISetupHint(): void {
+    const keysPath = getKeysEnvPath();
+    console.log(`\n    Tip: Enable AI error explanations by creating ${keysPath}`);
+    console.log(`    Add: ANTHROPIC_API_KEY=sk-ant-... or OPENAI_API_KEY=sk-...`);
+    console.log(`    See README.md for details.`);
+}

package/glib/gctypes.ts

@@ -29,6 +29,7 @@ export interface IndexEntry {
     resourceName: string;
     displayName: string;
     updatedAt: string;
+    sortKey?: string;      /** Sort key: fileAs, displayNameLastFirst, or displayName */
     hasPhoto?: boolean;    /** Has non-default photo */
     starred?: boolean;     /** In starred/favorites group */
     _delete?: string;      /** Deletion reason. *prefix means skipped (e.g., *photo, *starred) */

package/glib/gutils.ts

@@ -125,9 +125,23 @@ export function resolveUser(cliUser: string, setAsDefault = false): string {
         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.');
+    // 3. Auto-detect if only one user exists
+    const allUsers = getAllUsers();
+    if (allUsers.length === 1) {
+        const onlyUser = allUsers[0];
+        console.log(`Auto-selected only user: ${onlyUser}`);
+        config.lastUser = onlyUser;
+        saveConfig(config);
+        return onlyUser;
+    }
+
+    // 4. No user - require --user on first use
+    if (allUsers.length > 1) {
+        console.error(`Multiple users exist: ${allUsers.join(', ')}`);
+        console.error('Use -u <name> to select one.');
+    } else {
+        console.error('No user specified. Use -u <email> on first run (e.g., your Gmail address).');
+    }
     process.exit(1);
 }
 

package/package.json

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