clt — 1コマンドでHarvard FASRCクラスタにCOMSOLジョブを投入

Macから1行でCOMSOLバッチジョブをクラスタ上で実行します：

cluster file3.mph

これにより（Touch IDのプロンプト →）Windowsマシンから file3.mph を取得し、パスワード + 自動生成された2FAコードでFASRCにログイン、ファイルをアップロードして非同期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

鍵となるのは、FASRCの「Java 2FAアプリ」（OpenAuth/JAuth）が標準的なTOTP（Google Authenticatorと同じアルゴリズム）であることです。base32シードを入手すれば、約15行のNode cryptoで有効なコードを生成でき、expectがsshプロンプトにパスワードとコードを入力して初回ログインを行います。ControlMasterによりそのセッションは維持され、以降はプロンプトが表示されなくなります。

初回セットアップ

0. 必要条件

• macOS、Node ≥ 18（brew install node または nodejs.org）

• OpenAuth 2FAが有効なFASRCアカウント

• オプションのTouch IDゲート：Xcode Command Line Tools（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. OpenAuth TOTPシードを取得する

OpenAuth Javaアプリはbase32シークレットでシードされています。取得方法は2つ：

• FASRC OpenAuthセルフサービスページにログインし、トークンを（再）プロビジョニングします。Javaアプリのダウンロードと同時に、電話認証アプリ用のQRコード/シークレットも提供されます。そのbase32文字列をコピーします。

• または、すでにダウンロードしたOpenAuthバンドルを確認します。シードはjarファイルの隣にあるアプリの設定ファイルに保存されています。

注意：再プロビジョニングすると、古いJavaアプリのコードは動作しなくなります。新しいシードが唯一の正しいシードになります（cluster code をコード生成器として使うか、電話アプリにも読み込んでください）。

4. Windowsマシン：組み込みOpenSSHサーバー

AnyDesk自体にはスクリプト可能なファイル転送機能がないため、Windowsの組み込みOpenSSHサーバー（Windows 10/11のオプション機能 – サードパーティソフト不要）から scp でファイルを取得します。Windowsマシンで管理者PowerShellを開いて実行：

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

次に、Macの公開鍵をインストールして scp がパスワードを要求しないようにします（Macで cat ~/.ssh/id_ed25519.pub、公開鍵がない場合は 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. MacからWindowsに接続する

以下のいずれかを選択：

• AnyDesk TCPトンネル（現在のワークフローに合致）：MacのAnyDeskで、Windows PCのセッション設定を開き → TCP tunneling → ローカルポート 2222 → リモート 127.0.0.1:22。トンネルはAnyDeskセッションが接続中のみ存在します — すでにAnyDeskで接続している場合は問題ありません。AnyDeskライセンスにTCPトンネリングが含まれていることを確認してください。

• 同一ネットワーク/VPN： winbox ブロックの HostName をPCのIPに変更し、Port 2222 の行を削除します。ラボのマシンが同じネットワークを共有している場合に最も簡単です。

• Windowsを完全にスキップ： COMSOLフォルダをOneDrive（Harvard提供）に置き、Macに同期します。その後 cluster ~/OneDrive/.../file3.mph でローカルコピーを使用し、PCには触れません。

テスト：ssh winbox でパスワードプロンプトなしでPCにログインできるはずです。

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）。cluster setup でメールを設定すると、ジョブ完了時に通知を受け取れます。投入されたジョブの管理情報は ~/.config/clt/jobs.json に保存されます。

MCPサーバー（AI駆動COMSOL）

mcp/server.mjs はパイプライン全体をMCPツールとして公開するため、Claude（または任意のMCPクライアント）がCOMSOLをエンドツーエンドで実行できます：run_code（生成されたJava = 完全なCOMSOL API）、run_model、job_status、job_log、wait_for_job、fetch_artifacts、cancel_job、lab_fairshare。.mcp.json を介してプロジェクト全体に登録されています — このリポジトリでClaude Codeセッションを開くと、ツールが利用可能になります。

サーバーではガードレールが適用されます（最大4つの同時ジョブ、≤16 CPU、≤64 GB、≤48時間、許可されたパーティション）。また lab_fairshare は healthy フラグを返し、AIはそれを尊重するよう指示されています。node mcp/smoke.mjs ですべてを確認してください — hello-worldモデルをツールで実行し、物理演算結果を解析解と照合します。モデル構築のイディオムと既知のCOMSOL APIの落とし穴は references/ にあります。

ラボメンバー用のフォーク

このリポジトリには個人データは一切含まれていません：設定は ~/.config/clt/ に、シークレットは各ユーザーのキーチェーンに保存されます。ラボメートはクローンし、npm link を実行し、2つの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/ はgitignoreされており、COMSOLモデルのエクスポート先です。エクスポートには未公開の形状や物理、および実名を含む絶対パスが埋め込まれているため、公開してはいけません。references/ 内の追跡対象ファイルは汎用的で公開可能な例（HelloBox、SweepBox、Inspect）と、CONVENTIONS.md（生成モデルを機能させるためのCOMSOL API知識の集積）です。プッシュする前に、git status で .mph、.java エクスポートファイルや結果CSVが含まれていないか確認してください。

セキュリティに関する注意（正直に）

• 同じMac上でパスワードの隣にTOTPシードを保存すると、2FAは「ロック解除された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 — Host fasrc ブロックに ControlMaster 行がないか、~/.ssh/sockets が存在しません。

• Windowsの取得に失敗 — AnyDeskセッション（とトンネル）は起動していますか？ ssh winbox は動作しますか？ .mph ファイル名にスペースがあるとサポートされていません — 名前を変更してください。* ジョブが即座に終了 — cluster logs でライセンスまたはモジュールエラが表示されることが多いです。モジュール名とグループのCOMSOLライセンスを確認してください。