clt — однострочные задания COMSOL на кластере FASRC Harvard

Запустите пакетное задание COMSOL на кластере с вашего Mac одной строкой:

cluster file3.mph

которая (запрос Touch ID →) забирает file3.mph с Windows-машины, входит в FASRC с вашим паролем + автоматически сгенерированным кодом 2FA, загружает файл, отправляет асинхронное задание Slurm и возвращает вам ID задания. Позже:

cluster status          # queue overview
cluster logs            # tail the COMSOL batch log of the latest job
cluster fetch           # download out.mph + batch.log when it's done
cluster shell           # drop into an interactive shell (no re-login)
cluster code            # print the current 2FA code, e.g. for a manual login

Всё это — один скрипт Node без зависимостей (cluster.js) плюс встроенные средства macOS: ssh, scp, expect, security (Связка ключей). Никаких npm-пакетов.

Как это работает

Mac (cluster.js)
 ├─ Touch ID gate            (optional tiny Swift helper, compiled once)
 ├─ Keychain                 → FASRC password + TOTP seed
 ├─ TOTP in Node crypto      → the same 6-digit codes as the OpenAuth Java app
 ├─ ssh ControlMaster        → authenticate ONCE, reuse the session ~8h,
 │                             so scp/ssh/sbatch below run with zero prompts
 ├─ scp  winbox → Mac        (over an AnyDesk TCP tunnel or LAN, key auth)
 ├─ scp  Mac → cluster       (over the shared session)
 └─ ssh  sbatch              → COMSOL batch job runs asynchronously on Slurm

Ключевая идея в том, что «Java 2FA app» FASRC (OpenAuth/JAuth) — это обычный TOTP, тот же алгоритм, что и в Google Authenticator. Получив его base32-сид, ~15 строк Node crypto генерируют корректные коды, а expect вводит пароль и код в приглашения ssh при первом входе за день. ControlMaster держит сессию активной, так что больше ничего не запрашивает.

Одноразовая настройка

0. Требования

• macOS с Node ≥ 18 (brew install node или nodejs.org)

• Учётная запись FASRC с OpenAuth 2FA

• Опциональный шлюз Touch ID: Инструменты командной строки Xcode (xcode-select --install)

1. Установка команды

cd clt
npm link          # or: alias cluster="node /path/to/clt/cluster.js" in ~/.zshrc

Опциональный шлюз Touch ID (пропустите — скрипт просто не будет запрашивать):

swiftc -O touchid.swift -o touchid

2. Конфигурация ssh (обязательно)

Добавьте в ~/.ssh/config (создайте при необходимости) и выполните mkdir -p ~/.ssh/sockets:

Host fasrc
  HostName login.rc.fas.harvard.edu
  User YOUR_FASRC_USERNAME
  ControlMaster auto
  ControlPath ~/.ssh/sockets/%r@%h-%p
  ControlPersist 8h
  ServerAliveInterval 60

Host winbox
  HostName 127.0.0.1        # via the AnyDesk TCP tunnel; or the LAN IP of the PC
  Port 2222                 # the tunnel's local port (drop this line if using LAN IP)
  User YOUR_WINDOWS_USERNAME

Блок ControlMaster — это то, что делает всё быстрым: без него каждый scp/ssh требовал бы новый пароль + OTP, и инструмент отказывается работать.

3. Получение сида TOTP OpenAuth

Java-приложение OpenAuth инициализируется base32-секретом. Два способа получить его:

• Войдите на страницу самообслуживания OpenAuth FASRC и (пере)выпустите свой токен. Вместе с загрузкой Java-приложения она предлагает QR-код / секрет для использования с приложениями-аутентификаторами на телефоне — скопируйте эту base32-строку.

• Или загляните внутрь уже загруженного пакета OpenAuth: сид хранится в файле конфигурации приложения рядом с jar.

Примечание: если вы перевыпустите токен, коды старого Java-приложения перестанут работать — новый сид становится единственно верным (используйте cluster code как генератор или также загрузите его в приложение на телефоне).

4. Windows-машина: встроенный сервер OpenSSH

У AnyDesk нет скриптуемой передачи файлов, поэтому мы забираем файлы с помощью scp со встроенного сервера OpenSSH Windows (опциональная функция Windows 10/11 — никакого стороннего ПО). В административной PowerShell на Windows-машине:

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic

Затем установите открытый ключ вашего Mac, чтобы scp не требовал пароль (cat ~/.ssh/id_ed25519.pub на Mac; сначала ssh-keygen -t ed25519, если у вас его нет). Загвоздка: если ваша учётная запись Windows является администратором, ключи помещаются в специальный файл:

Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys -Value "ssh-ed25519 AAAA...your key..."
icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"

(Для неадминистративных учётных записей это обычный C:\Users\you\.ssh\authorized_keys.)

5. Доступ к Windows с Mac

Выберите один вариант:

• TCP-туннель AnyDesk (соответствует вашему текущему рабочему процессу): в AnyDesk на Mac откройте настройки сессии для Windows ПК → TCP tunneling → локальный порт 2222 → удалённый 127.0.0.1:22. Туннель существует только пока сессия AnyDesk подключена — нормально, если вы всё равно в AnyDesk. Убедитесь, что ваша лицензия AnyDesk включает TCP-туннелирование.

• Одна сеть / VPN: установите HostName на IP ПК в блоке winbox и удалите строку Port 2222. Проще всего, если лабораторные машины находятся в одной сети.

• Пропустить Windows полностью: поместите папку COMSOL в OneDrive (Harvard предоставляет его) и дайте ей синхронизироваться с Mac — тогда cluster ~/OneDrive/.../file3.mph использует локальную копию и никогда не обращается к ПК.

Тест: ssh winbox должен войти на ПК без запроса пароля.

6. Хранение секретов и настройка

cluster setup

Запрашивает псевдонимы хостов, настройки Slurm по умолчанию, ваш пароль FASRC и сид TOTP. Секреты помещаются в Связку ключей macOS (никогда на диск, никогда в этот репозиторий). Настройка завершается выводом сгенерированного кода 2FA — проверьте, что он совпадает с тем, что показывает Java-приложение, прежде чем доверять ему.

Затем подтвердите на кластере (один раз, через cluster shell):

• module avail comsol — установите точное имя модуля в ~/.config/clt/config.json

• ваша группа имеет лицензионные места COMSOL и выберите правильный раздел для вашей лаборатории

Использование

cluster file3.mph                    # fetch from Windows, upload, submit
cluster ./local/file3.mph            # a file that exists locally skips the Windows fetch
cluster file3.mph -study std2        # extra args are passed to `comsol batch`
cluster status                       # your whole queue
cluster status 12345678              # one job, incl. finished (sacct)
cluster logs file3                   # tail batch.log
cluster fetch file3                  # → ./file3-out.mph + ./file3-batch.log

Файлы заданий попадают на кластер в ~/comsol_jobs/<name>-<timestamp>/ (in.mph, out.mph, batch.log, slurm-<id>.log). Установите email в cluster setup, чтобы получать сообщение о завершении заданий. Учёт отправленных заданий ведётся в ~/.config/clt/jobs.json.

MCP-сервер (COMSOL под управлением ИИ)

mcp/server.mjs предоставляет весь конвейер в виде инструментов MCP, так что Claude (или любой MCP-клиент) может запускать COMSOL от начала до конца: run_code (сгенерированный Java = полный API COMSOL), run_model, job_status, job_log, wait_for_job, fetch_artifacts, cancel_job, lab_fairshare. Зарегистрированы в масштабе проекта через .mcp.json — откройте сессию Claude Code в этом репозитории, и инструменты будут доступны.

Ограничения применяются на сервере (макс. 4 одновременных задания, ≤16 ЦП, ≤64 ГБ, ≤48 ч, разрешённые разделы), а lab_fairshare возвращает флаг healthy, который ИИ предписано уважать. Проверьте всё с помощью node mcp/smoke.mjs — он запускает модель hello-world через инструменты и проверяет физику на соответствие аналитическому ответу. Идиомы построения моделей и известные ловушки API COMSOL хранятся в references/.

Форки для членов лаборатории

Репозиторий содержит ноль личных данных: конфигурация хранится в ~/.config/clt/, секреты — в Связке ключей каждого человека. Коллега просто клонирует, запускает npm link, добавляет два блока конфигурации ssh и запускает cluster setup со своими учётными данными. Никогда не делитесь своим сидом TOTP и не фиксируйте его где-либо.

Быстрый старт для свежего клона:

git clone <this repo> && cd clt
npm install          # MCP server deps (the CLI itself needs none)
npm link             # provides the `cluster` command
swiftc -O touchid.swift -o touchid    # optional Touch ID gate
cluster setup        # host aliases, Slurm defaults, secrets -> Keychain
cluster login        # verify; then `cluster help`

Держите исследовательские данные вне репозитория

references/lab/ проигнорирован git и предназначен для экспортов моделей COMSOL. Экспорты содержат неопубликованную геометрию и физику, а также абсолютные пути с реальными именами, поэтому они не должны публиковаться. Отслеживаемые файлы в references/ — это общие, публикуемые примеры (HelloBox, SweepBox, Inspect) плюс CONVENTIONS.md, накопленные знания API COMSOL, которые заставляют сгенерированные модели работать. Перед отправкой проверьте git status на наличие случайных .mph, .java экспортов или CSV-результатов.

Замечания по безопасности, честно

• Хранение сида TOTP рядом с паролем на одном Mac сводит двухфакторную аутентификацию к «владению вашим разблокированным Mac». Это защищает от удалённого кражи учётных данных, но не от того, кто сидит за вашей клавиатурой. Включите FileVault.

• Шлюз Touch ID — это удобная блокировка этого скрипта, а не шифрование — секреты защищены Связкой ключей. Чтобы принудительно показывать диалог подтверждения macOS при каждом чтении секрета, пересоздайте элементы без доверенного приложения: security add-generic-password -U -T "" -a $USER -s clt-cluster-password -w

• Убедитесь, что автоматизация вашего собственного OTP соответствует политике допустимого использования FASRC; это автоматизация удобства для одного человека, и сид должен оставаться личным.

Устранение неполадок

• login failed — выполните ssh fasrc вручную, чтобы увидеть реальные приглашения, и сравните cluster code с Java-приложением. Если часы вашего Mac сбиты, коды TOTP будут неверны (Системные настройки → Основные → Дата и время → устанавливать автоматически).

• no ControlMaster socket — строки ControlMaster отсутствуют в блоке Host fasrc, или ~/.ssh/sockets не существует.

• Сбой получения с Windows — активна ли сессия AnyDesk (и туннель)? Работает ли ssh winbox? Пробелы в именах файлов .mph не поддерживаются — переименуйте.

• Задание умирает сразу — cluster logs обычно показывает ошибку лицензии или модуля; проверьте имя модуля и лицензию COMSOL вашей группы.