apple-notes-prod-checklist

Apple Notes Production Checklist

Overview

Before deploying Apple Notes automation to a production macOS machine, validate every dependency: TCC permissions, iCloud sync health, Notes.app availability, error handling robustness, and data security. Unlike cloud services where deployment is a push, Apple Notes automation requires physical or remote access to a Mac with a logged-in user session. This checklist ensures nothing is missed before going live.

Pre-Deployment Checklist

Permissions and Access

• TCC automation permission granted (System Settings > Privacy > Automation)
• Permission tested from the exact context that will run in production (Terminal, launchd, etc.)
• Full Disk Access granted if reading Notes database directly (not recommended)
• Script runs without interactive prompts (no "Allow" dialogs left)

Application Configuration

• Notes.app configured to launch at login (System Settings > General > Login Items)
• Target Apple ID / iCloud account signed in and syncing
• "On My Mac" account enabled if local storage is needed
• Correct default account set for automation scripts

Data and Sync

• iCloud sync verified working (create note on Mac, verify on iPhone)
• Backup strategy documented (JSON export on schedule)
• Exported data files have restricted permissions (chmod 600)
• No sensitive data written to logs or temp files

Reliability

• Error handling for all AppleEvent failure codes (-1743, -1712, -609, -1728)
• Retry logic with exponential backoff for transient failures
• Write operations throttled (max 1 per second for iCloud sync)
• Health check script deployed and running on schedule
• Alerting configured for automation failures (macOS notification or webhook)

Compatibility

• Script tested on target macOS version (sw_vers)
• JXA API compatibility verified for target OS (Ventura/Sonoma/Sequoia)
• Node.js version matches production (if using child_process for osascript)

Validation Script

#!/bin/bash
echo "=== Apple Notes Production Readiness ==="
PASS=0; FAIL=0; WARN=0

check() {
  local label=$1 result=$2
  if [ "$result" = "PASS" ]; then echo "[PASS] $label"; PASS=$((PASS+1))
  elif [ "$result" = "WARN" ]; then echo "[WARN] $label"; WARN=$((WARN+1))
  else echo "[FAIL] $label"; FAIL=$((FAIL+1)); fi
}

# macOS version
VER=$(sw_vers -productVersion)
check "macOS version ($VER)" "$(echo "$VER" | grep -qE '^1[3-9]|^[2-9]' && echo PASS || echo WARN)"

# Notes.app running
check "Notes.app running" "$(pgrep -x Notes > /dev/null && echo PASS || echo FAIL)"

# JXA access
NOTE_COUNT=$(osascript -l JavaScript -e 'Application("Notes").defaultAccount.notes.length' 2>/dev/null)
check "JXA access (${NOTE_COUNT:-0} notes)" "$([ -n "$NOTE_COUNT" ] && echo PASS || echo FAIL)"

# iCloud sync daemon
check "iCloud sync daemon (bird)" "$(pgrep -x bird > /dev/null && echo PASS || echo WARN)"

# Write test (create and delete a test note)
TEST_ID=$(osascript -l JavaScript -e '
  const Notes = Application("Notes");
  const n = Notes.Note({name: "__prod_check_" + Date.now(), body: "test"});
  Notes.defaultAccount.folders[0].notes.push(n);
  n.id();
' 2>/dev/null)
check "Write permission test" "$([ -n "$TEST_ID" ] && echo PASS || echo FAIL)"
# Clean up test note
[ -n "$TEST_ID" ] && osascript -l JavaScript -e "Application('Notes').notes.byId('$TEST_ID').delete()" 2>/dev/null

echo ""
echo "=== Results: $PASS passed, $WARN warnings, $FAIL failed ==="
[ "$FAIL" -gt 0 ] && echo "BLOCKED: Fix failures before deploying" && exit 1
[ "$WARN" -gt 0 ] && echo "READY with warnings" && exit 0
echo "READY for production" && exit 0

Error Handling

Issue	Cause	Solution
Validation passes locally, fails on target Mac	Different macOS version or Apple ID	Run validation script on the exact production machine
Write test fails	Account is read-only (Gmail IMAP)	Switch to iCloud or "On My Mac" account
Notes.app not at login items	Removed after macOS update	Re-add via System Settings > General > Login Items
Health check does not alert	Notification permissions denied for Terminal	Grant notification permission in System Settings
iCloud sync lag in production	Large attachment uploads	Monitor with brctl status; set expectations for sync delay

Resources

• Mac Automation Scripting Guide
• macOS Login Items
• Apple System Status

Next Steps

For deploying as a launchd service, see apple-notes-deploy-integration. For ongoing monitoring, see apple-notes-observability.