colloq 0.2.0__py3-none-any.whl

colloq/__init__.py

@@ -0,0 +1,12 @@
+"""Colloq — совместная среда для семинаров.
+
+Пакет не содержит логики занятия: она вся в CLI, который лежит рядом собранным
+(_app/cli/colloq.mjs) и исполняется Node. Здесь только упаковка — то, что
+позволяет поставить всё это одной строкой `pip install colloq`.
+
+Точка входа: colloq.__main__:main.
+"""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

colloq/__main__.py

@@ -0,0 +1,315 @@
+"""Шим: найти Node, при первом запуске поставить node_modules, отдать управление CLI.
+
+Больше здесь не происходит ничего, и это намеренно. Логика занятия — сборка,
+ядра, порты, туннель, остановка — живёт в CLI (_app/cli/colloq.mjs, собран из
+cli/src) и в супервизоре занятия, которым пользуется и `npm run dev` в
+репозитории. Второй, питонский, слой правил означал бы две программы на одно
+дело, и чинить пришлось бы обе.
+
+Что шим делает по шагам:
+
+  1. ищет node — сначала в PATH, потом там, где его кладут установщики;
+     проверяет, что версия не ниже 22 (better-sqlite3 13 заявляет node >=22, а
+     на 18 сервер и вовсе падает на ходу, а не при старте);
+  2. если рядом с приложением нет node_modules — ставит их один раз npm-ом и
+     говорит об этом вслух: молчаливая минута на первом запуске читается как
+     «зависло»;
+  3. выставляет COLLOQ_APP_DIR (где лежит приложение) и COLLOQ_CWD (откуда
+     позвали);
+  4. заменяет собой процесс Node через execve — чтобы Ctrl+C уходил прямо в
+     CLI, а код возврата приходил прямо от него. Прослойка-надзиратель здесь
+     сломала бы и то, и другое: Ctrl+C на паре означает «сохрани и останови
+     занятие», и он должен дойти до того, кто умеет это сделать.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Iterator, NoReturn, Optional, Tuple
+
+#: Приложение лежит внутри пакета: так его кладёт в колесо scripts/pack.mts.
+APP = Path(__file__).resolve().parent / "_app"
+ENTRY = APP / "cli" / "colloq.mjs"
+MARK = APP / ".colloq-dist.json"
+STAMP = APP / ".node-modules.json"
+LOCK = APP / ".node-modules.lock"
+
+#: Ниже 22 не бывает: better-sqlite3 13 заявляет node >=22 (server/package.json),
+#: и это же версия образа в Dockerfile. С 13-й он на N-API: один готовый бинарь
+#: на все версии Node выше, и пересборка под «свой» Node преподавателю не грозит.
+MIN_NODE = 22
+#: Сколько ждать чужую установку, прежде чем считать замок брошенным.
+LOCK_WAIT_SEC = 900
+#: Слова, ради которых незачем ставить окружение: они только рассказывают.
+#: `colloq --help` сразу после установки — самое частое первое действие, и
+#: минута npm в ответ на просьбу показать список команд была бы издевательством.
+#: Сам CLI собран без единой внешней зависимости (это стережёт scripts/pack.mts),
+#: так что ответить ему есть чем и без node_modules.
+#:
+#: Голый `colloq` в этот список НЕ входит, хотя тоже только рассказывает. Он —
+#: первое, что набирают после `pip install colloq`, и это лучший момент для
+#: разовой минуты: занятие начинается словом `colloq start`, и вот тогда ждать
+#: уже нечего — до пары остаются минуты, а не вечер.
+TELLING = frozenset(["--help", "-h", "help", "--version", "-V"])
+
+
+def fail(*lines: str) -> NoReturn:
+    """Отказ словами, без трассировки: её здесь некому читать."""
+    for line in lines:
+        print(line, file=sys.stderr, flush=True)
+    raise SystemExit(3)
+
+
+def _version_key(path: Path) -> Tuple[int, ...]:
+    """Ключ сортировки для каталогов вида node-20.11.1: числами, а не строкой."""
+    numbers = re.findall(r"\d+", str(path))
+    return tuple(int(number) for number in numbers[-3:]) or (0,)
+
+
+def _candidates() -> Iterator[str]:
+    """Где бывает node, в порядке убывания доверия.
+
+    PATH — первым: если преподаватель поставил себе Node сам, он ожидает именно
+    свой. Дальше обычные места установщиков: тот же Homebrew кладёт node в
+    /opt/homebrew/bin, которого нет в PATH у процессов, запущенных не из
+    оболочки, — а pip-скрипт вполне может быть запущен из чего угодно.
+    Менеджеры версий (nvm, fnm, volta, asdf) перебираются последними и сверху
+    вниз по версии: у них node в PATH появляется только после `source`, и без
+    этого списка `colloq` в свежем терминале говорил бы «поставьте Node»
+    человеку, у которого он стоит.
+    """
+    found = shutil.which("node")
+    if found:
+        yield found
+    for fixed in (
+        "/opt/homebrew/bin/node",
+        "/usr/local/bin/node",
+        "/usr/bin/node",
+        "/opt/local/bin/node",
+        "/snap/bin/node",
+    ):
+        yield fixed
+    home = Path.home()
+    for pattern in (
+        ".nvm/versions/node/*/bin/node",
+        ".local/share/fnm/node-versions/*/installation/bin/node",
+        ".fnm/node-versions/*/installation/bin/node",
+        ".volta/tools/image/node/*/bin/node",
+        ".asdf/installs/nodejs/*/bin/node",
+    ):
+        for path in sorted(home.glob(pattern), key=_version_key, reverse=True):
+            yield str(path)
+
+
+def _node_version(node: str) -> Optional[Tuple[int, int, int]]:
+    try:
+        done = subprocess.run(
+            [node, "--version"], capture_output=True, text=True, timeout=15
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    match = re.match(r"v(\d+)\.(\d+)\.(\d+)", (done.stdout or "").strip())
+    if done.returncode != 0 or not match:
+        return None
+    return (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+
+
+def find_node() -> str:
+    """Первый работающий node не ниже MIN_NODE.
+
+    Отдельно разбирается случай «node есть, но старый»: сказать такому человеку
+    «Node не найден» — значит отправить его ставить второй раз то, что у него
+    стоит, и удивляться, почему не помогает.
+    """
+    seen = set()
+    old: Optional[str] = None
+    for candidate in _candidates():
+        if candidate in seen:
+            continue
+        seen.add(candidate)
+        if not os.path.isfile(candidate) or not os.access(candidate, os.X_OK):
+            continue
+        version = _node_version(candidate)
+        if version is None:
+            continue
+        if version[0] >= MIN_NODE:
+            return candidate
+        if old is None:
+            old = "%s (v%d.%d.%d)" % (candidate, version[0], version[1], version[2])
+    if old:
+        fail(
+            "Node is too old: " + old,
+            "Colloq needs Node %d or newer." % MIN_NODE,
+            "macOS: brew install node · Debian/Ubuntu: see https://nodejs.org/en/download",
+        )
+    fail(
+        "Node.js not found — Colloq cannot start without it.",
+        "Node %d or newer is required." % MIN_NODE,
+        "macOS: brew install node · Debian/Ubuntu: apt install nodejs (or https://nodejs.org/en/download)",
+        "If Node is installed somewhere unusual, add it to PATH.",
+    )
+
+
+def find_npm(node: str) -> Optional[str]:
+    """npm рядом с node или в PATH.
+
+    Рядом — первым: у менеджеров версий (nvm, fnm) в PATH может лежать npm от
+    совсем другой версии Node, и ставить нативные модули той версией, которой
+    их потом не запускать, — это тихая поломка better-sqlite3 на ровном месте.
+    """
+    names = ["npm.cmd", "npm"] if os.name == "nt" else ["npm"]
+    for name in names:
+        near = Path(node).parent / name
+        if near.is_file():
+            return str(near)
+    for name in names:
+        found = shutil.which(name)
+        if found:
+            return found
+    return None
+
+
+def _wanted() -> dict:
+    """Чего ждут node_modules: версия приложения и список зависимостей.
+
+    Сравнивается целиком, а не «каталог существует»: после обновления колеса
+    приложение новое, а node_modules рядом — от прошлой версии, и они молча
+    подходят по именам, но не по содержимому.
+    """
+    data = json.loads((APP / "package.json").read_text(encoding="utf-8"))
+    return {
+        "version": data.get("version"),
+        "dependencies": data.get("dependencies", {}),
+    }
+
+
+def _ready(wanted: dict) -> bool:
+    if not (APP / "node_modules").is_dir():
+        return False
+    try:
+        return json.loads(STAMP.read_text(encoding="utf-8")) == wanted
+    except (OSError, ValueError):
+        return False
+
+
+def _install(npm: str, wanted: dict) -> None:
+    # flush у каждой строки — не суеверие. Дальше идёт чужой процесс (npm), а
+    # в конце os.execve, который выбрасывает буфер стандартного вывода не
+    # напечатав: при выводе в файл или в конвейер обе эти строки пропадали
+    # целиком, и разовая минута ожидания выглядела зависанием без объяснений.
+    print("Installing Colloq's Node environment — once, a minute or two.", flush=True)
+    print("Directory: %s" % APP, flush=True)
+    done = subprocess.run(
+        [npm, "install", "--omit=dev", "--no-audit", "--no-fund"],
+        cwd=str(APP),
+    )
+    if done.returncode != 0:
+        fail(
+            "",
+            "Could not install the Node environment (npm exited with %d)." % done.returncode,
+            "Run it by hand: cd %s && npm install --omit=dev" % APP,
+        )
+    STAMP.write_text(json.dumps(wanted, ensure_ascii=False, indent=2), encoding="utf-8")
+    print("Environment ready.\n", flush=True)
+
+
+def ensure_modules(node: str) -> None:
+    """node_modules рядом с приложением — ставятся один раз, на этой машине.
+
+    Почему их нет в колесе: better-sqlite3 и @resvg/resvg-js — нативные, и
+    колесо с ними перестало бы быть одним на всех (своё на macOS arm64, своё на
+    Linux x86_64, своё на каждую версию Node ABI). Цена такого решения — одна
+    минута на первом запуске, и она названа вслух, а не проведена молча.
+    """
+    wanted = _wanted()
+    if _ready(wanted):
+        return
+    npm = find_npm(node)
+    if not npm:
+        fail(
+            "No npm next to Node, and the server environment cannot be installed without it.",
+            "npm normally ships with Node: check `npm --version`.",
+            "What should happen: cd %s && npm install --omit=dev" % APP,
+        )
+    if not os.access(str(APP), os.W_OK):
+        fail(
+            "The application directory is read-only: %s" % APP,
+            "The first run installs the server's node_modules there, so it needs to be writable.",
+            "Install Colloq into an environment of your own (python3 -m venv ~/colloq && ~/colloq/bin/pip install colloq),",
+            "or pip install --user colloq — and run it as yourself.",
+        )
+    # Замок на случай двух терминалов сразу: npm в одном каталоге двумя
+    # процессами — это половина дерева от одного и половина от другого.
+    deadline = time.time() + LOCK_WAIT_SEC
+    while True:
+        try:
+            handle = os.open(str(LOCK), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+        except FileExistsError:
+            if _ready(wanted):
+                return
+            try:
+                stale = time.time() - LOCK.stat().st_mtime > LOCK_WAIT_SEC
+            except OSError:
+                stale = False
+            if stale:
+                LOCK.unlink(missing_ok=True)
+                continue
+            if time.time() > deadline:
+                fail(
+                    "Another process is already installing the Node environment, and it is taking too long.",
+                    "If that process died, remove the lock: rm %s" % LOCK,
+                )
+            print("Another run is installing the Node environment — waiting…", flush=True)
+            time.sleep(2)
+            continue
+        os.close(handle)
+        try:
+            if _ready(wanted):
+                return
+            _install(npm, wanted)
+        finally:
+            LOCK.unlink(missing_ok=True)
+        return
+
+
+def main() -> int:
+    if not ENTRY.is_file() or not MARK.is_file():
+        fail(
+            "The package carries no built application (%s)." % APP,
+            "That happens to a wheel built without `make pack`. Rebuild it: make wheel.",
+        )
+    node = find_node()
+    arguments = sys.argv[1:]
+    if not arguments or not set(arguments) & TELLING:
+        ensure_modules(node)
+
+    environment = dict(os.environ)
+    # Где лежит приложение. Всё остальное — состояние занятия — CLI ищет сам:
+    # у него для этого COLLOQ_HOME.
+    environment["COLLOQ_APP_DIR"] = str(APP)
+    # Каталог, из которого позвали: относительные пути в аргументах
+    # (`colloq restore --db backups/…`) должны считаться от него, а не от
+    # приложения.
+    environment.setdefault("COLLOQ_CWD", os.getcwd())
+
+    argv = [str(node), str(ENTRY)] + arguments
+    # Перед подменой процесса — вытолкнуть всё своё: execve не возвращается и
+    # ничего не дописывает.
+    sys.stdout.flush()
+    sys.stderr.flush()
+    if os.name == "nt":
+        # На Windows execve не заменяет процесс, а порождает второй, и родитель
+        # возвращается немедленно: там приходится ждать ребёнка руками.
+        return subprocess.call(argv, env=environment)
+    os.execve(str(node), argv, environment)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

colloq/_app/.colloq-dist.json

@@ -0,0 +1,66 @@
+{
+  "name": "colloq",
+  "version": "0.2.0",
+  "builtAt": "2026-09-23T12:57:49.000Z",
+  "builtBy": "scripts/pack.mts",
+  "node": "v22.23.2",
+  "layout": {
+    "cli": "cli/colloq.mjs",
+    "launch": "cli/launch.mjs",
+    "lease": "cli/public-url-lease.mjs",
+    "server": "server/dist/server.js",
+    "web": "web/dist",
+    "kernel": "kernel",
+    "scripts": "scripts"
+  },
+  "install": {
+    "manager": "npm",
+    "args": [
+      "install",
+      "--omit=dev"
+    ],
+    "cwd": "."
+  },
+  "parts": [
+    {
+      "path": "cli/colloq.mjs",
+      "files": 1,
+      "bytes": 100112
+    },
+    {
+      "path": "cli/launch.mjs",
+      "files": 1,
+      "bytes": 59864
+    },
+    {
+      "path": "cli/public-url-lease.mjs",
+      "files": 1,
+      "bytes": 6892
+    },
+    {
+      "path": "server/dist",
+      "files": 3,
+      "bytes": 5451220
+    },
+    {
+      "path": "server/assets",
+      "files": 5,
+      "bytes": 220703
+    },
+    {
+      "path": "web/dist",
+      "files": 183,
+      "bytes": 17461331
+    },
+    {
+      "path": "kernel",
+      "files": 8,
+      "bytes": 12776
+    },
+    {
+      "path": "scripts",
+      "files": 9,
+      "bytes": 199615
+    }
+  ]
+}

colloq/_app/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Kalashnikov
+
+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.

colloq/_app/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,106 @@
+# Third-party notices
+
+Colloq's own code is licensed under the [MIT License](LICENSE). This repository
+and everything built from it also contain third-party work under other licenses:
+
+- the web bundle (`web/dist`);
+- the server bundle;
+- the Docker images;
+- the pip wheel;
+- the colloq.ru site.
+
+This file lists the assets that are committed to the repository and the
+non-MIT components that ship in the builds.
+
+## Fonts committed to the repository
+
+### JetBrains Mono: SIL Open Font License 1.1
+
+Copyright 2020 The JetBrains Mono Project Authors
+(<https://github.com/JetBrains/JetBrainsMono>).
+
+| Files | License text |
+| --- | --- |
+| `web/public/fonts/jetbrains-mono-*.woff2` | `web/public/fonts/JetBrainsMono-OFL.txt` |
+| `site/fonts/jetbrains-mono-*.woff2` | `site/fonts/JetBrainsMono-OFL.txt` |
+| `server/assets/fonts/JetBrainsMono-Medium.ttf` (link-preview cards) | `server/assets/fonts/JetBrainsMono-OFL.txt` |
+
+### HSE Sans: not covered by the MIT license
+
+| Files |
+| --- |
+| `web/public/fonts/hse-sans-{400,600,700,900}.woff2` |
+| `site/fonts/hse-sans-{400,600,700,900}.woff2` |
+| `server/assets/fonts/HSESans-{Regular,Bold,Black}.otf` |
+
+HSE Sans is the corporate typeface of HSE University (National Research
+University Higher School of Economics). It is **not** covered by this project's
+MIT license, and this repository grants no rights to it: the files are here only
+to render Colloq's own interface. Do not reuse them outside Colloq. A fork that
+needs a freely licensed typeface can swap these files and the `@font-face`
+rules in `web/index.html`, `site/styles.css` and `docs/build.py`; the font stacks
+already fall back to system fonts.
+
+## Other assets committed to the repository
+
+### pdf.js worker: Apache License 2.0
+
+`web/public/pdf/pdf.worker.min.mjs` is copied unmodified from `pdfjs-dist`
+6.2.108 by `npm run pdf:worker` (Copyright Mozilla Foundation). The file keeps
+its license header. License: <https://www.apache.org/licenses/LICENSE-2.0>.
+
+### plotly.js strict bundle: MIT
+
+`web/public/plotly/plotly.min.js` is copied unmodified from
+`plotly.js-strict-dist-min` 4.1.1 by `npm run plotly:dist` (Copyright Plotly,
+Inc.) and keeps its license header. It is **not** committed — the copy step runs
+on every build, and the file is ignored in `.gitignore`. The strict bundle is the
+one without function constructors, so the sandboxed frame that renders a figure
+needs no `unsafe-eval` in its policy (`server/src/plotly-frame.ts`).
+
+## Components shipped in builds under non-MIT licenses
+
+npm installs these; they are not committed. Each package carries its own license
+file in `node_modules`, and the Docker images and a pip installation contain
+them there.
+
+| Component | License | Where it ends up |
+| --- | --- | --- |
+| `pdfjs-dist` | Apache-2.0 | web bundle (PDF viewer) |
+| `dompurify` | MPL-2.0 OR Apache-2.0 | web bundle (HTML sanitising) |
+| `satori` | MPL-2.0 | server (link-preview cards) |
+| `@resvg/resvg-js` and its platform binaries | MPL-2.0 | server (link-preview cards) |
+| `openai` | Apache-2.0 | server (Oracle) |
+| `dotenv`, `webidl-conversions` | BSD-2-Clause | server |
+| `qs`, `ieee754` | BSD-3-Clause | server |
+
+Every other runtime npm dependency is MIT or ISC, per `package-lock.json`.
+The KaTeX fonts in the web bundle are part of KaTeX (MIT).
+
+## The vast.ai image
+
+`deploy/vast/Dockerfile` adds prebuilt binaries to the Node base image. The
+versions and checksums of `frpc` and `cloudflared` are pinned in that file:
+
+| Component | License | Source |
+| --- | --- | --- |
+| `frpc` (frp) | Apache-2.0 | <https://github.com/fatedier/frp> |
+| `cloudflared` | Apache-2.0 | <https://github.com/cloudflare/cloudflared> |
+| Docker CLI and `docker-buildx` | Apache-2.0 | copied from the official `docker:*-cli` image |
+
+The Debian packages installed with `apt-get` (`tini`, `curl`, `sqlite3`,
+`procps`) and those of the `node:22-bookworm-slim` base keep their copyright
+files under `/usr/share/doc` in the image.
+
+## Kernel images
+
+Room kernel images install Python packages from PyPI at build time:
+
+- `kernel/requirements.txt`: Jupyter Server, ipykernel, NumPy, pandas,
+  Matplotlib, Plotly, scikit-learn, requests and Black;
+- `kernel/environments/*.txt`, for example seaborn, PyTorch (the CPU build in
+  `cv`, the CUDA build in `base-gpu`), torchvision, timm, OpenCV and
+  Transformers.
+
+Each package keeps its own license inside the image. The CUDA build of PyTorch
+brings NVIDIA CUDA libraries, which are covered by NVIDIA's license terms.