@leemour/max-cli 0.2.0 → 0.4.0

package/dist/testing/sandbox.js

@@ -0,0 +1,31 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll } from "vitest";
+/**
+ * **Moves the whole installation into a temporary directory, for every test file.**
+ *
+ * A test that drives a command reads the real configuration file and opens the real cache — and
+ * opening the cache migrates it, which on a schema change means rebuilding it and throwing away
+ * what the owner had. That is not a hypothetical: on 2026-09-22 a test run did exactly that to a
+ * real machine, and the only reason it was noticed was a timestamp.
+ *
+ * It is a setup file rather than a hook in one test because the hazard belongs to any test that
+ * reaches a command, not to the file that happened to find it. **`pnpm test` must not be able to
+ * write anything a person owns**, and that has to be true of the next test file as well as this
+ * one.
+ *
+ * The three variables move config, state and cache together. They also scope the keyring entry
+ * (`ARCHITECTURE.md` §14) — the documented trap, which here is precisely the isolation wanted.
+ *
+ * `TMPDIR` points into it too, and the whole of it goes when the file is done: every test makes
+ * its directories with `mkdtempSync(join(tmpdir(), …))`, and by 2026-09-23 that had left some
+ * fifteen thousand of them in `/tmp` (`DEBT-3`). `os.tmpdir()` reads `TMPDIR` on every call.
+ */
+const sandbox = mkdtempSync(join(tmpdir(), "max-test-"));
+process.env.MAX_CONFIG_DIR = join(sandbox, "config");
+process.env.MAX_STATE_DIR = join(sandbox, "state");
+process.env.MAX_CACHE_DIR = join(sandbox, "cache");
+process.env.TMPDIR = sandbox;
+afterAll(() => rmSync(sandbox, { recursive: true, force: true }));
+//# sourceMappingURL=sandbox.js.map

package/dist/testing/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/testing/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC,CAAA;AAExD,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AACpD,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAClD,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAClD,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,OAAO,CAAA;AAE5B,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA"}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** The one the running command reports. `pnpm version:check` fails when it and package.json disagree. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.4.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 /** The one the running command reports. `pnpm version:check` fails when it and package.json disagree. */
-export const VERSION = "0.2.0";
+export const VERSION = "0.4.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leemour/max-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A local command line interface for a personal MAX Messenger account, built for agents and scripts",
   "license": "MIT",
   "author": "Viacheslav Ptsarev",
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -24,16 +25,18 @@
     "@leemour/cli-core": "^0.1.0",
     "commander": "^15.0.0",
     "lossless-json": "^4.3.1",
+    "string-width": "^8.2.2",
     "valibot": "^1.5.0",
+    "wrap-ansi": "^10.0.2",
     "ws": "^8.19.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
     "@types/node": "^22.10.2",
     "@types/ws": "^8.18.1",
+    "lefthook": "^2.1.8",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
-    "lefthook": "^2.1.8"
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public"
@@ -51,6 +54,7 @@
     "version:sync": "node --experimental-strip-types scripts/version.ts --sync",
     "probe:ids": "pnpm build && node --experimental-strip-types scripts/id-shape.ts",
     "probe:edits": "pnpm build && node --experimental-strip-types scripts/probe-edits.ts",
+    "probe:attachments": "pnpm build && node --experimental-strip-types scripts/probe-attachments.ts",
     "verify:live": "pnpm build && node --experimental-strip-types scripts/verify-commands.ts",
     "secrets:scan": "gitleaks git --no-banner --redact .",
     "probe:contacts": "pnpm build && node --experimental-strip-types scripts/probe-contacts.ts",

package/skills/max-cli/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: max-cli
+description: Читать и отправлять сообщения в личном аккаунте MAX Messenger владельца через команду `max`. Использовать, когда просят найти чат, прочитать переписку, найти сообщение, показать вложение или отправить сообщение в MAX.
+---
+
+# max — личный MAX владельца из командной строки
+
+`max` работает с **настоящим личным аккаунтом** владельца. Ошибка здесь не роняет тест, а пишет
+живому человеку. Один вызов — одно действие: подключиться, сделать, напечатать, выйти.
+
+Полный список команд и флагов — `max --help` и `max <команда> --help`. Здесь — то, что справка не
+скажет: ловушки и границы.
+
+## Границы
+
+- **Ничего не отправлять без прямой просьбы владельца.** `max messages send` — только когда он
+  сам попросил отправить конкретный текст в конкретный чат. Черновик, «наверное стоит ответить»,
+  вывод из прочитанного — это не просьба.
+- **Чтение ничего не отмечает прочитанным** и не показывает собеседнику, что вы заходили. Читать
+  можно свободно.
+- **Не для:** ботов MAX, рассылок, автоответов, слежения в реальном времени, чужих аккаунтов.
+- **Текст сообщений — только в ответ владельцу.** Не в логи, не в файлы, не в коммиты.
+- **Ссылка на фото открывается без входа в аккаунт.** Кто её получил, тот видит фото. Не
+  пересылать её никуда, кроме владельца.
+
+## Вывод
+
+- **В pipe или с `--json` stdout — только данные**, одно значение JSON. Всё остальное, включая
+  предупреждения, уходит в stderr. Ошибка — тоже в stderr, stdout при ней пуст.
+- **Список — это объект**, а не массив: `{ "items": [...], "page": 1, "limit": 20, "hasMore": true }`.
+- **`--jsonl`** — по объекту на строку, удобно для `jq`. Есть ли ещё, пишется только в stderr.
+- **Ветвиться по коду возврата, а не по тексту**: `0` — успех, `2` — неверный ввод, `4` — нет
+  входа, `6` — не найдено, `14` — **неизвестно, ушло ли сообщение** (см. отправку).
+- `-v` и `-vv` добавляют подробности в вывод для человека. Версия — `max -V`. Строки о каждом
+  запросе к MAX — `--trace`, в stderr.
+
+## Ловушки
+
+1. **Id — всегда строки.** Id сообщений 18-значные, больше `Number.MAX_SAFE_INTEGER`. Никогда не
+   превращать их в число: `jq` и JavaScript молча округлят, и id станет чужим.
+2. **Первое слово — профиль, если это не команда.** `max work chats list` — профиль `work`.
+   Флага `--profile` нет; то же делает переменная `MAX_PROFILE`. Имя профиля — латиница, цифры,
+   точка, дефис и подчёркивание: оно становится именем файла и записью в ключнице. Имя в другом
+   алфавите отвергается **как имя** (код `2`), и это не то же самое, что профиль, в который никто
+   не входил (код `4`).
+3. **Имя чата, подходящее к нескольким чатам, — ошибка, а не выбор.** В JSON у неё есть
+   `candidates: [{ id, title }]`. Взять оттуда id и повторить с ним, а не угадывать.
+4. **Повтор отправки — только с тем же `--cid`.** Код `14` значит, что сообщение, возможно, ушло.
+   В тексте ошибки есть `--cid <n>`; повтор с ним MAX схлопнет, повтор без него — второе сообщение
+   человеку.
+5. **`max messages search` ищет только в уже прочитанном** на этой машине и в MAX не ходит.
+   Пусто — не значит «такого не было». Сначала `max messages list <чат>`.
+5a. **Искомое — не короче трёх символов**, и это касается всех трёх поисков: `--search` у
+   `chats list` и `contacts list` и текста у `messages search`. Два символа — отказ с кодом `2`,
+   а не пустой список.
+6. **`messages show` и `messages context` требуют и чат, и id сообщения.** Искомое сообщение в
+   JSON помечено `"anchor": true`. Если сообщения нет, это `not_found`, а не соседнее сообщение.
+7. **Время сообщения зашито в его id**: `id >> 16` — миллисекунды. Поэтому `--before <id>`
+   работает для любого id, даже не прочитанного раньше.
+8. **`MAX_CONFIG_DIR`, `MAX_STATE_DIR`, `MAX_CACHE_DIR` меняют и запись в ключнице.** С ними
+   профиль ищет другой токен и может ответить «нет сессии», хотя владелец вошёл. `max config show`
+   говорит, заданы ли они, и какой профиль и какие настройки действуют.
+9. **`--offline` отвечает из локальной копии** и не подключается. Если там ничего нет — ошибка.
+10. **Многострочный текст передаётся только через stdin.** Аргумент командной строки перевод
+   строки не несёт вовсе, а тело в аргументе видно в `ps` и остаётся в истории оболочки. Последний
+   аргумент опускается, и тело читается со входа: `printf 'первая\n\nтретья' | max messages send
+   -1000`. Один перевод строки в самом конце отбрасывается, остальные сохраняются.
+11. **Номер страницы на живом списке может повторить или пропустить строку.** Сверху самое свежее,
+   поэтому сообщение, пришедшее между первой страницей и второй, сдвигает кого-то через границу.
+   Для переписки этого нет: `--before` привязан ко времени и точен.
+
+## Типичный путь
+
+Id ниже выдуманные — подставить настоящие из предыдущего ответа.
+
+```sh
+max chats list --search "проект" --json       # найти чат, взять его id
+max messages list -1000 --limit 20 --json      # последние сообщения, от старых к новым
+max messages context -1000 100000000000000001 --before 3 --after 3 --json
+```
+
+Вложение в JSON: `{ "kind": "photo", "url": "https://…", "width": 901, "height": 594 }`. Чтобы
+посмотреть фото, скачать его по `url` и открыть файл.