@masslessai/push-todo 3.0.0 → 3.2.0

package/lib/fetch.js

@@ -148,6 +148,20 @@ export async function showTask(displayNumber, options = {}) {
   console.log(formatTaskForDisplay(decrypted));
 }
 
+/**
+ * Get a task by display number (for programmatic use).
+ *
+ * @param {number} displayNumber - The task's display number
+ * @returns {Promise<Object|null>} The task object or null if not found
+ */
+export async function getTaskByNumber(displayNumber) {
+  const task = await api.fetchTaskByNumber(displayNumber);
+  if (!task) {
+    return null;
+  }
+  return decryptTaskFields(task);
+}
+
 /**
  * Mark a task as completed.
  *
@@ -280,7 +294,8 @@ export async function showStatus(options = {}) {
 
   // API
   if (status.api.valid) {
-    console.log(`${bold('API:')} ${green('Connected')} (${status.api.email})`);
+    const emailPart = status.api.email ? ` (${status.api.email})` : '';
+    console.log(`${bold('API:')} ${green('Connected')}${emailPart}`);
   } else {
     console.log(`${bold('API:')} ${red('Not connected')} - run "push-todo connect"`);
   }

package/lib/utils/git.js

@@ -147,3 +147,46 @@ export function hasUncommittedChanges() {
     return false;
   }
 }
+
+/**
+ * Normalize a git remote URL to a consistent format.
+ *
+ * Converts various URL formats to: host/owner/repo
+ * - git@github.com:user/repo.git → github.com/user/repo
+ * - https://github.com/user/repo.git → github.com/user/repo
+ * - ssh://git@github.com/user/repo → github.com/user/repo
+ *
+ * @param {string} url - The git remote URL to normalize
+ * @returns {string} Normalized URL
+ */
+export function normalizeGitRemote(url) {
+  if (!url) return url;
+
+  let normalized = url.trim();
+
+  // Remove protocol prefixes
+  const prefixes = ['https://', 'http://', 'git@', 'ssh://git@', 'ssh://'];
+  for (const prefix of prefixes) {
+    if (normalized.startsWith(prefix)) {
+      normalized = normalized.slice(prefix.length);
+      break;
+    }
+  }
+
+  // Convert : to / (for git@ style URLs like git@github.com:user/repo)
+  if (normalized.includes(':') && !normalized.includes('://')) {
+    normalized = normalized.replace(':', '/');
+  }
+
+  // Remove .git suffix
+  if (normalized.endsWith('.git')) {
+    normalized = normalized.slice(0, -4);
+  }
+
+  // Remove trailing slash
+  if (normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}

package/lib/utils/screenshots.js

@@ -0,0 +1,65 @@
+/**
+ * Screenshot utilities for Push CLI.
+ *
+ * Screenshots are stored in iCloud Drive and can be opened via the default image viewer.
+ */
+
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+import { spawn } from 'child_process';
+
+const SCREENSHOTS_DIR = join(
+  homedir(),
+  'Library/Mobile Documents/iCloud~ai~massless~push/Documents/Screenshots'
+);
+
+/**
+ * Get the full path to a screenshot file in iCloud Drive.
+ *
+ * @param {string} filename - Screenshot filename (e.g., "ABC-123.heic")
+ * @returns {string} Full path to screenshot file
+ */
+export function getScreenshotPath(filename) {
+  return join(SCREENSHOTS_DIR, filename);
+}
+
+/**
+ * Check if screenshot file exists in iCloud Drive.
+ *
+ * @param {string} filename - Screenshot filename
+ * @returns {boolean} True if file exists
+ */
+export function screenshotExists(filename) {
+  return existsSync(getScreenshotPath(filename));
+}
+
+/**
+ * Open screenshot file in default image viewer.
+ *
+ * @param {string} filepath - Full path to screenshot file
+ * @returns {Promise<void>}
+ */
+export function openScreenshot(filepath) {
+  return new Promise((resolve, reject) => {
+    if (!existsSync(filepath)) {
+      reject(new Error(`Screenshot not found: ${filepath}`));
+      return;
+    }
+
+    // Use macOS 'open' command
+    const child = spawn('open', [filepath], {
+      stdio: 'inherit'
+    });
+
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        console.log(`Opened screenshot: ${basename(filepath)}`);
+        resolve();
+      } else {
+        reject(new Error(`Failed to open screenshot (exit code: ${code})`));
+      }
+    });
+  });
+}

package/lib/watch.js

@@ -265,6 +265,7 @@ function outputPlainText() {
  *
  * @param {Object} options - Watch options
  * @param {boolean} options.json - Output JSON instead of TUI
+ * @param {boolean} options.follow - Exit when all tasks complete
  */
 export function startWatch(options = {}) {
   // JSON mode
@@ -281,6 +282,7 @@ export function startWatch(options = {}) {
 
   // Live TUI mode
   let running = true;
+  const followMode = options.follow || options.f;
 
   // Hide cursor
   process.stdout.write(codes.hideCursor);
@@ -290,6 +292,15 @@ export function startWatch(options = {}) {
     const status = readStatus();
     const output = formatUI(status);
     process.stdout.write(codes.clearScreen + codes.cursorHome + output);
+
+    // In follow mode, exit when no running or queued tasks
+    if (followMode && status) {
+      const runningTasks = status.runningTasks || [];
+      const queuedTasks = status.queuedTasks || [];
+      if (runningTasks.length === 0 && queuedTasks.length === 0) {
+        cleanup('All tasks completed.');
+      }
+    }
   }
 
   // Initial render
@@ -310,7 +321,7 @@ export function startWatch(options = {}) {
   }
 
   // Cleanup function
-  function cleanup() {
+  function cleanup(message = 'Watch mode ended.') {
     running = false;
     clearInterval(interval);
 
@@ -319,7 +330,7 @@ export function startWatch(options = {}) {
 
     // Clear screen and show exit message
     process.stdout.write(codes.clearScreen + codes.cursorHome);
-    console.log('Watch mode ended.');
+    console.log(message);
 
     if (process.stdin.isTTY) {
       process.stdin.setRawMode(false);

package/natives/KeychainHelper.swift

@@ -1,134 +1,351 @@
 #!/usr/bin/env swift
-/**
- * Push Keychain Helper
- *
- * Retrieves the E2EE encryption key from iCloud Keychain.
- * Used by the push-todo CLI for decrypting end-to-end encrypted tasks.
- *
- * Exit codes:
- *   0 - Success (key printed to stdout as base64)
- *   1 - Key not found in Keychain
- *   2 - iCloud Keychain not available
- *   3 - Other error
- *
- * Build:
- *   swiftc -O KeychainHelper.swift -o push-keychain-helper
- */
+//
+//  KeychainHelper.swift
+//  push-todo CLI
+//
+//  Created on 2026-01-29.
+//
+//  Reads the Push encryption key from iCloud Keychain.
+//  This helper is called by the Python CLI to decrypt encrypted todos.
+//
+//  COMPILE:
+//    swiftc -O KeychainHelper.swift -o push-keychain-helper
+//
+//  USAGE:
+//    ./push-keychain-helper           # Outputs base64-encoded key
+//    ./push-keychain-helper --check   # Exits 0 if key exists, 1 if not
+//    ./push-keychain-helper --version # Print version
+//
+//  EXIT CODES:
+//    0 = Success
+//    1 = Key not found
+//    2 = iCloud Keychain not available
+//    3 = Other error
+//
+//  CRITICAL: These values MUST match the iOS EncryptionService exactly:
+//    - Service: "ai.massless.push.encryption"
+//    - Account: "data-encryption-key"
+//    - Synchronizable: true (iCloud Keychain)
+//    - NO access group (allows CLI to read)
+//
+//  See: /docs/20260126_e2ee_cli_implementation_analysis.md
+//
 
 import Foundation
 import Security
 
-/// Keychain service and account identifiers
-/// Must match the iOS app's keychain storage
-let keychainService = "ai.massless.push.e2ee"
-let keychainAccount = "encryption-key"
+// MARK: - Constants
 
-/// Query the keychain for the E2EE encryption key
-func getEncryptionKey() -> (Data?, OSStatus) {
-    let query: [String: Any] = [
+/// Version of this helper (for update checks)
+let VERSION = "1.0.1"
+
+/// Keychain service - MUST match iOS EncryptionService
+let KEYCHAIN_SERVICE = "ai.massless.push.encryption"
+
+/// Keychain account - MUST match iOS EncryptionService
+let KEYCHAIN_ACCOUNT = "data-encryption-key"
+
+// MARK: - Debug
+
+var debugMode = false
+
+func debug(_ message: String) {
+    // Always write to file for debugging hangs
+    let logPath = "/tmp/push-keychain-helper.log"
+    let entry = "[DEBUG] \(message)\n"
+    if let data = entry.data(using: .utf8) {
+        if FileManager.default.fileExists(atPath: logPath) {
+            if let handle = FileHandle(forWritingAtPath: logPath) {
+                handle.seekToEndOfFile()
+                handle.write(data)
+                handle.closeFile()
+            }
+        } else {
+            FileManager.default.createFile(atPath: logPath, contents: data)
+        }
+    }
+    if debugMode {
+        fputs("[DEBUG] \(message)\n", stderr)
+    }
+}
+
+// MARK: - Exit Codes
+
+enum ExitCode: Int32 {
+    case success = 0
+    case keyNotFound = 1
+    case iCloudNotAvailable = 2
+    case otherError = 3
+}
+
+// MARK: - Keychain Functions
+
+/// Read the encryption key from iCloud Keychain.
+///
+/// - Returns: The key data, or nil if not found.
+func readEncryptionKey() -> Data? {
+    debug("Building keychain query...")
+    debug("  Service: \(KEYCHAIN_SERVICE)")
+    debug("  Account: \(KEYCHAIN_ACCOUNT)")
+    debug("  Synchronizable: any (prefer synced)")
+
+    // First try iCloud-synced key
+    let syncQuery: [String: Any] = [
         kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: keychainService,
-        kSecAttrAccount as String: keychainAccount,
-        kSecAttrSynchronizable as String: kCFBooleanTrue!,  // iCloud Keychain
-        kSecReturnData as String: kCFBooleanTrue!,
+        kSecAttrService as String: KEYCHAIN_SERVICE,
+        kSecAttrAccount as String: KEYCHAIN_ACCOUNT,
+        kSecAttrSynchronizable as String: true,
+        kSecReturnData as String: true,
         kSecMatchLimit as String: kSecMatchLimitOne
     ]
 
+    debug("Trying iCloud-synced key first...")
     var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    var status = SecItemCopyMatching(syncQuery as CFDictionary, &result)
+    debug("Synced query returned: \(status)")
 
-    if status == errSecSuccess, let data = result as? Data {
-        return (data, status)
+    // If not found, try local key (fallback for testing or manual import)
+    if status == errSecItemNotFound {
+        debug("Synced key not found, trying local key...")
+        let localQuery: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: KEYCHAIN_SERVICE,
+            kSecAttrAccount as String: KEYCHAIN_ACCOUNT,
+            kSecAttrSynchronizable as String: false,
+            kSecReturnData as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne
+        ]
+        result = nil
+        status = SecItemCopyMatching(localQuery as CFDictionary, &result)
+        debug("Local query returned: \(status)")
     }
 
-    return (nil, status)
+    switch status {
+    case errSecSuccess:
+        debug("Success! Got key data.")
+        return result as? Data
+
+    case errSecItemNotFound:
+        debug("Key not found in keychain.")
+        return nil
+
+    case errSecNotAvailable:
+        // iCloud Keychain not available
+        debug("iCloud Keychain not available (errSecNotAvailable)")
+        fputs("Error: iCloud Keychain is not available on this Mac.\n", stderr)
+        fputs("Make sure you're signed into iCloud and have Keychain enabled.\n", stderr)
+        exit(ExitCode.iCloudNotAvailable.rawValue)
+
+    case -34018: // errSecMissingEntitlement
+        debug("Missing entitlement (errSecMissingEntitlement)")
+        fputs("Error: Missing keychain entitlement. The helper may need to be properly signed.\n", stderr)
+        exit(ExitCode.otherError.rawValue)
+
+    default:
+        debug("Query failed with status: \(status)")
+        fputs("Error: Keychain query failed with status \(status)\n", stderr)
+        exit(ExitCode.otherError.rawValue)
+    }
 }
 
-/// Check if iCloud Keychain is available
-func isICloudKeychainAvailable() -> Bool {
-    // Try to query for any iCloud synced item
-    let query: [String: Any] = [
+/// Check if the encryption key exists (either synced or local).
+///
+/// - Returns: true if the key exists, false otherwise.
+func keyExists() -> Bool {
+    debug("Checking if key exists...")
+
+    // First check iCloud-synced key
+    let syncQuery: [String: Any] = [
         kSecClass as String: kSecClassGenericPassword,
-        kSecAttrSynchronizable as String: kCFBooleanTrue!,
-        kSecMatchLimit as String: kSecMatchLimitOne,
-        kSecReturnAttributes as String: kCFBooleanTrue!
+        kSecAttrService as String: KEYCHAIN_SERVICE,
+        kSecAttrAccount as String: KEYCHAIN_ACCOUNT,
+        kSecAttrSynchronizable as String: true,
+        kSecReturnData as String: false
     ]
 
+    debug("Checking synced key...")
     var result: AnyObject?
-    let status = SecItemCopyMatching(query as CFDictionary, &result)
+    var status = SecItemCopyMatching(syncQuery as CFDictionary, &result)
+    debug("Synced check returned: \(status)")
+
+    if status == errSecSuccess {
+        return true
+    }
+
+    // Fallback to local key
+    let localQuery: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: KEYCHAIN_SERVICE,
+        kSecAttrAccount as String: KEYCHAIN_ACCOUNT,
+        kSecAttrSynchronizable as String: false,
+        kSecReturnData as String: false
+    ]
+
+    debug("Checking local key...")
+    result = nil
+    status = SecItemCopyMatching(localQuery as CFDictionary, &result)
+    debug("Local check returned: \(status)")
 
-    // If we get errSecItemNotFound, iCloud Keychain is available but empty
-    // If we get errSecSuccess, iCloud Keychain is available with items
-    // Other errors may indicate iCloud Keychain is not available
-    return status == errSecSuccess || status == errSecItemNotFound
+    return status == errSecSuccess
 }
 
-/// Main entry point
-func main() -> Int32 {
-    // Handle --check flag
-    if CommandLine.arguments.contains("--check") {
-        if isICloudKeychainAvailable() {
-            print("iCloud Keychain available")
-            return 0
-        } else {
-            fputs("iCloud Keychain not available\n", stderr)
-            return 2
-        }
+/// Store an encryption key in the LOCAL (file-based) keychain.
+///
+/// This is used for manual key import when iCloud Keychain sync doesn't work for CLI.
+/// The key is stored with kSecAttrSynchronizable: false so it stays in login.keychain.
+///
+/// - Parameter keyData: The 32-byte AES-256 encryption key
+/// - Returns: true if stored successfully, false otherwise.
+func storeLocalKey(_ keyData: Data) -> Bool {
+    debug("Storing key in local keychain...")
+    debug("  Key size: \(keyData.count) bytes")
+
+    // Validate key size (AES-256 = 32 bytes)
+    guard keyData.count == 32 else {
+        debug("Invalid key size: expected 32 bytes, got \(keyData.count)")
+        return false
     }
 
-    // Handle --help flag
-    if CommandLine.arguments.contains("--help") || CommandLine.arguments.contains("-h") {
+    // Delete any existing local key first
+    let deleteQuery: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: KEYCHAIN_SERVICE,
+        kSecAttrAccount as String: KEYCHAIN_ACCOUNT,
+        kSecAttrSynchronizable as String: false
+    ]
+
+    let deleteStatus = SecItemDelete(deleteQuery as CFDictionary)
+    debug("Delete existing returned: \(deleteStatus)")
+
+    // Store new key
+    let addQuery: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: KEYCHAIN_SERVICE,
+        kSecAttrAccount as String: KEYCHAIN_ACCOUNT,
+        kSecAttrSynchronizable as String: false,  // CRITICAL: file-based keychain
+        kSecValueData as String: keyData,
+        kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock
+    ]
+
+    let status = SecItemAdd(addQuery as CFDictionary, nil)
+    debug("Add key returned: \(status)")
+
+    return status == errSecSuccess
+}
+
+// MARK: - Main
+
+func main() {
+    // First thing - write to log to prove we started
+    debug("=== Starting push-keychain-helper ===")
+
+    let args = CommandLine.arguments
+
+    // Check for debug mode
+    if args.contains("--debug") || args.contains("-d") {
+        debugMode = true
+        debug("Debug mode enabled (stderr output)")
+    }
+
+    debug("push-keychain-helper v\(VERSION)")
+    debug("Arguments: \(args)")
+
+    // Handle --version
+    if args.contains("--version") || args.contains("-v") {
+        print(VERSION)
+        exit(ExitCode.success.rawValue)
+    }
+
+    // Handle --help
+    if args.contains("--help") || args.contains("-h") {
         print("""
-        Usage: push-keychain-helper [options]
+        push-keychain-helper - Read/write Push encryption key
 
-        Options:
-          --check    Check if iCloud Keychain is available
-          --help     Show this help
+        USAGE:
+            push-keychain-helper           Output base64-encoded encryption key
+            push-keychain-helper --check   Check if key exists (exit 0) or not (exit 1)
+            push-keychain-helper --store   Import key from stdin (base64)
+            push-keychain-helper --debug   Enable debug output
+            push-keychain-helper --version Print version
+            push-keychain-helper --help    Show this help
 
-        Without options, retrieves and prints the E2EE key as base64.
+        EXIT CODES:
+            0  Success
+            1  Key not found / invalid key
+            2  iCloud Keychain not available
+            3  Other error
 
-        Exit codes:
-          0 - Success
-          1 - Key not found
-          2 - iCloud Keychain not available
-          3 - Other error
+        NOTES:
+            - Key is stored by the Push iOS app in iCloud Keychain
+            - For CLI, use --store to import key to local (file-based) keychain
+            - First run may prompt for Keychain access permission
         """)
-        return 0
+        exit(ExitCode.success.rawValue)
     }
 
-    // Check iCloud Keychain availability first
-    if !isICloudKeychainAvailable() {
-        fputs("Error: iCloud Keychain not available\n", stderr)
-        return 2
-    }
+    // Handle --store (import key from stdin)
+    if args.contains("--store") {
+        debug("Store mode: reading key from stdin...")
 
-    // Get the encryption key
-    let (keyData, status) = getEncryptionKey()
+        // Read base64 key from stdin
+        guard let inputLine = readLine() else {
+            fputs("Error: No input provided. Paste the base64 key from your iOS app.\n", stderr)
+            exit(ExitCode.keyNotFound.rawValue)
+        }
 
-    switch status {
-    case errSecSuccess:
-        if let data = keyData {
-            // Output as base64
-            print(data.base64EncodedString())
-            return 0
-        } else {
-            fputs("Error: Key data is nil\n", stderr)
-            return 3
+        let base64Key = inputLine.trimmingCharacters(in: .whitespacesAndNewlines)
+        debug("Read base64 key: \(base64Key.prefix(20))...")
+
+        // Decode base64
+        guard let keyData = Data(base64Encoded: base64Key) else {
+            fputs("Error: Invalid base64 encoding.\n", stderr)
+            exit(ExitCode.keyNotFound.rawValue)
         }
 
-    case errSecItemNotFound:
-        fputs("Error: Encryption key not found in Keychain\n", stderr)
-        fputs("Make sure E2EE is enabled in the Push iOS app\n", stderr)
-        return 1
+        debug("Decoded key: \(keyData.count) bytes")
 
-    case errSecAuthFailed:
-        fputs("Error: Keychain authentication failed\n", stderr)
-        return 3
+        // Validate key size
+        guard keyData.count == 32 else {
+            fputs("Error: Invalid key size. Expected 32 bytes, got \(keyData.count).\n", stderr)
+            exit(ExitCode.keyNotFound.rawValue)
+        }
 
-    default:
-        fputs("Error: Keychain error (status: \(status))\n", stderr)
-        return 3
+        // Store in local keychain
+        if storeLocalKey(keyData) {
+            print("Key stored successfully in macOS Keychain")
+            exit(ExitCode.success.rawValue)
+        } else {
+            fputs("Error: Failed to store key in Keychain.\n", stderr)
+            exit(ExitCode.otherError.rawValue)
+        }
+    }
+
+    // Handle --check (just check if key exists)
+    if args.contains("--check") {
+        if keyExists() {
+            print("Key exists")
+            exit(ExitCode.success.rawValue)
+        } else {
+            print("Key not found")
+            exit(ExitCode.keyNotFound.rawValue)
+        }
+    }
+
+    // Default: read and output the key
+    debug("Reading encryption key...")
+    guard let keyData = readEncryptionKey() else {
+        fputs("Error: Encryption key not found in iCloud Keychain.\n", stderr)
+        fputs("Make sure:\n", stderr)
+        fputs("  1. You have enabled E2EE in the Push iOS app\n", stderr)
+        fputs("  2. iCloud Keychain is syncing to this Mac\n", stderr)
+        fputs("  3. You're signed into the same Apple ID\n", stderr)
+        exit(ExitCode.keyNotFound.rawValue)
     }
+
+    debug("Key found, outputting base64...")
+    // Output base64-encoded key to stdout
+    print(keyData.base64EncodedString())
+    exit(ExitCode.success.rawValue)
 }
 
-exit(main())
+main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masslessai/push-todo",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Voice tasks from Push iOS app for Claude Code",
   "type": "module",
   "bin": {
@@ -29,6 +29,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js",
     "test": "node --test test/",
     "start": "node bin/push-todo.js"
   },