@leemour/max-cli 0.7.0 → 0.8.0

package/README.md

@@ -1,48 +1,138 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/leemour/max-cli/main/docs/design/logo.png" alt="max-cli" width="160">
+</p>
+
 # max-cli
 
-Читать и писать в свой личный аккаунт [MAX Messenger](https://max.ru) из терминала или из
-скрипта — чаты, сообщения, контакты, — не открывая браузер.
+Ваш личный аккаунт [MAX](https://max.ru) в терминале и в ИИ-агентах. `max` — командная строка и
+MCP-сервер: читайте и пишите в чаты сами или поручите это Claude, Codex, Cursor и другим агентам.
 
-Сделано **в первую очередь для агентов и скриптов**: любой результат доступен как одно
-детерминированное значение JSON, у любого отказа есть код, на который можно ветвиться, а stdout
-никогда не несёт ничего, кроме данных. Та же дисциплина делает его приятным для человека: в
-терминале таблицы и цвет, и ничего не происходит само.
+> ⚠️ **max-cli использует неофициальный внутренний API MAX.** API может измениться без
+> предупреждения, а использование инструмента может нарушать условия сервиса. Вы используете
+> max-cli на свой риск; авторы и контрибьюторы не несут ответственности за блокировки аккаунтов,
+> потерю данных или другие последствия.
 
 ```sh
-max session start qr   # один раз: токен уходит в ключницу
 max chats list --limit 5
 max messages list "Иван Петров"
+max messages send "Иван Петров" "Опаздываю на 15 минут"
 ```
 
-## Что это даёт
-
-- **Один запуск — одна операция.** Соединиться, сделать, напечатать, отключиться. Ничего не висит
-  фоном, не держит сокет и не слушает события: команда, которая напечатала ответ и не вышла, — это
-  дефект, а не особенность.
-- **Чтение ничего не помечает прочитанным.** В протоколе «получить историю» и «отметить
-  прочитанным» — разные операции; вторая не отправляется никогда, и это проверяется тестом, а не
-  обещается в README.
-- **Токен не касается ни файла, ни истории оболочки.** Он спрашивается без эха или читается из
-  трубы и уходит в ключницу операционной системы. В схеме настроек нет поля, куда его можно было
-  бы положить.
-- **Отправка, которая не врёт об исходе.** Если ответ не пришёл, это `outcome_unknown`, а не
-  «ошибка» и не «отправлено»: сообщение могло уйти. Повтор возможен только с тем же `--cid`, и
-  MAX схлопывает дубль — это измерено на реальном аккаунте, а не предположено.
-- **Имя чата не угадывается.** Часть названия, подходящая к двум чатам, — это отказ со списком
-  кандидатов. Отправить не в тот разговор нельзя отменить.
-- **Диагностика, в которой нет содержимого.** `--trace` показывает по строке на запрос,
-  `--record` кладёт их в каталог запуска на 30 дней. Операция, опкод, идентификаторы, байты,
-  длительности — да. Название чата, имя, текст, телефон, токен — никогда, ни обрезанными, ни
-  хэшем.
-- **По умолчанию не записывается ничего.** Мессенджер, который сам собирает каталог с историей
-  того, кого вы читали, — это чужая жизнь в чужом логе; запись включается флагом.
-- **Каждый вход спрашивает только то, что изменилось.** Метка времени прошлого входа уходит
-  обратно, и MAX присылает дельту, а не весь список заново — так что контакты остаются свежими,
-  не стоя ничего.
-- **Два рантайма, и это проверяется.** Node 22+ и Bun; под обоими в CI выполняется собранная
-  команда, а не только проверка типов.
-- **Мы выглядим как официальный клиент.** На проводе нет ни нашего имени, ни своего user-agent:
-  поля, которыми клиент представляется, копируют веб-клиент MAX.
+## Как это использовать
+
+Самое полезное — поручить переписку агенту: Claude, Codex или другому. Он читает чаты через `max`
+и делает то, что вы попросили словами.
+
+- **Проверка по расписанию.** Утром и вечером агент смотрит, что пришло, и присылает короткую
+  сводку: кто ждёт ответа, что срочно, что можно не читать.
+- **Отчёты.** Итог недели по рабочему чату: что решили, кто что взял на себя, какие вопросы
+  остались без ответа.
+- **Кто кому должен.** Агент находит в переписке обещания, долги и договорённости и собирает их в
+  список: кто, что, когда и в каком чате.
+- **Напоминания.** Кому вы обещали ответить и не ответили; чей вопрос висит третий день.
+- **Черновики ответов.** Агент предлагает текст, а отправляете вы — или он сам, если вы разрешили
+  писать в этот чат.
+- **Поиск.** «Когда мы договорились о встрече с Иваном?» — ответ с датой и самим сообщением.
+
+Как настроить агента под каждую задачу — готовые запросы, расписание и ограничения:
+[docs/recipes.md](docs/recipes.md).
+
+## Как это работает
+
+`max` работает от вашего имени, как ещё одно ваше устройство, а не как бот. Вы входите один раз
+по QR-коду, и дальше доступно то же, что в приложении: чаты, сообщения, файлы, группы, контакты и
+профиль.
+
+Агенту `max` подключается одним из двух способов:
+
+- **Агент с терминалом** — Claude Code, Codex, Gemini CLI. Он сам вызывает команды `max`. Дайте
+  ему навык (skill) — инструкцию, как работать с `max`: одна команда, см.
+  [ниже](#для-скриптов-и-агентов).
+- **Агент без терминала** — Claude Desktop, Cursor и другие клиенты MCP. Подключите `max mcp`.
+  По умолчанию агент только читает. Отправку можно разрешить, в том числе с вашим подтверждением
+  каждого сообщения.
+
+[![npm](https://img.shields.io/npm/v/@leemour/max-cli)](https://www.npmjs.com/package/@leemour/max-cli)
+[![CI](https://github.com/leemour/max-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/leemour/max-cli/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/node/v/@leemour/max-cli)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/bun-1.3%2B-f9f1e1)](https://bun.sh/)
+[![npm downloads](https://img.shields.io/npm/dm/@leemour/max-cli)](https://www.npmjs.com/package/@leemour/max-cli)
+[![License: MIT](https://img.shields.io/npm/l/@leemour/max-cli)](LICENSE)
+
+## Что умеет
+
+- **Читать.** Чаты, история, одно сообщение вместе с соседними, непрочитанное во всех чатах
+  сразу (`max inbox`), новые сообщения по мере прихода (`max watch`), скачивание вложений,
+  расшифровка голосовых в текст на вашем компьютере, выгрузка переписки в JSONL или Markdown.
+- **Искать.** Сообщения — по тексту всего прочитанного, без подключения к MAX. Чаты и контакты —
+  по части названия или имени.
+- **Писать.** Текст и разметка, ответы, фото и файлы, правка, пересылка, закрепление, реакции,
+  отложенная отправка, удаление — у себя или у всех.
+- **Вести группы и каналы.** Создать группу, вступить по ссылке, выйти, участники и админы,
+  название и настройки, заявки на вступление, ссылка-приглашение, папки.
+- **Контакты и аккаунт.** Найти человека по номеру, добавить, удалить, импортировать из файла;
+  изменить профиль; посмотреть и завершить другие сеансы.
+- **Входить удобным способом.** QR-код прямо в терминале, QR-код или SMS через web.max.ru в
+  браузере, или готовый токен.
+
+## Чем он хорош
+
+- **Читает незаметно.** Чтение не ставит отметку «прочитано»: собеседник не видит, что вы открыли
+  чат. Отметить прочитанным можно, когда нужно: `max chats read` или `--mark-read`.
+- **Агент не напишет лишнего.** Есть профиль только для чтения, список чатов, в которые можно
+  писать, и лимит сообщений в час. MCP-сервер может показывать вам каждое сообщение до отправки.
+  Если имя подходит к двум чатам, `max` не выбирает сам, а показывает оба.
+- **Сообщение не уйдёт дважды.** Если связь оборвалась во время отправки, `max` прямо говорит, что
+  не знает, дошло ли сообщение, и даёт команду для повтора. MAX узнаёт повтор и второго сообщения не
+  создаёт.
+- **Своя копия переписки.** Всё прочитанное сохраняется на вашем компьютере. По ней работает
+  быстрый поиск по тексту сообщений, и её можно читать без интернета (`--offline`). При входе MAX
+  присылает только то, что изменилось. Стереть копию — `max cache clear`.
+- **Пароль от аккаунта не лежит в файле.** Токен входа хранится в системном хранилище паролей:
+  Keychain в macOS, Secret Service (GNOME Keyring, KWallet) в Linux, диспетчер учётных данных в
+  Windows. В историю команд он не попадает.
+- **Скрипту и агенту легко разобрать ответ.** С `--json` команда отдаёт только данные, в одной и
+  той же форме, без текста для человека вокруг. Ошибка приходит отдельно и с номером, поэтому
+  скрипт сразу понимает, что случилось: нет входа, чат не найден или MAX не ответил вовремя.
+- **Разбор проблем без вашей переписки.** `--trace` показывает каждый запрос к MAX, чтобы понять,
+  почему команда не сработала. В этой записи нет текстов, имён, телефонов и токена, поэтому её
+  можно приложить к сообщению об ошибке. Без флага ничего не записывается.
+
+## Под заказ
+
+Делаем автоматизацию процессов и инструменты под вашу задачу: интеграции с MAX и другими
+мессенджерами, ИИ-агентов, внутренние сервисы. Пишите на [info@neirox.ai](mailto:info@neirox.ai).
+
+## Чем отличается от других
+
+Для MAX уже есть хорошие проекты, и max-cli многому у них научился.
+[PyMax](https://github.com/MaxApiTeam/PyMax) — самая полная библиотека для личного аккаунта; её код
+помог разобрать многие операции протокола. Выбирайте то, что подходит под задачу.
+
+| | max-cli | [PyMax](https://github.com/MaxApiTeam/PyMax) | [max-mcp](https://github.com/renosaza/max-mcp) |
+|---|:-:|:-:|:-:|
+| что это | командная строка и MCP-сервер | библиотека на Python | MCP-сервер на PyMax |
+| MCP-сервер и навык для агентов | ✅ | — | MCP |
+| ограничения для агента: только чтение, разрешённые действия, список чатов, лимит в час, подтверждение отправки | ✅ | — | — |
+| расшифровка голосовых в текст на вашем компьютере | ✅ | — | — |
+| готовые команды — не нужно писать свою программу | ✅ | — (библиотека для своего кода на Python) | — |
+| локальная копия с поиском и чтением без интернета | ✅ | — | — |
+| новые сообщения в реальном времени | ✅ `max watch` | ✅ обработчики событий | — |
+| отложенная отправка — уходит, даже если компьютер выключен | ✅ | ✅ | — |
+| выгрузка переписки в JSONL или Markdown | ✅ | — | — |
+| чтение, отправка текста, фото и файлов | ✅ | ✅ | ✅ |
+| реакции, правка, пересылка, закрепление | ✅ | ✅ | — |
+| удаление сообщений — у себя или у всех, с лимитом | ✅ | ✅ | — |
+| отметка «прочитано» по запросу | ✅ | ✅ | — |
+| группы и каналы: создать, вступить, участники, админы | ✅ | ✅ | чтение каналов |
+| контакты, профиль, другие сеансы | ✅ | ✅ | — |
+| отправка видео и кружков | — | ✅ | — |
+| отправка голосовых | — | ⚠️ в 2.4.1 не проходит ([#102](https://github.com/MaxApiTeam/PyMax/issues/102), [#103](https://github.com/MaxApiTeam/PyMax/issues/103)) | — |
+| опросы | — | ✅ | — |
+| пароль и двухфакторный вход, фото профиля | — | ✅ | — |
+
+Если нужен бот со своим аккаунтом, а не ваш личный аккаунт, — это официальный
+[Bot API MAX](https://dev.max.ru/docs).
 
 ## Содержание
 
@@ -52,7 +142,9 @@ max messages list "Иван Петров"
 - [Для скриптов и агентов](#для-скриптов-и-агентов)
 - [Документация](#документация)
 - [Разработка](#разработка)
+- [Дорожная карта](#дорожная-карта)
 - [Лицензия](#лицензия)
+- [Участие](#участие)
 
 ## Установка
 
@@ -69,7 +161,7 @@ npx @leemour/max-cli --help
 
 ```sh
 npm install -g @leemour/max-cli
-max --version      # 0.1.0
+max --version
 ```
 
 Нужен **Node 22 или новее**, либо **Bun 1.3+**. Подробности, переменные окружения и то, куда
@@ -77,8 +169,8 @@ max --version      # 0.1.0
 
 ## Вход
 
-`max session start qr` рисует QR-код в терминале: вы сканируете его приложением MAX, и токен уходит
-в ключницу. Ещё способы — `qr-chrome`, `sms` (оба через web.max.ru в браузере) и `token`
+`max session start qr` рисует QR-код в терминале: вы сканируете его приложением MAX, и токен входа
+сохраняется в системном хранилище паролей. Ещё способы — `qr-chrome`, `sms` (оба через web.max.ru в браузере) и `token`
 ([docs/sessions.md](docs/sessions.md)).
 
 ```sh
@@ -136,27 +228,12 @@ max cache clear
 
 ## Для скриптов и агентов
 
-```sh
-max chats list --json
-```
-
-`--json` — это **ровно одно значение JSON на stdout и больше ничего**: ни спиннера, ни галочки, ни
-предупреждения. То же самое включается само, когда stdout не терминал. Любой список отвечает одним
-объектом — `{ "items": […], "page": 1, "limit": 20, "hasMore": true }` — и `--all` с `--offline`
-отвечают **тем же**, чтобы разбирающему ответ не приходилось ветвиться на две формы.
+### Навык для агентов с терминалом
 
-Ошибка уходит на stderr, а stdout остаётся пустым, поэтому отказ невозможно принять за результат:
-
-```json
-{"error":{"code":"authentication_error","message":"no session for profile \"default\" — run `max session start`"}}
-```
-
-Ветвиться надо по коду возврата: `4` — нет сессии, `6` — не найдено, `9` — таймаут, `14` — исход
-неизвестен, `130` — прервано. Вся таблица — в [docs/commands.md](docs/commands.md).
-
-**Инструкция для агента** — не список флагов, а ловушки и границы: что нельзя делать без просьбы,
-почему id — строки, как повторять отправку. Ставится одной строкой, той же версии, что и `max`.
-Файл один и тот же, различается только папка:
+Навык (skill) — файл с инструкцией, который агент читает перед работой. В навыке `max` описано,
+какие команды есть, что агент делает только по вашей просьбе и как безопасно повторить отправку.
+Его понимают **Claude Code**, **Codex** и **Gemini CLI**. Навык ставится одной командой и всегда
+той же версии, что и `max`:
 
 ```sh
 # Claude Code
@@ -165,33 +242,59 @@ mkdir -p ~/.claude/skills/max-cli && max skill show > ~/.claude/skills/max-cli/S
 mkdir -p ~/.agents/skills/max-cli && max skill show > ~/.agents/skills/max-cli/SKILL.md
 ```
 
-Где какая среда ищет навыки: [Codex](https://learn.chatgpt.com/docs/build-skills),
-[Gemini CLI](https://geminicli.com/docs/cli/skills/) (сверено 2026-09-24).
+Как эти агенты находят навыки: [Codex](https://learn.chatgpt.com/docs/build-skills),
+[Gemini CLI](https://geminicli.com/docs/cli/skills/).
 
-**Для клиентов без терминала** — Claude Desktop, Cursor — тот же профиль по MCP. Без `--allow-send`
-сервер только читает. Подробно — [docs/mcp.md](docs/mcp.md).
+### MCP-сервер для агентов без терминала
+
+Claude Desktop, Cursor и другие клиенты MCP подключаются к `max mcp` и работают с тем же
+аккаунтом. Без `--allow-send` агент только читает. С `--confirm-send` перед каждой отправкой вы
+видите чат и текст и отвечаете «да» или «нет». Подробно — [docs/mcp.md](docs/mcp.md).
 
 ```sh
 claude mcp add max -- max mcp
 ```
 
+### Ответы в JSON
+
+```sh
+max chats list --json
+```
+
+С `--json` команда печатает только данные в JSON, без таблиц, цвета и подсказок. Так же она
+работает, когда её вывод читает другая программа, — например, в конвейере `max … | jq`. Любой
+список приходит в одной и той же форме:
+
+```json
+{ "items": [ … ], "page": 1, "limit": 20, "hasMore": true }
+```
+
+Ошибка приходит отдельно от данных, поэтому её нельзя принять за пустой результат:
+
+```json
+{"error":{"code":"authentication_error","message":"no session for profile \"default\" — run `max session start`"}}
+```
+
+У каждой ошибки есть номер — код завершения программы. По нему скрипт решает, что делать дальше:
+`4` — нужно войти, `6` — чат или сообщение не найдены, `9` — MAX не ответил вовремя, `14` —
+неизвестно, ушло ли сообщение. Все коды — в [docs/commands.md](docs/commands.md).
+
 ## Документация
 
-| | |
-|---|---|
-| [docs/installation.md](docs/installation.md) | установка, обновление, куда что ложится |
-| [docs/usage.md](docs/usage.md) | вход, чтение, отправка, машинный режим |
-| [docs/sessions.md](docs/sessions.md) | токен, ключница, профили |
-| [docs/configuration.md](docs/configuration.md) | настройки, переменные, порядок разрешения |
-| [docs/mcp.md](docs/mcp.md) | MCP-сервер: подключение, отправка, соединение с MAX |
-| [docs/diagnostics.md](docs/diagnostics.md) | `--trace`, `--record`, `max runs` |
-| [docs/security.md](docs/security.md) | что пишется на диск, а что никогда |
-| [docs/troubleshooting.md](docs/troubleshooting.md) | по симптому: что делать, когда не работает |
-| [docs/commands.md](docs/commands.md) | каждая команда и опция — **генерируется** из программы |
-| [docs/protocol.md](docs/protocol.md) | каждый опкод и откуда известна его форма — **генерируется** |
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | как это устроено и какие швы нельзя пересекать |
-| [docs/DECISIONS.md](docs/DECISIONS.md) | что и почему решено — читать прежде, чем «чинить» странное |
-| [docs/BACKLOG.md](docs/BACKLOG.md) | что осталось |
+- [docs/installation.md](docs/installation.md) — установка, обновление, куда что ложится
+- [docs/usage.md](docs/usage.md) — вход, чтение, отправка, машинный режим
+- [docs/sessions.md](docs/sessions.md) — токен, хранилище паролей, профили
+- [docs/configuration.md](docs/configuration.md) — настройки, переменные, порядок разрешения
+- [docs/mcp.md](docs/mcp.md) — MCP-сервер: подключение, отправка, соединение с MAX
+- [docs/recipes.md](docs/recipes.md) — рецепты для агентов: сводки, отчёты, долги, напоминания, расписание
+- [docs/diagnostics.md](docs/diagnostics.md) — `--trace`, `--record`, `max runs`
+- [docs/ROADMAP.md](docs/ROADMAP.md) — что планируется
+- [docs/security.md](docs/security.md) — что пишется на диск, а что никогда
+- [docs/troubleshooting.md](docs/troubleshooting.md) — по симптому: что делать, когда не работает
+- [docs/commands.md](docs/commands.md) — каждая команда и опция — **генерируется** из программы
+- [docs/protocol.md](docs/protocol.md) — каждый опкод и откуда известна его форма — **генерируется**
+- [docs/dev/ARCHITECTURE.md](docs/dev/ARCHITECTURE.md) — как это устроено и какие швы нельзя пересекать
+- [docs/dev/BACKLOG.md](docs/dev/BACKLOG.md) — что осталось
 
 Оглавление целиком — [docs/README.md](docs/README.md).
 
@@ -208,9 +311,25 @@ pnpm generate                         # переписать сгенериро
 каждого сообщения объявлены один раз в `src/spec/`, а реестр, типизированный клиент и
 [docs/protocol.md](docs/protocol.md) из них генерируются — и CI падает, если дерево устарело.
 
-Половина, не имеющая отношения к MAX — потоки вывода, рендерер, коды ошибок, ключница, часы, —
+Половина, не имеющая отношения к MAX — потоки вывода, рендерер, коды ошибок, хранилище паролей, часы, —
 вынесена в [`@leemour/cli-core`](https://github.com/leemour/cli-core) и общая с `braze-cli`.
 
+## Дорожная карта
+
+Ближайшее:
+
+- голосовые сообщения и видео;
+- опросы: показывать при чтении и голосовать;
+- локальная копия по желанию — можно работать совсем без неё.
+
+Весь список — [docs/ROADMAP.md](docs/ROADMAP.md).
+
 ## Лицензия
 
 MIT — см. [LICENSE](LICENSE).
+
+## Участие
+
+Пулл-реквесты, сообщения об ошибках и предложения приветствуются —
+[issues](https://github.com/leemour/max-cli/issues). Как устроен код и как его проверять —
+[docs/dev/ARCHITECTURE.md](docs/dev/ARCHITECTURE.md) и [docs/dev/TESTING.md](docs/dev/TESTING.md).

package/dist/cache/schema.d.ts

@@ -3,21 +3,26 @@ import type { CacheDatabase } from "./driver.js";
  * **Raise this on every change to the statements below.** The second schema change is the one that
  * corrupts somebody's file, because the first is always made while the only copy is your own.
  */
-export declare const SCHEMA_VERSION = 4;
+export declare const SCHEMA_VERSION = 5;
 /**
  * Brings a file up to date, and **refuses a file from the future** rather than writing to it.
  *
  * A newer `max` may have added a column this one does not know about. Reading it is survivable;
  * writing to it is how one version quietly destroys what another stored.
  *
- * **An older file is rebuilt, not altered.** Everything in here comes back from MAX, so a
- * column-by-column migration would be code that runs once, is tested never, and is how the second
- * schema change corrupts somebody's file. What a rebuild costs is one full login — which is what
- * every command did before the delta sync existed.
+ * **An older file is rebuilt, except for the history.** Chats, people and memberships come back
+ * from MAX with one login, so they are dropped and refilled rather than altered. Messages do not:
+ * getting a chat's history back costs a request per page, and a backup (`CLI-34`) is exactly what
+ * cannot be allowed to vanish on the next upgrade (`MAX-44`). `messages` and `ranges` therefore
+ * keep their rows — copied, by the columns both versions share, into the tables this version
+ * creates.
  *
- * ⚠ **This stops being the right answer the day the database holds something MAX cannot re-send.**
- * Contacts that are in no chat would be exactly that (`RES-7`), and the day they arrive this
- * becomes `ALTER TABLE … ADD COLUMN` and this paragraph gets rewritten.
+ * ⚠ **A column added to `messages` or `ranges` must be nullable or have a default.** The copy
+ * leaves it out, and a `NOT NULL` column without one fails it. A test holds every shipped shape of
+ * those tables to that.
+ *
+ * Contacts that are in no chat would be another thing MAX cannot re-send (`RES-7`); the day they
+ * arrive, their table joins `KEPT`.
  */
 /** Ours, so its message is known to hold no path and can be shown as it is. */
 export declare class NewerCacheError extends Error {

package/dist/cache/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/cache/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;GAGG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AAqM/B;;;;;;;;;;;;;;GAcG;AACH,+EAA+E;AAC/E,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAE7C,eAAO,MAAM,OAAO,GAAI,UAAU,aAAa,KAAG,IAgBjD,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/cache/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;GAGG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AAuM/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+EAA+E;AAC/E,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAO7C,eAAO,MAAM,OAAO,GAAI,UAAU,aAAa,KAAG,IAgCjD,CAAA"}

package/dist/cache/schema.js

@@ -2,7 +2,7 @@
  * **Raise this on every change to the statements below.** The second schema change is the one that
  * corrupts somebody's file, because the first is always made while the only copy is your own.
  */
-export const SCHEMA_VERSION = 4;
+export const SCHEMA_VERSION = 5;
 /**
  * Everything the cache holds, and the indexes are part of it rather than an afterthought — each
  * one exists for a query that is actually made.
@@ -80,6 +80,8 @@ const STATEMENTS = [
      attachments TEXT NOT NULL,
      link        TEXT,
      fetched_at  INTEGER NOT NULL,
+     transcript  TEXT,
+     transcript_model TEXT,
      PRIMARY KEY (chat_id, id)
    )`,
     `CREATE INDEX IF NOT EXISTS messages_by_time ON messages (chat_id, time DESC)`,
@@ -192,26 +194,53 @@ const STATEMENTS = [
  * A newer `max` may have added a column this one does not know about. Reading it is survivable;
  * writing to it is how one version quietly destroys what another stored.
  *
- * **An older file is rebuilt, not altered.** Everything in here comes back from MAX, so a
- * column-by-column migration would be code that runs once, is tested never, and is how the second
- * schema change corrupts somebody's file. What a rebuild costs is one full login — which is what
- * every command did before the delta sync existed.
+ * **An older file is rebuilt, except for the history.** Chats, people and memberships come back
+ * from MAX with one login, so they are dropped and refilled rather than altered. Messages do not:
+ * getting a chat's history back costs a request per page, and a backup (`CLI-34`) is exactly what
+ * cannot be allowed to vanish on the next upgrade (`MAX-44`). `messages` and `ranges` therefore
+ * keep their rows — copied, by the columns both versions share, into the tables this version
+ * creates.
  *
- * ⚠ **This stops being the right answer the day the database holds something MAX cannot re-send.**
- * Contacts that are in no chat would be exactly that (`RES-7`), and the day they arrive this
- * becomes `ALTER TABLE … ADD COLUMN` and this paragraph gets rewritten.
+ * ⚠ **A column added to `messages` or `ranges` must be nullable or have a default.** The copy
+ * leaves it out, and a `NOT NULL` column without one fails it. A test holds every shipped shape of
+ * those tables to that.
+ *
+ * Contacts that are in no chat would be another thing MAX cannot re-send (`RES-7`); the day they
+ * arrive, their table joins `KEPT`.
  */
 /** Ours, so its message is known to hold no path and can be shown as it is. */
 export class NewerCacheError extends Error {
 }
+const KEPT = ["messages", "ranges"];
+const versionOf = (database) => Number(database.prepare("PRAGMA user_version").get()?.user_version ?? 0);
 export const migrate = (database) => {
-    const current = Number(database.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+    const current = versionOf(database);
     if (current > SCHEMA_VERSION) {
         throw new NewerCacheError(`this cache was written by a newer max (schema ${current}, this one speaks ${SCHEMA_VERSION}) — ` +
             "run `max cache clear`, or use the newer version");
     }
-    if (current > 0 && current < SCHEMA_VERSION)
-        rebuild(database);
+    if (current > 0 && current < SCHEMA_VERSION) {
+        database.exec("BEGIN IMMEDIATE");
+        try {
+            // Another max may have waited on the same lock and upgraded the file while we did.
+            if (versionOf(database) === SCHEMA_VERSION) {
+                database.exec("COMMIT");
+                return;
+            }
+            const kept = rebuild(database);
+            for (const statement of STATEMENTS)
+                database.exec(statement);
+            for (const table of kept)
+                restore(database, table);
+            database.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+            database.exec("COMMIT");
+        }
+        catch (error) {
+            database.exec("ROLLBACK");
+            throw error;
+        }
+        return;
+    }
     for (const statement of STATEMENTS)
         database.exec(statement);
     database.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
@@ -219,28 +248,60 @@ export const migrate = (database) => {
 /**
  * Drops what is there by asking the file rather than by listing what we think a previous version
  * wrote. A version that added a table we have since forgotten would otherwise survive the rebuild
- * and collide with a later name.
+ * and collide with a later name. The tables in `KEPT` are set aside under another name instead, and
+ * returned so `restore` can bring them back.
  *
  * The `fetched` table goes with the rest on purpose: it records that a collection was complete,
  * and keeping it would claim a sweep whose rows have just been thrown away.
  */
 const rebuild = (database) => {
-    // ⚠ **Virtual tables first.** An FTS5 index keeps four shadow tables of its own, and
+    const names = (sql) => database
+        .prepare(sql)
+        .all()
+        .map(({ name }) => String(name));
+    // Triggers and indexes first: a kept table takes both along when it is renamed, and then the new
+    // table's `CREATE … IF NOT EXISTS` finds the name taken and quietly creates nothing. A trigger
+    // that writes to a search index about to be dropped also makes the rename itself fail.
+    for (const name of names("SELECT name FROM sqlite_master WHERE type = 'trigger'")) {
+        database.exec(`DROP TRIGGER IF EXISTS "${name}"`);
+    }
+    for (const name of names("SELECT name FROM sqlite_master WHERE type = 'index' AND sql IS NOT NULL")) {
+        database.exec(`DROP INDEX IF EXISTS "${name}"`);
+    }
+    // ⚠ **Virtual tables before ordinary ones.** An FTS5 index keeps four shadow tables of its own, and
     // `sqlite_master` lists them as ordinary tables. Dropping one of those out from under a live
     // index is how a rebuild leaves a corrupt file behind. Dropping the virtual table takes its
     // shadows with it, and the second pass then finds only real tables.
     //
     // It happens to work without this today, because `sqlite_master` returns them in creation order
     // and `IF EXISTS` swallows the leftovers. That is an accident of ordering, not a guarantee.
-    const virtual = database
-        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'")
-        .all();
-    for (const { name } of virtual)
-        database.exec(`DROP TABLE IF EXISTS "${String(name)}"`);
-    const tables = database
-        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
-        .all();
-    for (const { name } of tables)
-        database.exec(`DROP TABLE IF EXISTS "${String(name)}"`);
+    for (const name of names("SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'")) {
+        database.exec(`DROP TABLE IF EXISTS "${name}"`);
+    }
+    const kept = [];
+    for (const name of names("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")) {
+        if (KEPT.includes(name)) {
+            database.exec(`ALTER TABLE "${name}" RENAME TO "${name}_previous"`);
+            kept.push(name);
+        }
+        else {
+            database.exec(`DROP TABLE IF EXISTS "${name}"`);
+        }
+    }
+    return kept;
+};
+/** The search index fills itself: the insert trigger runs for every copied message. */
+const restore = (database, table) => {
+    const columns = (name) => database
+        .prepare(`PRAGMA table_info("${name}")`)
+        .all()
+        .map((row) => String(row.name));
+    const now = new Set(columns(table));
+    const shared = columns(`${table}_previous`)
+        .filter((column) => now.has(column))
+        .map((column) => `"${column}"`)
+        .join(", ");
+    database.exec(`INSERT OR IGNORE INTO "${table}" (${shared}) SELECT ${shared} FROM "${table}_previous"`);
+    database.exec(`DROP TABLE "${table}_previous"`);
 };
 //# sourceMappingURL=schema.js.map

package/dist/cache/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/cache/schema.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAA;AAE/B;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAG;IACjB;;;;;;;;;KASG;IACH,6EAA6E;IAE7E;;;;;;;;;OASG;IACH;;;;;;;;KAQG;IACH,gFAAgF;IAEhF;;;;OAIG;IACH;;;;KAIG;IACH,0EAA0E;IAE1E;;;;;;;OAOG;IACH;;;KAGG;IAEH;;;;;;;;;;;;;KAaG;IACH,8EAA8E;IAC9E,kFAAkF;IAClF,8FAA8F;IAC9F,4DAA4D;IAE5D;;;;OAIG;IACH;;;;;KAKG;IACH,0EAA0E;IAE1E;;;;OAIG;IACH;;;KAGG;IAEH;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qGAAqG;IACrG,gHAAgH;IAChH,0GAA0G;IAE1G;;;;;;;;;;;;;;;;OAgBG;IACH;;OAEK;IACL;;OAEK;IACL;;;OAGK;IAEL;;OAEK;IACL;;OAEK;IACL;;;OAGK;IAEL;;OAEK;IACL;;OAEK;IACL;;;OAGK;IAEL;;;;;;KAMG;CACJ,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,+EAA+E;AAC/E,MAAM,OAAO,eAAgB,SAAQ,KAAK;CAAG;AAE7C,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,QAAuB,EAAQ,EAAE;IACvD,MAAM,OAAO,GAAG,MAAM,CACnB,QAAQ,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,GAAG,EAAgC,EAAE,YAAY,IAAI,CAAC,CAChG,CAAA;IAED,IAAI,OAAO,GAAG,cAAc,EAAE,CAAC;QAC7B,MAAM,IAAI,eAAe,CACvB,iDAAiD,OAAO,qBAAqB,cAAc,MAAM;YAC/F,iDAAiD,CACpD,CAAA;IACH,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,cAAc;QAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAE9D,KAAK,MAAM,SAAS,IAAI,UAAU;QAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5D,QAAQ,CAAC,IAAI,CAAC,yBAAyB,cAAc,EAAE,CAAC,CAAA;AAC1D,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,GAAG,CAAC,QAAuB,EAAQ,EAAE;IAChD,qFAAqF;IACrF,6FAA6F;IAC7F,4FAA4F;IAC5F,oEAAoE;IACpE,EAAE;IACF,gGAAgG;IAChG,4FAA4F;IAC5F,MAAM,OAAO,GAAG,QAAQ;SACrB,OAAO,CAAC,0FAA0F,CAAC;SACnG,GAAG,EAAE,CAAA;IACR,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,yBAAyB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAEvF,MAAM,MAAM,GAAG,QAAQ;SACpB,OAAO,CAAC,kFAAkF,CAAC;SAC3F,GAAG,EAAE,CAAA;IAER,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,MAAM;QAAE,QAAQ,CAAC,IAAI,CAAC,yBAAyB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACxF,CAAC,CAAA"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/cache/schema.ts"],"names":[],"mappings":"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"}

package/dist/cache/store.d.ts

@@ -121,8 +121,23 @@ export interface CacheStore {
         write(chatId: Id, messages: Message[]): void;
         /** After a send, what we hold for that chat is missing the message we just added. */
         invalidate(chatId: Id): void;
+        /** Messages deleted in MAX: gone from reading and from search, not merely stale. */
+        forget(chatId: Id, messageIds: Id[]): void;
+        /** What `max messages transcribe` heard in a voice message, and which model heard it. */
+        transcript(chatId: Id, messageId: Id): {
+            text: string;
+            model: string;
+        } | undefined;
+        keepTranscript(chatId: Id, messageId: Id, text: string, model: string): void;
         /** `before` messages up to and including `time`, and `after` messages later than it, oldest first. */
         window(chatId: Id, time: number, before: number, after: number): Message[];
+        /** Everything held for a chat from `since` on, oldest first. */
+        all(chatId: Id, since?: number): Message[];
+        /** The windows read completely, in epoch ms, oldest first. Neighbouring windows are not merged. */
+        ranges(chatId: Id): {
+            from: number;
+            to: number;
+        }[];
         /**
          * Messages whose text contains `query`, newest first, across every chat we hold or one.
          *