colloq 0.2.0__py3-none-any.whl

colloq/_app/cli/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "colloq",
+  "version": "0.2.0",
+  "type": "module"
+}

colloq/_app/cli/public-url-lease.mjs

@@ -0,0 +1,198 @@
+// scripts/public-url-lease.mts
+import fs2 from "node:fs";
+import path2 from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+// server/src/local/public-url-lease.ts
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+// shared/local-public-url-lease.ts
+function publicLeaseAddress(value) {
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) return null;
+    return url.href.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+function parsePublicUrlLease(raw) {
+  try {
+    const lease = JSON.parse(raw ?? "");
+    if (!lease || typeof lease.runId !== "string" || !lease.runId || typeof lease.owner !== "string" || !lease.owner || !Number.isFinite(lease.expiresAt)) return null;
+    const url = publicLeaseAddress(lease.url);
+    return url ? { runId: lease.runId, owner: lease.owner, expiresAt: lease.expiresAt, url } : null;
+  } catch {
+    return null;
+  }
+}
+
+// server/src/local/public-url-lease.ts
+var LEASE_TTL_MS = 15e3;
+function read(file) {
+  try {
+    return parsePublicUrlLease(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function locked(file, operation) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 448 });
+  const lock = `${file}.lock`;
+  try {
+    if (Date.now() - fs.statSync(lock).mtimeMs > 6e4) fs.rmdirSync(lock);
+  } catch {
+  }
+  fs.mkdirSync(lock, { mode: 448 });
+  try {
+    return operation();
+  } finally {
+    fs.rmdirSync(lock);
+  }
+}
+function write(file, lease) {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temp, JSON.stringify(lease) + "\n", { mode: 384, flag: "wx" });
+    fs.renameSync(temp, file);
+  } finally {
+    try {
+      fs.unlinkSync(temp);
+    } catch {
+    }
+  }
+}
+function acquireLease(file, value, now = Date.now(), ttl = LEASE_TTL_MS) {
+  const url = publicLeaseAddress(value.url);
+  if (!url || !value.owner || !value.runId) throw new Error("Invalid public URL lease");
+  locked(file, () => {
+    const previous = read(file);
+    if (previous && previous.expiresAt > now) throw new Error("A tunnel already owns the public URL");
+    write(file, { ...value, url, expiresAt: now + ttl });
+  });
+}
+function renewLease(file, runId, owner, now = Date.now(), ttl = LEASE_TTL_MS) {
+  return locked(file, () => {
+    const lease = read(file);
+    if (!lease || lease.runId !== runId || lease.owner !== owner || lease.expiresAt <= now) return false;
+    write(file, { ...lease, expiresAt: now + ttl });
+    return true;
+  });
+}
+function releaseLease(file, runId, owner) {
+  return locked(file, () => {
+    const lease = read(file);
+    if (!lease || lease.runId !== runId || lease.owner !== owner) return false;
+    fs.unlinkSync(file);
+    return true;
+  });
+}
+
+// scripts/public-url-lease.mts
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function verify(url, runId) {
+  const response = await fetch(`${url.replace(/\/+$/, "")}/api/health`, { signal: AbortSignal.timeout(3e3) });
+  const health = await response.json();
+  if (!runId || health.localRunId !== runId) throw new Error("Local session identity does not match the running server");
+}
+async function servedByAnother(port, runId) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return false;
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(3e3) });
+    const health = await response.json();
+    return typeof health.version === "string" && (health.localRunId ?? null) !== runId;
+  } catch {
+    return false;
+  }
+}
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command === "discover") {
+    let receipt;
+    if (process.env.COLLOQ_LOCAL_SESSION === "1") {
+      receipt = { runId: process.env.COLLOQ_LOCAL_RUN_ID, leaseFile: process.env.COLLOQ_PUBLIC_URL_LEASE_FILE, url: process.env.COLLOQ_LOCAL_URL, port: Number(process.env.PORT || 3e3), dataDir: process.env.DATA_DIR || path2.resolve("data") };
+    } else {
+      if (!fs2.existsSync(args[0])) {
+        process.exitCode = 2;
+        return;
+      }
+      receipt = JSON.parse(fs2.readFileSync(args[0], "utf8"));
+      if (!alive(Number(receipt.pid))) {
+        if (await servedByAnother(Number(receipt.port), receipt.runId)) {
+          process.exitCode = 2;
+          return;
+        }
+        throw new Error("Local session is no longer running; start colloq first");
+      }
+    }
+    if (!Number.isInteger(receipt.port) || receipt.port < 1 || receipt.port > 65535) throw new Error("Invalid local session port");
+    const values = [receipt.runId, receipt.leaseFile, receipt.url, String(receipt.port), receipt.dataDir];
+    if (values.some((v) => typeof v !== "string" || !v || /[\t\r\n]/.test(v))) throw new Error("Invalid local session receipt");
+    const local = new URL(receipt.url);
+    if (local.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(local.hostname)) throw new Error("Invalid local session URL");
+    await verify(`http://127.0.0.1:${receipt.port}`, receipt.runId);
+    process.stdout.write([...values, local.port || "80"].join("	") + "\n");
+    return;
+  }
+  const [file, runId, owner] = args;
+  if (!file || !runId || !owner) throw new Error("Expected lease file, run ID and owner");
+  if (command === "acquire") {
+    await verify(args[4], runId);
+    acquireLease(file, { runId, owner, url: args[3] });
+    return;
+  }
+  if (command === "release") {
+    releaseLease(file, runId, owner);
+    return;
+  }
+  if (command !== "watch") throw new Error("Unknown lease command");
+  const tunnelPid = Number(args[3]), hostPid = Number(args[4]), healthUrl = args[5];
+  let stopping = false;
+  const finish = () => {
+    if (stopping) return;
+    stopping = true;
+    try {
+      releaseLease(file, runId, owner);
+    } catch {
+    }
+    try {
+      if (alive(tunnelPid)) process.kill(tunnelPid, "SIGTERM");
+    } catch {
+    }
+  };
+  process.once("SIGINT", finish);
+  process.once("SIGTERM", finish);
+  let lastHealthy = Date.now();
+  try {
+    while (!stopping) {
+      if (!alive(tunnelPid) || !alive(hostPid)) break;
+      try {
+        await verify(healthUrl, runId);
+        lastHealthy = Date.now();
+      } catch (error) {
+        if (error instanceof Error && /identity does not match/.test(error.message) || Date.now() - lastHealthy >= LEASE_TTL_MS) throw error;
+        await delay(1e3);
+        continue;
+      }
+      if (stopping || !renewLease(file, runId, owner)) break;
+      await delay(3e3);
+    }
+  } finally {
+    finish();
+  }
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

colloq/_app/kernel/Dockerfile

@@ -0,0 +1,93 @@
+# Поверх чего собираемся — параметр, и это весь механизм наследования.
+#
+# Родитель по умолчанию — python-slim, то есть ровно прежняя сборка. Но им
+# может быть и готовый colloq-образ (`--build-arg PARENT=colloq-kernel:base-gpu`),
+# и тогда тот же самый файл делает не базу, а тонкий слой поверх неё: torch с
+# CUDA остаётся в родителе и не ставится заново.
+ARG PARENT=python:3.11-slim-bookworm
+FROM ${PARENT}
+
+# Родитель может быть нашим собственным образом, а в нём последним стоит
+# `USER runner` — от него ни apt, ни pip не пройдут. На python-slim эта строка
+# не меняет ничего: там и так root.
+USER root
+
+# MPLBACKEND здесь НЕТ, и это правка по живому семинару.
+#
+# Стояло `MPLBACKEND=Agg` — переменная действует на весь контейнер, в том числе
+# на ядро, а Agg рисует в файл и не отдаёт ничего наружу. Значит `plt.show()` в
+# ячейке не давал ни одного сообщения display_data: график не появлялся, ошибки
+# не было, ячейка честно отчитывалась «выполнена». Проверено на живой машине:
+# с Agg ядро отвечает одним `stream`, без переменной — `display_data` с
+# image/png.
+#
+# Не задано — и правильно: внутри ядра matplotlib сам берёт inline-бэкенд
+# (matplotlib_inline приезжает с ipykernel), а в обычном `python script.py`,
+# где экрана нет, — тот же Agg. Обе стороны получают то, что им нужно, без
+# переменной; задать её глобально значит выбрать одно из двух за оба случая.
+# А PLOTLY_RENDERER — есть, и это правка ровно по тому же месту, что абзац выше.
+#
+# Без неё plotly решает сам, чем отдавать фигуру, и решает по-разному в разных
+# версиях: 7.x в ipykernel отдаёт только `application/vnd.plotly.v1+json` — то,
+# из чего тетрадь рисует интерактивный график, — а 5.x добавляет к нему
+# `text/html` со скриптом и первым кадром высылает ВЕСЬ бандл plotly.js, пять
+# мегабайт. Скрипты из вывода Colloq не исполняет никогда (SECURITY.md), так
+# что эти пять мегабайт — чистый вес в общем документе, который едет каждому в
+# комнате.
+#
+# `plotly_mimetype` — не запрет, а умолчание: студент перебивает его строкой
+# `pio.renderers.default = "png"`, и это продолжает работать. Ту же переменную
+# ставит сервер при подъёме контейнера комнаты (kernel/pool.ts · runArgs) —
+# ради чужих окружений, собранных без этого файла.
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PLOTLY_RENDERER=plotly_mimetype
+
+# Оба шага ниже повторяются на каждом слое цепочки, и это дёшево: на готовом
+# родителе curl уже стоит (apt-get тратит секунды на индексы и отвечает
+# «already the newest version»), а pip на каждую строку базы отвечает
+# «Requirement already satisfied» и ничего не качает. Минуты стоит только то,
+# чего в родителе нет, — ради этого наследование и заведено.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends curl libgomp1 \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt
+
+# Окружение семинара — слой поверх базы, а не вместо неё.
+#
+# Два слоя, а не один, ради кеша: база одинакова у всех окружений, поэтому
+# docker переиспользует её, и «завести окружение» стоит только тех пакетов,
+# которых в базе нет. Один общий слой пересобирался бы целиком на каждую
+# правку списка, а это pandas и scikit-learn заново.
+#
+# Копируется ровно выбранный файл, а не вся папка: иначе правка чужого
+# окружения сбрасывала бы кеш этому.
+ARG KERNEL_ENV=base
+COPY environments/${KERNEL_ENV}.txt /tmp/environment.txt
+RUN pip install --no-cache-dir -r /tmp/environment.txt
+
+# Student code runs as this user; it owns nothing outside /workspace.
+#
+# Идемпотентно: на втором слое цепочки runner уже заведён родителем, а второй
+# `useradd` падает «already exists» и роняет сборку целиком.
+RUN if ! id -u runner >/dev/null 2>&1; then useradd --create-home --uid 1000 runner; fi \
+ && mkdir -p /workspace \
+ && chown runner:runner /workspace
+USER runner
+WORKDIR /workspace
+
+EXPOSE 8888
+HEALTHCHECK --interval=5s --timeout=3s --start-period=20s --retries=12 \
+  CMD curl -fsS "http://localhost:8888/api/status?token=${JUPYTER_TOKEN}" || exit 1
+
+CMD ["sh", "-c", "exec jupyter server \
+  --ServerApp.ip=0.0.0.0 \
+  --ServerApp.port=8888 \
+  --ServerApp.root_dir=/workspace \
+  --ServerApp.allow_remote_access=True \
+  --ServerApp.allow_origin='*' \
+  --ServerApp.disable_check_xsrf=True \
+  --IdentityProvider.token=\"$JUPYTER_TOKEN\" \
+  --no-browser"]

colloq/_app/kernel/environments/base-gpu.txt

@@ -0,0 +1,21 @@
+# Тяжёлая половина всех GPU-окружений: torch с CUDA, и больше ничего.
+#
+# colloq: gpu
+#
+# Строка выше — не комментарий, а директива: комната на этом окружении получает
+# срез из KERNEL_GPUS на всё время жизни своего контейнера, а если свободных
+# срезов нет — честно не открывается. Отката на процессор здесь нет и быть не
+# может: колёса ниже собраны под CUDA. Признак наследуется, поэтому окружениям
+# поверх этого повторять его не нужно.
+#
+# Отдельным окружением, а не строками в каждом GPU-списке, ровно по одной
+# причине. Слой окружения один, и любая правка списка ставит его целиком
+# заново: добавить timm или поднять версию transformers стоило трёх гигабайт
+# колёс и девяти минут — каждый раз. Здесь они лежат один раз, а окружения
+# сверху (`# colloq: from base-gpu`) собираются за секунды.
+#
+# Обычный индекс pypi, а не .../whl/cpu, как в cv: именно там колёса с CUDA.
+# Драйвер приходит с хоста через nvidia-container-toolkit, ставить его в образ
+# не надо. Первая сборка идёт долго, дальше образ лежит в кеше docker.
+torch>=2.4
+torchvision>=0.19

colloq/_app/kernel/environments/base.txt

@@ -0,0 +1,12 @@
+# Базовое окружение — то, что стоит в каждом семинаре и так.
+#
+# Здесь намеренно пусто. Ядро всегда ставит kernel/requirements.txt (jupyter,
+# numpy, pandas, matplotlib, plotly, scikit-learn), а этот файл добавляется сверху.
+# Пустой файл значит «ничего сверх базы» — и образ собирается за секунды.
+#
+# Чтобы завести своё окружение, не редактируйте этот файл:
+#
+#     make env-new NAME=cv     # создаст kernel/environments/cv.txt
+#     make env-use NAME=cv     # соберёт образ и сделает его умолчанием
+#                              # для НОВЫХ семинаров
+seaborn

colloq/_app/kernel/environments/cv.txt

@@ -0,0 +1,15 @@
+# Компьютерное зрение. Пример настоящего окружения — можно удалить.
+#
+# Ставится поверх базы, поэтому numpy/pandas/matplotlib перечислять не нужно.
+# Сборка тянет около двух гигабайт: первый `make env-use NAME=cv` идёт долго,
+# дальше образ лежит в кеше docker, и следующий семинар на нём заводится сразу.
+# Открытых семинаров это не касается: окружение выбирают семинару при создании,
+# и дальше оно не меняется.
+
+# CPU-сборка: колёса для GPU весят втрое больше и на ноутбуке бесполезны.
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch>=2.4
+torchvision>=0.19
+timm>=1.0
+pillow>=10.3
+opencv-python-headless>=4.10

colloq/_app/kernel/environments/gpu.txt

@@ -0,0 +1,17 @@
+# Нейросети на GPU. Образец окружения со срезом видеокарты — можно удалить.
+#
+# colloq: from base-gpu
+#
+# Строка выше — не комментарий, а директива: этот слой строится поверх образа
+# base-gpu, где torch с CUDA уже стоит. Поэтому здесь только лёгкое сверху, и
+# правка этого списка — секунды, а не девять минут на три гигабайта колёс.
+#
+# Срез видеокарты приходит оттуда же: base-gpu объявляет `# colloq: gpu`, и
+# признак наследуется — комната на этом окружении получает срез из KERNEL_GPUS
+# на всё время жизни своего контейнера, а если свободных нет, честно не
+# открывается. Отката на процессор здесь нет: колёса собраны под CUDA.
+#
+# `make env-build NAME=gpu` первым делом соберёт base-gpu, если его образа ещё
+# нет: это те самые девять минут — но один раз, а не на каждую правку.
+transformers>=4.44
+accelerate>=0.33

colloq/_app/kernel/environments/kaggle-base.txt

@@ -0,0 +1,20 @@
+# Colloq: lightweight Kaggle-style CPU stack, verified without network.
+# This is not the official Kaggle image.
+# colloq: from base
+numpy==2.4.6
+pandas==3.0.6
+scipy==1.17.1
+scikit-learn==1.9.1
+catboost==1.2.10
+lightgbm==4.6.0
+xgboost==3.2.0
+optuna==4.9.0
+polars==1.44.2
+pyarrow==23.0.1
+statsmodels==0.15.0
+imbalanced-learn==0.14.2
+category-encoders==2.11.1
+shap==0.51.0
+h3==4.5.0
+nbclient==0.11.0
+nbformat==5.11.1

colloq/_app/kernel/environments/pvz-geo.txt

@@ -0,0 +1,6 @@
+# Геопрогноз спроса ПВЗ: CPU, квантильный бустинг и spatial CV.
+# colloq: from base
+lightgbm==4.6.0
+h3>=4.2,<5
+nbclient>=0.10,<1
+nbformat>=5.10,<6

colloq/_app/kernel/requirements.txt

@@ -0,0 +1,18 @@
+jupyter-server>=2.14,<3
+ipykernel>=6.29
+numpy>=1.26
+pandas>=2.2
+matplotlib>=3.8
+# Интерактивные графики. В базе, а не в окружении, по той же причине, что и
+# matplotlib: `px.histogram(df, x=...)` пишут на первом же семинаре по данным, и
+# «поставьте себе plotly» — не тот ответ, который даёт преподаватель классу
+# посреди пары. Тетрадь рисует фигуру сама (shared/plotly.ts), и ядро для этого
+# должно уметь её отдать.
+#
+# `narwhals` и `packaging` приезжают зависимостями plotly; pandas уже выше.
+plotly>=6.0
+scikit-learn>=1.4
+requests>=2.32
+# Форматирование ноутбука кнопкой FORMAT. Живёт в базе, а не в окружении:
+# кнопка есть в каждой комнате, значит и инструмент должен быть везде.
+black>=24.4

colloq/_app/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "colloq",
+  "version": "0.2.0",
+  "private": true,
+  "type": "module",
+  "description": "Colloq — собранное приложение. Зависимости ставит colloq при первом запуске.",
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "better-sqlite3": "^13.0.3",
+    "busboy": "^1.6.0",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "lib0": "^0.2.99",
+    "openai": "^4.77.0",
+    "satori": "^0.33.4",
+    "ws": "^8.18.0",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.21"
+  }
+}

colloq/_app/scripts/backup-local.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# Копия занятия на этой машине: база одним файлом и архив со всем, чего в базе
+# нет. Пара к `colloq restore --legacy` (scripts/restore.sh).
+#
+#   ./scripts/backup-local.sh    снять копию в <состояние>/backups/
+#   colloq backup                у преподавателя это он
+#   make backup-legacy           в репозитории это он же, обёрткой в одну строку
+#
+# Почему отдельным файлом, а не рецептом в Makefile, где он прожил до сих пор.
+# В колесо pip едут приложение и scripts/ — Makefile не едет и не поедет
+# (scripts/pack.mts · SCRIPTS), а `colloq backup` у поставленного colloq звал
+# make и умирал на «command not found» — на той единственной команде, которой
+# преподаватель уносит семестр с машины. То же самое и по той же причине уже
+# сделано с restore-legacy и с host: одно описание, один файл.
+#
+# ----------------------------------------------------------------- два корня
+#
+# Каталог ПРИЛОЖЕНИЯ — тот, что над scripts/: web/dist, kernel/, эти скрипты.
+# Он приезжает с пакетом и сносится целиком следующим `pip install -U`.
+# Каталог СОСТОЯНИЯ — .env, data/, workspace/, свои окружения, backups/ — живёт
+# отдельно (~/.colloq или COLLOQ_HOME) и обновления переживает.
+#
+# Копия снимается ЦЕЛИКОМ с состояния, и адрес его здесь не вычисляется: его
+# знает scripts/lib.sh (COLLOQ_STATE_ROOT), второго ответа на один вопрос быть
+# не должно. В репозитории оба корня — один и тот же каталог, и там не сдвинулся
+# ни один путь.
+#
+# Имена в архиве — тоже от корня состояния: развернуть его надо будет там же.
+#
+# ------------------------------------------------------------ что и почему
+#
+# Копия ЗДЕШНЕГО инстанса, и кладётся она в корень backups/. У среды на
+# арендованной машине есть имя и свой подкаталог (backups/demo/ — туда пишет
+# make vast-sync), а у этой машины имени нет: корень и есть её место. Так корень
+# и подкаталоги не мешают друг другу — «последняя копия» одной среды никогда не
+# окажется копией другой.
+#
+# VACUUM INTO читает согласованный снимок и пишет один готовый файл. Копия
+# самого colloq.db этого не даёт: в режиме WAL половина дня лежит в журнале
+# рядом, и файл, скопированный на ходу, отстаёт на часы. Проверено.
+#
+# Вторым файлом рядом — архив со всем, чего в базе нет: workspace (то, что
+# загрузили в комнаты), файлы соревнований, wheel-наборы, ключ подписи и токен
+# установки. Раньше README звал копировать папку руками, и это был ровно тот шаг, который пропускают: база
+# без workspace — это тетради со ссылками на файлы, которых больше нет, а база
+# без ключа подписи — инстанс, где все выданные ссылки мертвы. На арендованной
+# машине, которую уничтожают после пары, цена такой забывчивости — весь семестр
+# разом.
+#
+# Оба файла 0600 и не «файлы занятия»: в них лежат ключи от инстанса.
+#
+# В базе — сами занятия, преподаватели, история версий и настройки оракула.
+# Слои Docker-образов не копируются. Закреплённый image ID в базе — ссылка,
+# а не содержимое образа: для воспроизводимости старых посылок сохраните сами
+# образы в registry либо отдельно через docker image save/load. Пересборка
+# списка пакетов не гарантирует прежний image ID или состав окружения.
+#
+# ------------------------------------------------------- списки окружений
+#
+# Каталогов со списками пакетов на машине ДВА, и в копию идёт только второй:
+#
+#   <приложение>/kernel/environments   привезённые с продуктом (base, cv, gpu).
+#       Копировать нечего: они приедут снова с любой установкой пакета.
+#   <состояние>/environments           заведённые человеком. Вот их и нет
+#       больше нигде — разбор, почему каталог отдельный, у ownEnvDir в
+#       cli/src/env.ts.
+#
+# В репозитории это ОДИН каталог, kernel/environments, и в архив он идёт
+# целиком — ровно как раньше.
+#
+# Почему списки вообще в копии: их правят и заводят из панели прямо на той
+# машине, где идут занятия (окно «Окружения» пишет <имя>.txt на хосте), и взять
+# их больше неоткуда — в репозитории лежат только те, что приехали с ноутбука.
+# Образы по ним пересобираются одной командой, а штампы `.<имя>.built` остаются
+# машине: они про её образ, а не про список.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+RED=$'\033[31m'; DIM=$'\033[2m'; BOLD=$'\033[1m'; OFF=$'\033[0m'
+say() { printf '%s\n' "$*"; }
+die() { printf '%s%s%s\n' "$RED" "$*" "$OFF" >&2; exit 1; }
+
+# Корень состояния — общий ответ на всех: scripts/lib.sh, тот же, что у host.sh
+# и restore.sh.
+. ./scripts/lib.sh
+
+APP="$PWD"
+STATE="$(cd "$COLLOQ_STATE_ROOT" 2>/dev/null && pwd || true)"
+# Скобки у имени обязательны: следом идёт «»», а его первый байт bash считает
+# частью имени переменной и падает на «unbound variable» вместо отказа по делу.
+# Тем же приёмом и по той же причине пишет restore.sh.
+[ -n "$STATE" ] || die "no state directory \"${COLLOQ_STATE_ROOT}\" — check COLLOQ_HOME."
+
+# Свои окружения: в репозитории прежний kernel/environments, у поставленного
+# пакета — <состояние>/environments (см. шапку).
+if [ "$STATE" = "$APP" ]; then ENV_LISTS=kernel/environments; else ENV_LISTS=environments; fi
+
+# Дальше всё считается от корня состояния — как раньше считалось от корня
+# репозитория. Один переход вместо префикса в каждой строке: и имена в архиве
+# получаются относительными сами собой.
+cd "$STATE"
+
+# Без базы копировать нечего, и сказать об этом надо вслух. VACUUM INTO над
+# несуществующим файлом молча заводит пустую базу и так же молча пишет пустую
+# «копию» — у поставленного colloq с разъехавшимися корнями это выглядело бы
+# как удачная копия пустого места.
+[ -f data/colloq.db ] || die "no data/colloq.db in $STATE — there is nothing to back up.
+  This is the directory that holds the .env of the class; for an installed colloq
+  its address is COLLOQ_HOME."
+
+mkdir -p backups
+stamp="$(date +%Y%m%d-%H%M%S)"
+out="backups/colloq-$stamp.db"
+files="backups/colloq-$stamp-files.tar.gz"
+
+# Как назвать копию человеку. В репозитории — как и раньше, от корня: `backups/…`
+# и есть путь от того каталога, в котором стоит человек. У поставленного colloq
+# состояние лежит в ~/.colloq, а человек стоит где угодно, и относительное имя
+# указывало бы на несуществующий backups/ рядом с ним — в том числе в подсказке
+# «развернуть обратно», которую копируют целиком.
+if [ "$STATE" = "$APP" ]; then SHOW=""; else SHOW="$STATE/"; fi
+
+# Путь уходит внутрь строки SQL, а приходит он теперь снаружи (COLLOQ_HOME):
+# одиночная кавычка в имени домашнего каталога закрыла бы строку посреди пути.
+# В SQL её удваивают.
+sql_out="$PWD/$out"
+sqlite3 data/colloq.db "VACUUM INTO '${sql_out//\'/\'\'}'" \
+  || die "did not work. sqlite3 is needed — brew install sqlite"
+# Копия базы такая же секретная, как сама база: в ней ключи входа для
+# преподавателей и ключ оракула, если его задавали в панели. VACUUM INTO
+# создаёт файл с обычными правами, поэтому 0600 ставим сами.
+chmod 600 "$out"
+printf '%sbackup:%s %s %s(%s)%s\n' "$BOLD" "$OFF" "$SHOW$out" "$DIM" "$(du -h "$out" | cut -f1)" "$OFF"
+
+back="colloq restore --legacy --db $SHOW$out"
+set --
+for p in workspace data/competitions data/dependencies data/session-secret data/setup-token "$ENV_LISTS"/*.txt; do
+  if [ -e "$p" ]; then set -- "$@" "$p"; fi
+done
+if [ $# -gt 0 ]; then
+  # Код tar разбирается, а не глотается: `set -e` иначе уронил бы скрипт на
+  # единице, которая здесь — не отказ (см. ниже).
+  code=0
+  tar -czf "$files" "$@" || code=$?
+  chmod 600 "$files" 2>/dev/null || true
+  [ "$code" -le 1 ] || die "could not take the class files — the backup is incomplete"
+  # Код 1 у tar это «файл менялся, пока его читали»: на ходу занятие пишет в
+  # workspace, и это нормально. Архив при этом годен, но об одном-двух файлах в
+  # нём знать стоит.
+  if [ "$code" -eq 1 ]; then
+    say "${DIM}some files changed while they were being copied — a class is running${OFF}"
+  fi
+  printf '%sfiles:%s  %s %s(%s)%s\n' "$BOLD" "$OFF" "$SHOW$files" "$DIM" "$(du -h "$files" | cut -f1)" "$OFF"
+  # Оба файла названы в одной строке нарочно: разворачивать их надо парой, а
+  # искать вторую по имени первой человеку незачем.
+  back="$back --files $SHOW$files"
+fi
+
+# Куда идти обратно. Прежняя подсказка звала `make restore`, а эта цель давно
+# про переносимую копию k3s и на паре файлов отвечает «ARCHIVE is required»;
+# make к тому же есть не у всех, кто эту копию снял. Пути — от корня состояния,
+# то есть от того каталога, в котором они и лежат.
+say "${DIM}restore it back: $back${OFF}"

colloq/_app/scripts/backup.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Cluster application backup. MODE=live (default) or MODE=consistent.
+# Consistent mode stops app, broker and every room; RESUME=1 explicitly starts
+# the application afterwards. Failure leaves writers stopped for investigation.
+set -euo pipefail
+SCRIPT_PATH="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+cd "$(dirname "$0")/.."
+umask 077
+STATE="${COLLOQ_STATE_DIR:-/var/lib/colloq}"
+MODE="${MODE:-live}"
+NAME="${NAME:-}"
+case "$MODE" in live|consistent) ;; *) echo 'MODE must be live or consistent' >&2; exit 1;; esac
+case "$NAME" in *[!A-Za-z0-9-]*|-*|*-) echo 'invalid environment name' >&2; exit 1;; esac
+RELEASE="${RELEASE:-$STATE/releases/current.json}"
+[ -f "$RELEASE" ] || { echo 'No installed release. Local backup: colloq backup (make backup-legacy); cluster backup needs an installed release.' >&2; exit 1; }
+OUT="${OUT:-backups${NAME:+/$NAME}/colloq-$(date -u +%Y%m%dT%H%M%SZ)-$MODE.tar.gz}"
+mkdir -p "$STATE"
+if ! python3 scripts/state-lock.py held --state "$STATE"; then
+  exec python3 scripts/state-lock.py run --state "$STATE" -- bash "$SCRIPT_PATH" "$@"
+fi
+[ ! -e "$STATE/.restore-in-progress" ] && [ ! -L "$STATE/.restore-in-progress" ] || { echo 'An interrupted restore must be recovered before backup.' >&2; exit 1; }
+extra=()
+if [ "$MODE" = consistent ]; then
+  bash scripts/cluster.sh stop
+  extra+=(--quiesced)
+  echo 'Consistent backup: all writers stopped; active kernel memory is discarded.' >&2
+else
+  echo 'Live backup: SQLite snapshot is consistent; workspace files are copied at different instants.' >&2
+fi
+python3 scripts/runtime-backup.py backup --root "$STATE" --release "$RELEASE" --output "$OUT" --mode "$MODE" --name "$NAME" "${extra[@]}"
+python3 scripts/runtime-backup.py validate --archive "$OUT" --name "$NAME" >&2
+if [ "$MODE" = consistent ]; then
+  if [ "${RESUME:-}" = 1 ]; then bash scripts/cluster.sh start; else echo 'Writers remain stopped. Resume: bash scripts/cluster.sh start' >&2; fi
+fi