alexa-sync 0.1.0__tar.gz

alexa_sync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owen Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alexa_sync-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: alexa-sync
+Version: 0.1.0
+Summary: Two-way sync between the Alexa shopping list and Apple Reminders
+Keywords: alexa,amazon,shopping list,apple reminders,macos,sync
+Author: Owen Williams
+Author-email: Owen Williams <owen@willia.ms>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Dist: aioamazondevices==16.3.0
+Requires-Dist: keyring>=25.7.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/ow/Alexa-apple-reminders
+Project-URL: Issues, https://github.com/ow/Alexa-apple-reminders/issues
+Description-Content-Type: text/markdown
+
+# alexa-sync
+
+Two-way sync between your Alexa shopping list and a list in Apple Reminders, on macOS.
+
+Say "Alexa, add oat milk to my shopping list" and it shows up in Reminders a minute or two later. Tick it off in Reminders at the store and it's ticked off on Alexa too.
+
+> **Unofficial.** Amazon has no public API for the shopping list anymore, so this uses the same private endpoints as the Alexa app. It can break whenever Amazon changes them. Use at your own risk.
+
+## Requirements
+
+- macOS 14+
+- [uv](https://docs.astral.sh/uv/) (or pipx)
+- [`remindctl`](https://github.com/openclaw/remindctl): `brew install steipete/tap/remindctl`, then `remindctl authorize`
+- An Amazon account with **2-Step Verification using an authenticator app** (the login flow needs a code, not an SMS or push approval)
+
+## Setup
+
+```sh
+uv tool install git+https://github.com/ow/Alexa-apple-reminders
+
+alexa-sync login                     # email, password, authenticator code (one time)
+alexa-sync doctor --list Groceries   # check everything is ready
+alexa-sync run --list Groceries --dry-run   # preview the first sync
+alexa-sync install --list Groceries  # sync every 2 minutes in the background
+```
+
+The Reminders list must already exist. `--list` defaults to `Groceries`.
+
+Other commands: `alexa-sync run` (sync once), `alexa-sync uninstall` (stop the background job), `install --interval 60` (change how often it runs, in seconds).
+
+## How it works
+
+**Amazon login.** `login` registers your Mac as a device on your Amazon account, the same way the Alexa phone app does (via [aioamazondevices](https://github.com/chemelli74/aioamazondevices)). That returns a long-lived token, which is kept in your macOS Keychain. Your password and 2FA code are not stored. The token is used to get fresh session cookies whenever needed. If it ever stops working you'll get a macOS notification asking you to run `alexa-sync login` again. To revoke it, remove the device under *Manage Your Content and Devices* on Amazon.
+
+**Sync.** Each run reads both lists and compares them with what they looked like after the last sync, so it can tell which side changed:
+
+- Adds, check-offs, un-checks, renames and deletes go both ways.
+- If the same item changed on both sides between syncs, Alexa wins.
+- Items that are already completed when first seen aren't copied. This keeps years of old Alexa history out of Reminders.
+- On the first sync, items with the same name on both sides are paired rather than duplicated.
+- If a single pass would delete more than 5 items it stops and notifies you instead (override with `--max-deletes`).
+
+**Files.**
+
+| What | Where |
+| --- | --- |
+| Amazon device token | Keychain, service `alexa-sync` |
+| Sync state | `~/Library/Application Support/alexa-sync/state.json` |
+| Log | `~/Library/Logs/alexa-sync.log` |
+| Background job | `~/Library/LaunchAgents/io.github.alexa-sync.plist` |
+
+Only the default Alexa shopping list is synced. It has been tested with amazon.com; other Amazon regions should work, since the login library supports them, but are untested.
+
+## Development
+
+```sh
+uv run pytest
+uv run alexa-sync run --dry-run -v
+```
+
+## License
+
+MIT

alexa_sync-0.1.0/README.md

@@ -0,0 +1,63 @@
+# alexa-sync
+
+Two-way sync between your Alexa shopping list and a list in Apple Reminders, on macOS.
+
+Say "Alexa, add oat milk to my shopping list" and it shows up in Reminders a minute or two later. Tick it off in Reminders at the store and it's ticked off on Alexa too.
+
+> **Unofficial.** Amazon has no public API for the shopping list anymore, so this uses the same private endpoints as the Alexa app. It can break whenever Amazon changes them. Use at your own risk.
+
+## Requirements
+
+- macOS 14+
+- [uv](https://docs.astral.sh/uv/) (or pipx)
+- [`remindctl`](https://github.com/openclaw/remindctl): `brew install steipete/tap/remindctl`, then `remindctl authorize`
+- An Amazon account with **2-Step Verification using an authenticator app** (the login flow needs a code, not an SMS or push approval)
+
+## Setup
+
+```sh
+uv tool install git+https://github.com/ow/Alexa-apple-reminders
+
+alexa-sync login                     # email, password, authenticator code (one time)
+alexa-sync doctor --list Groceries   # check everything is ready
+alexa-sync run --list Groceries --dry-run   # preview the first sync
+alexa-sync install --list Groceries  # sync every 2 minutes in the background
+```
+
+The Reminders list must already exist. `--list` defaults to `Groceries`.
+
+Other commands: `alexa-sync run` (sync once), `alexa-sync uninstall` (stop the background job), `install --interval 60` (change how often it runs, in seconds).
+
+## How it works
+
+**Amazon login.** `login` registers your Mac as a device on your Amazon account, the same way the Alexa phone app does (via [aioamazondevices](https://github.com/chemelli74/aioamazondevices)). That returns a long-lived token, which is kept in your macOS Keychain. Your password and 2FA code are not stored. The token is used to get fresh session cookies whenever needed. If it ever stops working you'll get a macOS notification asking you to run `alexa-sync login` again. To revoke it, remove the device under *Manage Your Content and Devices* on Amazon.
+
+**Sync.** Each run reads both lists and compares them with what they looked like after the last sync, so it can tell which side changed:
+
+- Adds, check-offs, un-checks, renames and deletes go both ways.
+- If the same item changed on both sides between syncs, Alexa wins.
+- Items that are already completed when first seen aren't copied. This keeps years of old Alexa history out of Reminders.
+- On the first sync, items with the same name on both sides are paired rather than duplicated.
+- If a single pass would delete more than 5 items it stops and notifies you instead (override with `--max-deletes`).
+
+**Files.**
+
+| What | Where |
+| --- | --- |
+| Amazon device token | Keychain, service `alexa-sync` |
+| Sync state | `~/Library/Application Support/alexa-sync/state.json` |
+| Log | `~/Library/Logs/alexa-sync.log` |
+| Background job | `~/Library/LaunchAgents/io.github.alexa-sync.plist` |
+
+Only the default Alexa shopping list is synced. It has been tested with amazon.com; other Amazon regions should work, since the login library supports them, but are untested.
+
+## Development
+
+```sh
+uv run pytest
+uv run alexa-sync run --dry-run -v
+```
+
+## License
+
+MIT

alexa_sync-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "alexa-sync"
+version = "0.1.0"
+description = "Two-way sync between the Alexa shopping list and Apple Reminders"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "alexa",
+    "amazon",
+    "shopping list",
+    "apple reminders",
+    "macos",
+    "sync",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "aioamazondevices==16.3.0",
+    "keyring>=25.7.0",
+]
+
+[[project.authors]]
+name = "Owen Williams"
+email = "owen@willia.ms"
+
+[project.urls]
+Homepage = "https://github.com/ow/Alexa-apple-reminders"
+Issues = "https://github.com/ow/Alexa-apple-reminders/issues"
+
+[project.scripts]
+alexa-sync = "alexa_sync.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

alexa_sync-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "alexa-sync"
+version = "0.1.0"
+description = "Two-way sync between the Alexa shopping list and Apple Reminders"
+readme = "README.md"
+authors = [
+    { name = "Owen Williams", email = "owen@willia.ms" }
+]
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["alexa", "amazon", "shopping list", "apple reminders", "macos", "sync"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: MacOS X",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "aioamazondevices==16.3.0",
+    "keyring>=25.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ow/Alexa-apple-reminders"
+Issues = "https://github.com/ow/Alexa-apple-reminders/issues"
+
+[project.scripts]
+alexa-sync = "alexa_sync.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

alexa_sync-0.1.0/src/alexa_sync/__init__.py

@@ -0,0 +1,3 @@
+"""Two-way sync between the Alexa shopping list and Apple Reminders."""
+
+__version__ = "0.1.0"

alexa_sync-0.1.0/src/alexa_sync/amazon.py

@@ -0,0 +1,211 @@
+"""Alexa shopping list side of the sync.
+
+Authentication piggybacks on aioamazondevices (the library behind Home
+Assistant's Alexa integration): it registers a virtual Alexa-app device once,
+which yields a long-lived refresh token. From then on we only ever trade that
+token for fresh website cookies; the password and OTP are never stored.
+
+The list endpoints are the same undocumented /alexashoppinglists/api/v2 calls
+the library and pyalexatodo use. We call them ourselves so we can paginate and
+see every field, but go through the library's HTTP wrapper for cookies/CSRF.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Coroutine
+from http import HTTPMethod
+from typing import Any
+
+from aiohttp import ClientSession
+from aioamazondevices.api import AmazonEchoApi
+from aioamazondevices.exceptions import CannotAuthenticate
+from aioamazondevices.structures import AmazonSaveDataConfig
+from yarl import URL
+
+from .sync import Item, normalize
+
+log = logging.getLogger(__name__)
+
+LISTS_PATH = "alexashoppinglists/api/v2/lists"
+PAGE_SIZE = 100  # API maximum
+
+
+class AuthExpired(Exception):
+    """The stored device registration no longer works; run `alexa-sync login`."""
+
+
+def make_api(session: ClientSession, email: str, password: str, login_data: dict | None, data_dir: str) -> AmazonEchoApi:
+    return AmazonEchoApi(
+        client_session=session,
+        login_email=email,
+        login_password=password,
+        login_data=login_data,
+        save_data=AmazonSaveDataConfig(path=data_dir),
+    )
+
+
+class AlexaClient:
+    """Async client for the shopping list. Refreshes cookies once on auth failure."""
+
+    def __init__(self, api: AmazonEchoApi) -> None:
+        self.api = api
+        self.login_data_changed = False
+
+    @property
+    def login_data(self) -> dict[str, Any]:
+        return self.api.login._session_state_data.login_stored_data
+
+    async def connect(self) -> None:
+        await self._with_refresh(self.api.login.login_mode_stored_data)
+
+    async def _refresh_cookies(self) -> None:
+        log.info("session cookies rejected; exchanging refresh token for new ones")
+        try:
+            await self.api.login._refresh_auth_cookies()
+        except Exception as exc:
+            raise AuthExpired("could not refresh Amazon cookies") from exc
+        self.login_data_changed = True
+
+    async def _with_refresh(self, fn: Callable[[], Coroutine[Any, Any, Any]]) -> Any:
+        try:
+            return await fn()
+        except (CannotAuthenticate, ValueError) as exc:
+            # ValueError: we got HTML (a sign-in page) instead of JSON.
+            log.debug("request failed with %r", exc)
+        await self._refresh_cookies()
+        try:
+            return await fn()
+        except (CannotAuthenticate, ValueError) as exc:
+            raise AuthExpired("Amazon rejected freshly refreshed cookies") from exc
+
+    async def _call(self, method: HTTPMethod, path: str, query: dict | None = None, body: dict | None = None) -> dict:
+        wrapper = self.api._http_wrapper
+        url = URL.joinpath(self.api.login._session_state_data.retail_site_url, LISTS_PATH, path)
+        if query:
+            url = url.with_query(query)
+
+        async def go() -> dict:
+            _, resp = await wrapper.session_request(method=method, url=url, input_data=body or {}, json_data=True)
+            return await wrapper.response_to_json(resp, "")
+
+        return await self._with_refresh(go)
+
+    async def shopping_list_id(self) -> str:
+        data = await self._call(HTTPMethod.POST, "fetch")
+        lists = data["listInfoList"]
+        shop = [l for l in lists if l.get("listType") == "SHOP"]
+        if not shop:
+            raise RuntimeError(f"no SHOP list among {[l.get('listType') for l in lists]}")
+        return (next((l for l in shop if l.get("defaultList")), shop[0]))["listId"]
+
+    async def items(self, list_id: str) -> list[dict]:
+        out: list[dict] = []
+        token = None
+        while True:
+            data = await self._call(
+                HTTPMethod.POST, f"{list_id}/items/fetch", {"limit": PAGE_SIZE}, {"nextToken": token} if token else {}
+            )
+            out += data.get("itemInfoList", [])
+            token = data.get("nextToken")
+            if not token:
+                return out
+
+    async def add(self, list_id: str, name: str) -> dict:
+        return await self._call(
+            HTTPMethod.POST, f"{list_id}/items", body={"items": [{"itemType": "KEYWORD", "itemName": name}]}
+        )
+
+    async def update(self, list_id: str, item_id: str, version: int, attrs: list[dict]) -> dict:
+        return await self._call(
+            HTTPMethod.PUT,
+            f"{list_id}/items/{item_id}",
+            {"version": version},
+            {"itemAttributesToUpdate": attrs, "itemAttributesToRemove": []},
+        )
+
+    async def delete(self, list_id: str, item_id: str, version: int) -> None:
+        await self._call(HTTPMethod.DELETE, f"{list_id}/items/{item_id}", {"version": version})
+
+
+def _find_item_id(obj: Any, name: str) -> str | None:
+    """Dig the new item's id out of an add response, whatever its exact shape."""
+    if isinstance(obj, dict):
+        if "itemId" in obj and normalize(str(obj.get("itemName", name))) == normalize(name):
+            return obj["itemId"]
+        obj = list(obj.values())
+    if isinstance(obj, list):
+        for v in obj:
+            if found := _find_item_id(v, name):
+                return found
+    return None
+
+
+class AlexaSide:
+    """Synchronous adapter over AlexaClient for the sync engine."""
+
+    label = "Alexa"
+
+    def __init__(self, client: AlexaClient, run: Callable[[Coroutine], Any], list_id: str) -> None:
+        self.client = client
+        self.run = run
+        self.list_id = list_id
+        self._versions: dict[str, int] = {}
+
+    def fetch(self) -> dict[str, Item]:
+        rows = self.run(self.client.items(self.list_id))
+        self._versions = {r["itemId"]: r["version"] for r in rows}
+        return {r["itemId"]: Item(r["itemId"], r["itemName"], r["itemStatus"] == "COMPLETE") for r in rows}
+
+    def add(self, name: str, completed: bool) -> str:
+        before = set(self._versions)
+        resp = self.run(self.client.add(self.list_id, name))
+        item_id = _find_item_id(resp, name)
+        if item_id is None:
+            log.debug("add response had no itemId (%r); re-fetching to find it", resp)
+            fresh = self.fetch()
+            new = [i for i in fresh.values() if i.id not in before and normalize(i.name) == normalize(name)]
+            if not new:
+                raise RuntimeError(f"added {name!r} but could not find it afterwards")
+            item_id = new[0].id
+        if completed:
+            self.update(item_id, name=None, completed=True)
+        return item_id
+
+    def _version(self, item_id: str) -> int:
+        if item_id not in self._versions:
+            self.fetch()
+        return self._versions[item_id]
+
+    def update(self, item_id: str, *, name: str | None, completed: bool | None) -> None:
+        attrs = []
+        if name is not None:
+            attrs.append({"type": "itemName", "value": name})
+        if completed is not None:
+            attrs.append({"type": "itemStatus", "value": "COMPLETE" if completed else "ACTIVE"})
+        self.run(self.client.update(self.list_id, item_id, self._version(item_id), attrs))
+        self._versions.pop(item_id, None)  # version bumped; re-read if needed again
+
+    def delete(self, item_id: str) -> None:
+        self.run(self.client.delete(self.list_id, item_id, self._version(item_id)))
+        self._versions.pop(item_id, None)
+
+
+class LoginFailed(Exception):
+    pass
+
+
+async def interactive_login(email: str, password: str, otp: str, data_dir: str) -> dict[str, Any]:
+    async with ClientSession() as session:
+        api = make_api(session, email, password, None, data_dir)
+        try:
+            return await api.login.login_mode_interactive(otp)
+        except CannotAuthenticate as exc:
+            if "OTP code not found" in str(exc):
+                raise LoginFailed(
+                    "Amazon didn't ask for a 2-Step Verification code. alexa-sync requires 2SV with an "
+                    "authenticator app: enable it under Your Account > Login & security, then try again. "
+                    "(It can also mean the password was wrong or Amazon showed a CAPTCHA.)"
+                ) from exc
+            raise LoginFailed(f"Amazon rejected the login ({exc}). Check the password and code, then retry.") from exc
+

alexa_sync-0.1.0/src/alexa_sync/cli.py

@@ -0,0 +1,289 @@
+"""alexa-sync: keep the Alexa shopping list and an Apple Reminders list in sync."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import fcntl
+import getpass
+import json
+import logging
+import os
+import plistlib
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import keyring
+
+from . import __version__, amazon
+from .reminders import RemindersSide, RemindersUnavailable, check_access
+from .sync import Pair, TooManyDeletes, sync
+
+log = logging.getLogger("alexa_sync")
+
+DATA_DIR = Path.home() / "Library/Application Support/alexa-sync"
+STATE_FILE = DATA_DIR / "state.json"
+LOCK_FILE = DATA_DIR / "run.lock"
+LOG_FILE = Path.home() / "Library/Logs/alexa-sync.log"
+KEYCHAIN_SERVICE = "alexa-sync"
+KEYCHAIN_ACCOUNT = "amazon-device"
+AGENT_LABEL = "io.github.alexa-sync"
+LEGACY_AGENT_LABELS = ["ms.willia.alexa-sync"]
+LAUNCH_AGENTS = Path.home() / "Library/LaunchAgents"
+AGENT_PLIST = LAUNCH_AGENTS / f"{AGENT_LABEL}.plist"
+ALERT_EVERY = 6 * 3600
+
+
+# --- persistence -----------------------------------------------------------
+
+
+def load_credentials() -> dict | None:
+    raw = keyring.get_password(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT)
+    return json.loads(raw) if raw else None
+
+
+def save_credentials(email: str, login_data: dict) -> None:
+    keyring.set_password(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, json.dumps({"email": email, "login_data": login_data}))
+
+
+def load_state() -> dict:
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except FileNotFoundError:
+        return {}
+
+
+def save_state(state: dict) -> None:
+    tmp = STATE_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(state, indent=2))
+    tmp.replace(STATE_FILE)
+
+
+def alert(state: dict, key: str, message: str) -> None:
+    """macOS notification, at most once per ALERT_EVERY for the same problem."""
+    log.error(message)
+    alerts = state.setdefault("alerts", {})
+    if time.time() - alerts.get(key, 0) < ALERT_EVERY:
+        return
+    alerts[key] = time.time()
+    script = f"display notification {json.dumps(message)} with title \"Alexa sync\""
+    subprocess.run(["osascript", "-e", script], check=False, capture_output=True)
+
+
+# --- commands --------------------------------------------------------------
+
+
+def cmd_login(args: argparse.Namespace) -> int:
+    email = args.email or input("Amazon email: ").strip()
+    password = getpass.getpass("Amazon password: ")
+    otp = input("2-Step Verification code from your authenticator app: ").strip()
+    try:
+        login_data = asyncio.run(amazon.interactive_login(email, password, otp, str(DATA_DIR)))
+    except amazon.LoginFailed as exc:
+        print(f"Login failed: {exc}", file=sys.stderr)
+        return 1
+    save_credentials(email, login_data)
+    print("Logged in. Device registration saved to Keychain (password and code were not stored).")
+    return 0
+
+
+class DryRun:
+    """Wraps a side so writes are logged instead of performed."""
+
+    def __init__(self, side) -> None:
+        self.side = side
+        self.label = side.label
+        self._n = 0
+
+    def fetch(self):
+        return self.side.fetch()
+
+    def add(self, name, completed):
+        print(f"[dry-run] {self.label}: add {name!r}")
+        self._n += 1
+        return f"dry-{self._n}"
+
+    def update(self, item_id, *, name, completed):
+        print(f"[dry-run] {self.label}: update {item_id} name={name!r} completed={completed!r}")
+
+    def delete(self, item_id):
+        print(f"[dry-run] {self.label}: delete {item_id}")
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    with open(LOCK_FILE, "w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            log.info("another run is in progress; skipping")
+            return 0
+        state = load_state()
+        try:
+            return _run(args, state)
+        finally:
+            if not args.dry_run:
+                save_state(state)
+
+
+def _run(args: argparse.Namespace, state: dict) -> int:
+    creds = load_credentials()
+    if not creds:
+        alert(state, "auth", "Not logged in to Amazon. Run: alexa-sync login")
+        return 2
+
+    try:
+        check_access()
+        reminders = RemindersSide(args.list)
+        state["reminders_list_id"] = reminders.resolve(state.get("reminders_list_id"))
+    except (RemindersUnavailable, RuntimeError) as exc:
+        alert(state, "reminders", str(exc))
+        return 2
+
+    with asyncio.Runner() as runner:
+        session = runner.run(_make_session())
+        try:
+            api = amazon.make_api(session, creds["email"], "", creds["login_data"], str(DATA_DIR))
+            client = amazon.AlexaClient(api)
+            try:
+                runner.run(client.connect())
+                list_id = runner.run(client.shopping_list_id())
+                alexa = amazon.AlexaSide(client, runner.run, list_id)
+
+                a_side, r_side = (DryRun(alexa), DryRun(reminders)) if args.dry_run else (alexa, reminders)
+                pairs = [Pair.from_dict(p) for p in state.get("pairs", [])]
+                pairs = sync(a_side, r_side, pairs, max_deletes=args.max_deletes)
+            except amazon.AuthExpired:
+                alert(state, "auth", "Amazon login expired. Run: alexa-sync login")
+                return 2
+            except TooManyDeletes as exc:
+                alert(state, "deletes", f"Sync paused: {exc}")
+                return 3
+            finally:
+                if client.login_data_changed and not args.dry_run:
+                    save_credentials(creds["email"], client.login_data)
+        finally:
+            runner.run(session.close())
+
+    if not args.dry_run:
+        state["pairs"] = [p.to_dict() for p in pairs]
+        state.get("alerts", {}).clear()
+    log.info("synced %d paired items", len(pairs))
+    return 0
+
+
+async def _make_session():
+    from aiohttp import ClientSession
+
+    return ClientSession()
+
+
+def _checks(list_name: str) -> list[tuple[str, str | None]]:
+    """(description, problem or None) for everything a background run needs."""
+    results: list[tuple[str, str | None]] = []
+    try:
+        check_access()
+        results.append(("remindctl installed with Reminders access", None))
+        try:
+            RemindersSide(list_name).resolve(load_state().get("reminders_list_id"))
+            results.append((f"Reminders list {list_name!r} found", None))
+        except RuntimeError as exc:
+            results.append((f"Reminders list {list_name!r} found", str(exc)))
+    except RemindersUnavailable as exc:
+        results.append(("remindctl installed with Reminders access", str(exc)))
+    results.append(("logged in to Amazon", None if load_credentials() else "run: alexa-sync login"))
+    return results
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    results = _checks(args.list)
+    for what, problem in results:
+        print(f"{'✗' if problem else '✓'} {what}" + (f": {problem}" if problem else ""))
+    print(f"{'✓' if AGENT_PLIST.exists() else '·'} background job {'installed' if AGENT_PLIST.exists() else 'not installed'}")
+    return 1 if any(p for _, p in results) else 0
+
+
+def _bootout_all() -> None:
+    uid = os.getuid()
+    for label in [AGENT_LABEL, *LEGACY_AGENT_LABELS]:
+        subprocess.run(["launchctl", "bootout", f"gui/{uid}/{label}"], capture_output=True)
+        (LAUNCH_AGENTS / f"{label}.plist").unlink(missing_ok=True)
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    problems = [f"{what}: {p}" for what, p in _checks(args.list) if p]
+    if problems:
+        print("Not installing; fix these first:\n  " + "\n  ".join(problems), file=sys.stderr)
+        return 1
+    # Keep the PATH entry (e.g. ~/.local/bin/alexa-sync from `uv tool install`)
+    # rather than resolving symlinks, so upgrades don't break the job.
+    exe = str(Path(shutil.which("alexa-sync") or sys.argv[0]).absolute())
+    AGENT_PLIST.parent.mkdir(parents=True, exist_ok=True)
+    LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    plist = {
+        "Label": AGENT_LABEL,
+        "ProgramArguments": [exe, "run", "--list", args.list],
+        "StartInterval": args.interval,
+        "RunAtLoad": True,
+        "StandardOutPath": str(LOG_FILE),
+        "StandardErrorPath": str(LOG_FILE),
+        "EnvironmentVariables": {"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"},
+    }
+    _bootout_all()
+    AGENT_PLIST.write_bytes(plistlib.dumps(plist))
+    subprocess.run(["launchctl", "bootstrap", f"gui/{os.getuid()}", str(AGENT_PLIST)], check=True)
+    print(f"Installed {AGENT_PLIST} (every {args.interval}s). Logs: {LOG_FILE}")
+    return 0
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    _bootout_all()
+    print("Uninstalled. Login stays in Keychain and sync state in", DATA_DIR)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="alexa-sync", description=__doc__)
+    parser.add_argument("-v", "--verbose", action="store_true")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("login", help="register this Mac with Amazon (one time)")
+    p.add_argument("--email")
+    p.set_defaults(fn=cmd_login)
+
+    p = sub.add_parser("run", help="sync once")
+    p.add_argument("--list", default="Groceries", help="Reminders list name (default: Groceries)")
+    p.add_argument("--max-deletes", type=int, default=5, help="abort if a pass would delete more than this")
+    p.add_argument("--dry-run", action="store_true", help="show what would change without changing anything")
+    p.set_defaults(fn=cmd_run)
+
+    p = sub.add_parser("install", help="run automatically via launchd")
+    p.add_argument("--list", default="Groceries")
+    p.add_argument("--interval", type=int, default=120, help="seconds between runs (default: 120)")
+    p.set_defaults(fn=cmd_install)
+
+    p = sub.add_parser("uninstall", help="remove the launchd job")
+    p.set_defaults(fn=cmd_uninstall)
+
+    p = sub.add_parser("doctor", help="check that everything needed is set up")
+    p.add_argument("--list", default="Groceries")
+    p.set_defaults(fn=cmd_doctor)
+
+    args = parser.parse_args()
+    if sys.platform != "darwin":
+        parser.exit(1, "alexa-sync only runs on macOS (it needs Apple Reminders).\n")
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    if not args.verbose:
+        logging.getLogger("aioamazondevices").setLevel(logging.WARNING)
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

alexa_sync-0.1.0/src/alexa_sync/reminders.py

@@ -0,0 +1,101 @@
+"""Apple Reminders side of the sync, via the remindctl CLI."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from .sync import Item
+
+INSTALL_HINT = "install it with: brew install steipete/tap/remindctl"
+
+
+class RemindersUnavailable(Exception):
+    pass
+
+
+def find_remindctl() -> str:
+    # launchd jobs get a minimal PATH, so also look in both Homebrew prefixes.
+    for candidate in (shutil.which("remindctl"), "/opt/homebrew/bin/remindctl", "/usr/local/bin/remindctl"):
+        if candidate and Path(candidate).exists():
+            return candidate
+    raise RemindersUnavailable(f"remindctl not found; {INSTALL_HINT}")
+
+
+def check_access() -> None:
+    """Raise RemindersUnavailable with a fix-it message if we can't use Reminders."""
+    proc = subprocess.run([find_remindctl(), "status", "--json"], capture_output=True, text=True, timeout=30)
+    try:
+        authorized = json.loads(proc.stdout).get("authorized")
+    except ValueError:
+        authorized = False
+    if not authorized:
+        raise RemindersUnavailable("no access to Reminders; run: remindctl authorize")
+
+
+class RemindersSide:
+    label = "Reminders"
+
+    def __init__(self, list_name: str) -> None:
+        self.list_name = list_name
+        self.list_id: str | None = None
+        self._bin = find_remindctl()
+
+    def _run(self, *args: str) -> object:
+        proc = subprocess.run(
+            [self._bin, *args, "--json", "--no-input", "--no-color"],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if proc.returncode != 0:
+            raise RuntimeError(f"remindctl {args[0]} failed: {proc.stderr.strip() or proc.stdout.strip()}")
+        return json.loads(proc.stdout) if proc.stdout.strip() else None
+
+    def resolve(self, pinned_id: str | None) -> str:
+        """Find the target list by ID (preferred) or unique name. Never creates one.
+
+        Shared iCloud lists can be missing from EventKit for a moment after a
+        process starts, so creating a list whenever the name isn't found would
+        make duplicates. Pinning the ID also survives two lists sharing a name.
+        """
+        lists = self._run("list")
+        by_id = {l["id"]: l for l in lists}
+        if pinned_id in by_id and by_id[pinned_id]["title"] == self.list_name:
+            self.list_id = pinned_id
+            return pinned_id
+        matches = [l["id"] for l in lists if l["title"] == self.list_name]
+        if not matches:
+            raise RuntimeError(f"no Reminders list named {self.list_name!r}; create it in Reminders first")
+        if len(matches) > 1:
+            raise RuntimeError(
+                f"{len(matches)} Reminders lists are named {self.list_name!r}; rename or delete the extras"
+            )
+        self.list_id = matches[0]
+        return self.list_id
+
+    def fetch(self) -> dict[str, Item]:
+        rows = self._run("show", "all", "--list", self.list_name)
+        return {r["id"]: Item(r["id"], r["title"], r["isCompleted"]) for r in rows if r["listID"] == self.list_id}
+
+    def add(self, name: str, completed: bool) -> str:
+        row = self._run("add", "--title", name, "--list", self.list_name)
+        if row["listID"] != self.list_id:
+            self._run("delete", row["id"], "--force")
+            raise RuntimeError(f"remindctl added {name!r} to list {row['listID']}, not {self.list_id}")
+        if completed:
+            self._run("edit", row["id"], "--complete")
+        return row["id"]
+
+    def update(self, item_id: str, *, name: str | None, completed: bool | None) -> None:
+        args = ["edit", item_id]
+        if name is not None:
+            args += ["--title", name]
+        if completed is not None:
+            args.append("--complete" if completed else "--incomplete")
+        self._run(*args)
+
+    def delete(self, item_id: str) -> None:
+        self._run("delete", item_id, "--force")

alexa_sync-0.1.0/src/alexa_sync/sync.py

@@ -0,0 +1,189 @@
+"""Two-way reconciliation between the Alexa shopping list and a Reminders list.
+
+The sync is state-based: we remember what each paired item looked like after the
+last successful sync, so on the next run we can tell which side changed. Neither
+side exposes reliable modification timestamps through the tools we use, so this
+three-way comparison (Alexa now, Reminders now, last synced) is what lets
+changes flow in both directions.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass
+from typing import Protocol
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Item:
+    id: str
+    name: str
+    completed: bool
+
+
+@dataclass
+class Pair:
+    alexa: str
+    reminder: str
+    name: str  # normalized name at last sync
+    completed: bool
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Pair:
+        return cls(**d)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class Side(Protocol):
+    """One end of the sync. Implementations raise on failure."""
+
+    label: str
+
+    def fetch(self) -> dict[str, Item]: ...
+    def add(self, name: str, completed: bool) -> str: ...
+    def update(self, item_id: str, *, name: str | None, completed: bool | None) -> None: ...
+    def delete(self, item_id: str) -> None: ...
+
+
+class TooManyDeletes(Exception):
+    pass
+
+
+def normalize(name: str) -> str:
+    return " ".join(name.split()).casefold()
+
+
+def display(name: str) -> str:
+    """Alexa stores voice-added items lowercase ("milk"); make them look normal."""
+    name = " ".join(name.split())
+    return name[:1].upper() + name[1:] if name.islower() else name
+
+
+@dataclass
+class _Update:
+    side: Side
+    item_id: str
+    name: str | None
+    completed: bool | None
+
+
+def sync(alexa: Side, reminders: Side, pairs: list[Pair], max_deletes: int = 5) -> list[Pair]:
+    """Run one sync pass and return the new list of pairs to persist."""
+    a_items = alexa.fetch()
+    r_items = reminders.fetch()
+
+    deletes: list[tuple[Side, str, Pair]] = []
+    updates: list[tuple[_Update, Pair, Pair]] = []  # (update, old pair, new pair)
+    kept: list[Pair] = []
+
+    for p in pairs:
+        a = a_items.pop(p.alexa, None)
+        r = r_items.pop(p.reminder, None)
+        if a is None and r is None:
+            continue
+        if a is None:
+            deletes.append((reminders, p.reminder, p))
+            continue
+        if r is None:
+            deletes.append((alexa, p.alexa, p))
+            continue
+
+        new = Pair(p.alexa, p.reminder, p.name, p.completed)
+        a_update = _Update(alexa, a.id, None, None)
+        r_update = _Update(reminders, r.id, None, None)
+
+        # Name: Alexa wins if both sides renamed.
+        a_name, r_name = normalize(a.name), normalize(r.name)
+        if a_name != p.name:
+            new.name = a_name
+            if r_name != a_name:
+                r_update.name = display(a.name)
+        elif r_name != p.name:
+            new.name = r_name
+            a_update.name = r.name
+
+        # Completion: Alexa wins if both sides changed.
+        if a.completed != p.completed:
+            new.completed = a.completed
+            if r.completed != a.completed:
+                r_update.completed = a.completed
+        elif r.completed != p.completed:
+            new.completed = r.completed
+            a_update.completed = r.completed
+
+        pending = [u for u in (a_update, r_update) if u.name is not None or u.completed is not None]
+        if not pending:
+            kept.append(new)
+        for i, u in enumerate(pending):
+            # Record the new pair only once, against the last update for this item.
+            updates.append((u, p, new if i == len(pending) - 1 else None))
+
+    if len(deletes) > max_deletes:
+        raise TooManyDeletes(
+            f"refusing to delete {len(deletes)} items in one pass (limit {max_deletes}); "
+            "run with --max-deletes to allow it"
+        )
+
+    # Unpaired items. Completed ones are history, not something to copy over.
+    a_new = [a for a in a_items.values() if not a.completed]
+    r_new = [r for r in r_items.values() if not r.completed]
+
+    # Pair up identical names first so an initial sync doesn't duplicate items
+    # that already exist on both sides.
+    r_by_name: dict[str, list[Item]] = {}
+    for r in r_new:
+        r_by_name.setdefault(normalize(r.name), []).append(r)
+    a_unmatched: list[Item] = []
+    for a in a_new:
+        matches = r_by_name.get(normalize(a.name))
+        if matches:
+            r = matches.pop(0)
+            kept.append(Pair(a.id, r.id, normalize(a.name), False))
+        else:
+            a_unmatched.append(a)
+    r_unmatched = [r for rs in r_by_name.values() for r in rs]
+
+    result = list(kept)
+
+    for side, item_id, p in deletes:
+        try:
+            side.delete(item_id)
+            log.info("deleted %r from %s", p.name, side.label)
+        except Exception:
+            log.exception("failed to delete %r from %s", p.name, side.label)
+            result.append(p)
+
+    failed: set[int] = set()
+    for u, old, new in updates:
+        try:
+            if id(old) not in failed:
+                u.side.update(u.item_id, name=u.name, completed=u.completed)
+                log.info("updated %r on %s (name=%r, completed=%r)", old.name, u.side.label, u.name, u.completed)
+        except Exception:
+            log.exception("failed to update %r on %s", old.name, u.side.label)
+            failed.add(id(old))
+        if new is not None:
+            # If any half failed, keep the old snapshot so the change is retried.
+            result.append(old if id(old) in failed else new)
+
+    for a in a_unmatched:
+        try:
+            rid = reminders.add(display(a.name), False)
+            result.append(Pair(a.id, rid, normalize(a.name), False))
+            log.info("added %r to %s", a.name, reminders.label)
+        except Exception:
+            log.exception("failed to add %r to %s", a.name, reminders.label)
+
+    for r in r_unmatched:
+        try:
+            aid = alexa.add(r.name, False)
+            result.append(Pair(aid, r.id, normalize(r.name), False))
+            log.info("added %r to %s", r.name, alexa.label)
+        except Exception:
+            log.exception("failed to add %r to %s", r.name, alexa.label)
+
+    return result