sshler 1.0.2__tar.gz → 1.0.4__tar.gz

{sshler-1.0.2/sshler.egg-info → sshler-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sshler
-Version: 1.0.2
+Version: 1.0.4
 Summary: A local FastAPI-powered SSH multiplexer for tmux-in-browser — from your laptop only.
 Author-email: Gabu <gabu@gabu.quest>
 License-Expression: MIT
@@ -45,6 +45,7 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: playwright>=1.48.0; extra == "dev"
 Requires-Dist: pytest-playwright>=0.5.0; extra == "dev"
 Requires-Dist: ruff>=0.5.6; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
 Provides-Extra: pdf
 Requires-Dist: playwright>=1.48.0; extra == "pdf"
 Dynamic: license-file
@@ -189,6 +190,12 @@ The app opens at `http://127.0.0.1:8822` and redirects to the Vue SPA at `/app/`
 - **Honest percentages** - The displayed percent is rounded **down**: a 3300-step build at 3299/3300 reads 99%, never a misleading 100% until it's actually done.
 - **Live updates** - One WebSocket (`/ws/progress`) fans out every upsert/delete to every connected browser tab. Multi-machine? Open `/app/progress` on your phone too.
 
+**🌐 Local HTML Artifacts**
+- **One catalog for generated HTML** - Register a single page, a static site, or a recursively discovered collection under a required project and optional nested group.
+- **Agent- and script-friendly CLI** - `sshler artifact add ./report.html --project demo --group reports` registers a completed output; list, show, update, rescan, open, and remove commands cover its lifecycle.
+- **Safe local viewing** - HTML is served from a separate loopback-only origin with strict path containment and no CORS permission. Inline JavaScript works without granting access to the main API origin.
+- **Non-destructive cleanup** - Trash actions and CLI removal unregister catalog metadata only. Source files and directories remain untouched.
+
 **♿ Accessibility**
 - **WCAG 2.1 AA Compliant** - Semantic HTML, ARIA labels, keyboard navigation
 - **Screen Reader Support** - Proper focus management and announcements
@@ -306,6 +313,34 @@ Subscriptions are **per box**: open a box (Files/Terminal), then hit the `+` on
 
 See `examples/progress-bar-build-watcher.sh` for a copy-pasteable demo loop including `trap` → `--status failed` on error.
 
+### Registering generated HTML
+
+Start sshler, create HTML anywhere inside your workspace, and register it by path:
+
+```bash
+# One self-contained page
+sshler artifact add ./report.html --project demo --group reports
+
+# A static site with assets
+sshler artifact add ./site --project demo --group prototypes --mode site --entry index.html
+
+# Recursively discover HTML pages
+sshler artifact add ./reports --project demo --group runs --discover
+
+sshler artifact find "quarterly summary" --project demo
+sshler artifact list --project demo
+sshler artifact open <id>
+sshler artifact remove <id>
+```
+
+Open `/app/artifacts` to search and filter registrations, expand page lists by clicking an
+artifact row, preview pages, and unregister with the trash action. Stable cross-links use
+`/r/<project-slug>/<artifact-slug>/`; `artifact add --mount <path>` can preserve existing
+root-relative links. Opening and previewing require a loopback address. `remove` always leaves
+source files unchanged.
+
+See [`ROADMAP-ARTIFACTS.md`](ROADMAP-ARTIFACTS.md) for the architecture and security model.
+
 ### Key Shortcuts
 
 - **Cmd/Ctrl+K** - Command palette
@@ -452,7 +487,10 @@ SSHLER_COOKIE_SECURE=false  # Only for localhost dev!
    # /etc/caddy/Caddyfile or ~/Caddyfile
 
    sshler.company.internal {
-       reverse_proxy localhost:8822
+       reverse_proxy localhost:8822 {
+           # Overwrite any X-Real-IP the client sent (see SSHLER_TRUST_PROXY_HEADERS)
+           header_up X-Real-IP {remote_host}
+       }
    }
    ```
 
@@ -463,6 +501,10 @@ SSHLER_COOKIE_SECURE=false  # Only for localhost dev!
    SSHLER_PORT=8822
    SSHLER_PUBLIC_URL=https://sshler.company.internal
    SSHLER_COOKIE_SECURE=true  # Required for HTTPS
+   # Caddy overwrites X-Real-IP (header_up above), so sshler may trust it for
+   # rate limits and login lockouts. Leave unset unless a proxy on this host
+   # overwrites X-Real-IP; otherwise sshler keys on the connection's address.
+   SSHLER_TRUST_PROXY_HEADERS=true
    ```
 
 4. Start Caddy:
@@ -573,6 +615,11 @@ server {
 }
 ```
 
+`proxy_set_header X-Real-IP $remote_addr` overwrites any `X-Real-IP` the client sent,
+so set `SSHLER_TRUST_PROXY_HEADERS=true` with this config. Without that setting sshler
+ignores `X-Real-IP` and keys rate limits and login lockouts on the connection's address,
+which behind a proxy is the proxy's.
+
 **Traefik:**
 
 ```yaml
@@ -735,12 +782,13 @@ If you use [Claude Code](https://claude.ai/code) to develop sshler, this repo sh
 - `docs/skills/markdown-preview/SKILL.md` — what renders, what doesn't, and quirks of the print-to-PDF pipeline.
 - `docs/skills/progress-bars/SKILL.md` — push protocol, WebSocket fan-out, per-box subscription model.
 - `docs/skills/diff-notebook/SKILL.md` — the multi-cell diff workspace: command parser, base64 URL state, server-side persistence, the "no new backend" architecture decision.
+- `docs/skills/artifacts/SKILL.md` — create HTML in the current workspace, choose a serving mode, and register it in the catalog.
 
 Claude won't auto-discover these — they live in the repo but aren't registered with the Claude Code runtime. A common pattern is to **symlink them into your global skills directory** (typically `~/.claude/skills/`) so any Claude Code session on your machine can load them by name:
 
 ```bash
 # One-time setup per machine
-for skill in markdown-preview progress-bars diff-notebook; do
+for skill in markdown-preview progress-bars diff-notebook artifacts; do
   mkdir -p ~/.claude/skills/sshler-$skill
   ln -sf "$PWD/docs/skills/$skill/SKILL.md" ~/.claude/skills/sshler-$skill/SKILL.md
 done
@@ -873,6 +921,12 @@ sshler serve
 - **正直なパーセンテージ** - 表示パーセントは**切り捨て**です。3300 ステップのビルドで 3299/3300 なら 99% と表示され、実際に完了するまで誤解を招く 100% にはなりません。
 - **ライブ更新** - WebSocket (`/ws/progress`) が接続中の全タブに upsert/delete イベントをファンアウト。複数マシン？スマホでも `/app/progress` を開けます。
 
+**ローカル HTML 成果物**
+- **生成 HTML を一か所で管理** - 単一ページ、静的サイト、再帰的に検出する HTML コレクションを、必須のプロジェクトと任意のネストしたグループに登録できます。
+- **エージェントやスクリプト向け CLI** - `sshler artifact add ./report.html --project demo --group reports` で完成した出力を登録し、list、show、update、rescan、open、remove で管理できます。
+- **安全なローカル表示** - HTML は厳密なパス制約と CORS 許可なしの別ループバックオリジンから配信されます。
+- **非破壊の整理** - ゴミ箱操作と CLI の remove はカタログ情報だけを解除し、元のファイルやディレクトリは変更しません。
+
 **🤖 Claude セッションダッシュボード**
 - **`/app/claude` — Claude Code セッションの再開** - このマシン上で再開可能な [Claude Code](https://claude.ai/code) の会話（`~/.claude/projects/*/*.jsonl` から読み取り）を一覧表示し、ワンクリックでブラウザ内ターミナルに再開します。タイトルは Claude Code の `/resume` ピッカーと同じ規則です（`/rename` で付けた名前 → AI 生成タイトル → 最初のプロンプトの順）。
 - **Git リポジトリ単位でグループ化・折りたたみ可能** - セッションはリポジトリのルート単位でグループ化されます（`repo/subdir` で実行した会話も `/resume` と同様に `repo` の下に表示）。各グループは折りたたみ可能で、アプリの他の場所と同じディレクトリ絵文字が付きます。初期状態は折りたたみで、フィルタ入力で該当グループが自動展開され、「すべて展開／すべて折りたたむ」ボタンもあります。
@@ -997,6 +1051,19 @@ sshler progress delete build
 
 エラー時に `trap` → `--status failed` するデモループは `examples/progress-bar-build-watcher.sh` を参照。
 
+### 生成 HTML を登録する
+
+```bash
+sshler artifact add ./report.html --project demo --group reports
+sshler artifact add ./site --project demo --group prototypes --mode site --entry index.html
+sshler artifact add ./reports --project demo --group runs --discover
+sshler artifact list --project demo
+sshler artifact open <id>
+sshler artifact remove <id>
+```
+
+`/app/artifacts` でプロジェクト、登録、ページ検出、プレビュー、ゴミ箱操作を管理できます。開く・プレビューする機能はループバックアドレス経由で利用でき、`remove` は元のファイルを残します。設計とセキュリティモデルは [`ROADMAP-ARTIFACTS.md`](ROADMAP-ARTIFACTS.md) を参照してください。
+
 ### キーショートカット
 
 - **Cmd/Ctrl+K** - コマンドパレット
@@ -1141,7 +1208,10 @@ SSHLER_COOKIE_SECURE=false  # localhost 開発専用！
    # /etc/caddy/Caddyfile または ~/Caddyfile
 
    sshler.company.internal {
-       reverse_proxy localhost:8822
+       reverse_proxy localhost:8822 {
+           # クライアントが送った X-Real-IP を上書き（SSHLER_TRUST_PROXY_HEADERS 参照）
+           header_up X-Real-IP {remote_host}
+       }
    }
    ```
 
@@ -1152,6 +1222,10 @@ SSHLER_COOKIE_SECURE=false  # localhost 開発専用！
    SSHLER_PORT=8822
    SSHLER_PUBLIC_URL=https://sshler.company.internal
    SSHLER_COOKIE_SECURE=true  # HTTPS 必須
+   # Caddy が X-Real-IP を上書きする（上記 header_up）ので、レート制限と
+   # ログインロックアウトにその値を使ってよい。同じホストのプロキシが X-Real-IP を
+   # 上書きしない構成では設定しないこと（接続元アドレスが使われる）。
+   SSHLER_TRUST_PROXY_HEADERS=true
    ```
 
 4. Caddy を起動：
@@ -1262,6 +1336,11 @@ server {
 }
 ```
 
+`proxy_set_header X-Real-IP $remote_addr` はクライアントが送った `X-Real-IP` を上書きするので、
+この設定では `SSHLER_TRUST_PROXY_HEADERS=true` を設定してください。この設定がないと sshler は
+`X-Real-IP` を無視し、レート制限とログインロックアウトを接続元アドレス（プロキシの背後では
+プロキシのアドレス）で数えます。
+
 **Traefik:**
 
 ```yaml
@@ -1393,12 +1472,13 @@ systemctl --user enable --now sshler.service
 - `docs/skills/markdown-preview/SKILL.md` — 何がレンダリングされ、何がされないか、そして印刷／PDF パイプラインの癖。
 - `docs/skills/progress-bars/SKILL.md` — プッシュプロトコル、WebSocket ファンアウト、ホストごとの購読モデル。
 - `docs/skills/diff-notebook/SKILL.md` — マルチセルの差分ワークスペース：コマンドパーサー、base64 URL 状態、サーバー側の永続化、「新しいバックエンドを作らない」という設計判断。
+- `docs/skills/artifacts/SKILL.md` — 現在のワークスペースで HTML を作成し、配信モードを選んでカタログへ登録する手順。
 
 Claude はこれらを自動では検出しません。リポジトリ内には存在しますが、Claude Code ランタイムには登録されていないためです。よく使われる方法は、**グローバルスキルディレクトリ（通常は `~/.claude/skills/`）へシンボリックリンクを張る**ことです。こうすると、このマシン上のどの Claude Code セッションからでも名前で読み込めるようになります：
 
 ```bash
 # マシンごとに一度だけセットアップ
-for skill in markdown-preview progress-bars diff-notebook; do
+for skill in markdown-preview progress-bars diff-notebook artifacts; do
   mkdir -p ~/.claude/skills/sshler-$skill
   ln -sf "$PWD/docs/skills/$skill/SKILL.md" ~/.claude/skills/sshler-$skill/SKILL.md
 done

{sshler-1.0.2 → sshler-1.0.4}/README.md

@@ -138,6 +138,12 @@ The app opens at `http://127.0.0.1:8822` and redirects to the Vue SPA at `/app/`
 - **Honest percentages** - The displayed percent is rounded **down**: a 3300-step build at 3299/3300 reads 99%, never a misleading 100% until it's actually done.
 - **Live updates** - One WebSocket (`/ws/progress`) fans out every upsert/delete to every connected browser tab. Multi-machine? Open `/app/progress` on your phone too.
 
+**🌐 Local HTML Artifacts**
+- **One catalog for generated HTML** - Register a single page, a static site, or a recursively discovered collection under a required project and optional nested group.
+- **Agent- and script-friendly CLI** - `sshler artifact add ./report.html --project demo --group reports` registers a completed output; list, show, update, rescan, open, and remove commands cover its lifecycle.
+- **Safe local viewing** - HTML is served from a separate loopback-only origin with strict path containment and no CORS permission. Inline JavaScript works without granting access to the main API origin.
+- **Non-destructive cleanup** - Trash actions and CLI removal unregister catalog metadata only. Source files and directories remain untouched.
+
 **♿ Accessibility**
 - **WCAG 2.1 AA Compliant** - Semantic HTML, ARIA labels, keyboard navigation
 - **Screen Reader Support** - Proper focus management and announcements
@@ -255,6 +261,34 @@ Subscriptions are **per box**: open a box (Files/Terminal), then hit the `+` on
 
 See `examples/progress-bar-build-watcher.sh` for a copy-pasteable demo loop including `trap` → `--status failed` on error.
 
+### Registering generated HTML
+
+Start sshler, create HTML anywhere inside your workspace, and register it by path:
+
+```bash
+# One self-contained page
+sshler artifact add ./report.html --project demo --group reports
+
+# A static site with assets
+sshler artifact add ./site --project demo --group prototypes --mode site --entry index.html
+
+# Recursively discover HTML pages
+sshler artifact add ./reports --project demo --group runs --discover
+
+sshler artifact find "quarterly summary" --project demo
+sshler artifact list --project demo
+sshler artifact open <id>
+sshler artifact remove <id>
+```
+
+Open `/app/artifacts` to search and filter registrations, expand page lists by clicking an
+artifact row, preview pages, and unregister with the trash action. Stable cross-links use
+`/r/<project-slug>/<artifact-slug>/`; `artifact add --mount <path>` can preserve existing
+root-relative links. Opening and previewing require a loopback address. `remove` always leaves
+source files unchanged.
+
+See [`ROADMAP-ARTIFACTS.md`](ROADMAP-ARTIFACTS.md) for the architecture and security model.
+
 ### Key Shortcuts
 
 - **Cmd/Ctrl+K** - Command palette
@@ -401,7 +435,10 @@ SSHLER_COOKIE_SECURE=false  # Only for localhost dev!
    # /etc/caddy/Caddyfile or ~/Caddyfile
 
    sshler.company.internal {
-       reverse_proxy localhost:8822
+       reverse_proxy localhost:8822 {
+           # Overwrite any X-Real-IP the client sent (see SSHLER_TRUST_PROXY_HEADERS)
+           header_up X-Real-IP {remote_host}
+       }
    }
    ```
 
@@ -412,6 +449,10 @@ SSHLER_COOKIE_SECURE=false  # Only for localhost dev!
    SSHLER_PORT=8822
    SSHLER_PUBLIC_URL=https://sshler.company.internal
    SSHLER_COOKIE_SECURE=true  # Required for HTTPS
+   # Caddy overwrites X-Real-IP (header_up above), so sshler may trust it for
+   # rate limits and login lockouts. Leave unset unless a proxy on this host
+   # overwrites X-Real-IP; otherwise sshler keys on the connection's address.
+   SSHLER_TRUST_PROXY_HEADERS=true
    ```
 
 4. Start Caddy:
@@ -522,6 +563,11 @@ server {
 }
 ```
 
+`proxy_set_header X-Real-IP $remote_addr` overwrites any `X-Real-IP` the client sent,
+so set `SSHLER_TRUST_PROXY_HEADERS=true` with this config. Without that setting sshler
+ignores `X-Real-IP` and keys rate limits and login lockouts on the connection's address,
+which behind a proxy is the proxy's.
+
 **Traefik:**
 
 ```yaml
@@ -684,12 +730,13 @@ If you use [Claude Code](https://claude.ai/code) to develop sshler, this repo sh
 - `docs/skills/markdown-preview/SKILL.md` — what renders, what doesn't, and quirks of the print-to-PDF pipeline.
 - `docs/skills/progress-bars/SKILL.md` — push protocol, WebSocket fan-out, per-box subscription model.
 - `docs/skills/diff-notebook/SKILL.md` — the multi-cell diff workspace: command parser, base64 URL state, server-side persistence, the "no new backend" architecture decision.
+- `docs/skills/artifacts/SKILL.md` — create HTML in the current workspace, choose a serving mode, and register it in the catalog.
 
 Claude won't auto-discover these — they live in the repo but aren't registered with the Claude Code runtime. A common pattern is to **symlink them into your global skills directory** (typically `~/.claude/skills/`) so any Claude Code session on your machine can load them by name:
 
 ```bash
 # One-time setup per machine
-for skill in markdown-preview progress-bars diff-notebook; do
+for skill in markdown-preview progress-bars diff-notebook artifacts; do
   mkdir -p ~/.claude/skills/sshler-$skill
   ln -sf "$PWD/docs/skills/$skill/SKILL.md" ~/.claude/skills/sshler-$skill/SKILL.md
 done
@@ -822,6 +869,12 @@ sshler serve
 - **正直なパーセンテージ** - 表示パーセントは**切り捨て**です。3300 ステップのビルドで 3299/3300 なら 99% と表示され、実際に完了するまで誤解を招く 100% にはなりません。
 - **ライブ更新** - WebSocket (`/ws/progress`) が接続中の全タブに upsert/delete イベントをファンアウト。複数マシン？スマホでも `/app/progress` を開けます。
 
+**ローカル HTML 成果物**
+- **生成 HTML を一か所で管理** - 単一ページ、静的サイト、再帰的に検出する HTML コレクションを、必須のプロジェクトと任意のネストしたグループに登録できます。
+- **エージェントやスクリプト向け CLI** - `sshler artifact add ./report.html --project demo --group reports` で完成した出力を登録し、list、show、update、rescan、open、remove で管理できます。
+- **安全なローカル表示** - HTML は厳密なパス制約と CORS 許可なしの別ループバックオリジンから配信されます。
+- **非破壊の整理** - ゴミ箱操作と CLI の remove はカタログ情報だけを解除し、元のファイルやディレクトリは変更しません。
+
 **🤖 Claude セッションダッシュボード**
 - **`/app/claude` — Claude Code セッションの再開** - このマシン上で再開可能な [Claude Code](https://claude.ai/code) の会話（`~/.claude/projects/*/*.jsonl` から読み取り）を一覧表示し、ワンクリックでブラウザ内ターミナルに再開します。タイトルは Claude Code の `/resume` ピッカーと同じ規則です（`/rename` で付けた名前 → AI 生成タイトル → 最初のプロンプトの順）。
 - **Git リポジトリ単位でグループ化・折りたたみ可能** - セッションはリポジトリのルート単位でグループ化されます（`repo/subdir` で実行した会話も `/resume` と同様に `repo` の下に表示）。各グループは折りたたみ可能で、アプリの他の場所と同じディレクトリ絵文字が付きます。初期状態は折りたたみで、フィルタ入力で該当グループが自動展開され、「すべて展開／すべて折りたたむ」ボタンもあります。
@@ -946,6 +999,19 @@ sshler progress delete build
 
 エラー時に `trap` → `--status failed` するデモループは `examples/progress-bar-build-watcher.sh` を参照。
 
+### 生成 HTML を登録する
+
+```bash
+sshler artifact add ./report.html --project demo --group reports
+sshler artifact add ./site --project demo --group prototypes --mode site --entry index.html
+sshler artifact add ./reports --project demo --group runs --discover
+sshler artifact list --project demo
+sshler artifact open <id>
+sshler artifact remove <id>
+```
+
+`/app/artifacts` でプロジェクト、登録、ページ検出、プレビュー、ゴミ箱操作を管理できます。開く・プレビューする機能はループバックアドレス経由で利用でき、`remove` は元のファイルを残します。設計とセキュリティモデルは [`ROADMAP-ARTIFACTS.md`](ROADMAP-ARTIFACTS.md) を参照してください。
+
 ### キーショートカット
 
 - **Cmd/Ctrl+K** - コマンドパレット
@@ -1090,7 +1156,10 @@ SSHLER_COOKIE_SECURE=false  # localhost 開発専用！
    # /etc/caddy/Caddyfile または ~/Caddyfile
 
    sshler.company.internal {
-       reverse_proxy localhost:8822
+       reverse_proxy localhost:8822 {
+           # クライアントが送った X-Real-IP を上書き（SSHLER_TRUST_PROXY_HEADERS 参照）
+           header_up X-Real-IP {remote_host}
+       }
    }
    ```
 
@@ -1101,6 +1170,10 @@ SSHLER_COOKIE_SECURE=false  # localhost 開発専用！
    SSHLER_PORT=8822
    SSHLER_PUBLIC_URL=https://sshler.company.internal
    SSHLER_COOKIE_SECURE=true  # HTTPS 必須
+   # Caddy が X-Real-IP を上書きする（上記 header_up）ので、レート制限と
+   # ログインロックアウトにその値を使ってよい。同じホストのプロキシが X-Real-IP を
+   # 上書きしない構成では設定しないこと（接続元アドレスが使われる）。
+   SSHLER_TRUST_PROXY_HEADERS=true
    ```
 
 4. Caddy を起動：
@@ -1211,6 +1284,11 @@ server {
 }
 ```
 
+`proxy_set_header X-Real-IP $remote_addr` はクライアントが送った `X-Real-IP` を上書きするので、
+この設定では `SSHLER_TRUST_PROXY_HEADERS=true` を設定してください。この設定がないと sshler は
+`X-Real-IP` を無視し、レート制限とログインロックアウトを接続元アドレス（プロキシの背後では
+プロキシのアドレス）で数えます。
+
 **Traefik:**
 
 ```yaml
@@ -1342,12 +1420,13 @@ systemctl --user enable --now sshler.service
 - `docs/skills/markdown-preview/SKILL.md` — 何がレンダリングされ、何がされないか、そして印刷／PDF パイプラインの癖。
 - `docs/skills/progress-bars/SKILL.md` — プッシュプロトコル、WebSocket ファンアウト、ホストごとの購読モデル。
 - `docs/skills/diff-notebook/SKILL.md` — マルチセルの差分ワークスペース：コマンドパーサー、base64 URL 状態、サーバー側の永続化、「新しいバックエンドを作らない」という設計判断。
+- `docs/skills/artifacts/SKILL.md` — 現在のワークスペースで HTML を作成し、配信モードを選んでカタログへ登録する手順。
 
 Claude はこれらを自動では検出しません。リポジトリ内には存在しますが、Claude Code ランタイムには登録されていないためです。よく使われる方法は、**グローバルスキルディレクトリ（通常は `~/.claude/skills/`）へシンボリックリンクを張る**ことです。こうすると、このマシン上のどの Claude Code セッションからでも名前で読み込めるようになります：
 
 ```bash
 # マシンごとに一度だけセットアップ
-for skill in markdown-preview progress-bars diff-notebook; do
+for skill in markdown-preview progress-bars diff-notebook artifacts; do
   mkdir -p ~/.claude/skills/sshler-$skill
   ln -sf "$PWD/docs/skills/$skill/SKILL.md" ~/.claude/skills/sshler-$skill/SKILL.md
 done

{sshler-1.0.2 → sshler-1.0.4}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sshler"
-version = "1.0.2"
+version = "1.0.4"
 description = "A local FastAPI-powered SSH multiplexer for tmux-in-browser — from your laptop only."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -57,6 +57,7 @@ dev = [
     "playwright>=1.48.0",
     "pytest-playwright>=0.5.0",
     "ruff>=0.5.6",
+    "pytest-timeout>=2.3",
 ]
 pdf = [
     "playwright>=1.48.0",
@@ -76,6 +77,7 @@ dev = [
     "types-pyyaml>=6.0.12.20250915",
     "pre-commit>=4.0.0",
     "build>=1.4.0",
+    "pytest-timeout>=2.3",
 ]
 
 [project.scripts]
@@ -91,7 +93,7 @@ exclude = ["frontend*", "tests*"]
 sshler = ["static/**/*", "scripts/*.ps1"]
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py312"
 line-length = 100
 
 [tool.ruff.lint]
@@ -116,3 +118,13 @@ warn_redundant_casts = true
 warn_unused_ignores = true
 no_implicit_reexport = true
 strict_equality = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "strict"
+timeout = 60
+timeout_method = "thread"
+addopts = "--strict-markers"
+markers = [
+    "e2e: Playwright end-to-end tests under tests/e2e (deselect with -m \"not e2e\")",
+]

{sshler-1.0.2 → sshler-1.0.4}/sshler/api/__init__.py

@@ -3,13 +3,14 @@
 from fastapi import APIRouter, Depends
 
 from .archive import get_router as archive_router
-from .excel import get_router as excel_router
+from .artifacts import get_router as artifacts_router
 from .batch import get_router as batch_router
 from .boxes import get_router as boxes_router
 from .claude_sessions import get_router as claude_sessions_router
 from .config import get_router as config_router
 from .dependencies import APIDependencies
 from .diff import get_router as diff_router
+from .excel import get_router as excel_router
 from .files import get_router as files_router
 from .git import get_router as git_router
 from .grep import get_router as grep_router
@@ -27,7 +28,12 @@ from .tunnels import get_router as tunnels_router
 
 
 def create_api_router(deps: APIDependencies) -> APIRouter:
-    api_router = APIRouter(prefix="/api/v1", tags=["api"], dependencies=[Depends(deps.require_token)])
+    api_router = APIRouter(
+        prefix="/api/v1",
+        tags=["api"],
+        dependencies=[Depends(deps.require_token)],
+    )
+    api_router.include_router(artifacts_router(deps))
     api_router.include_router(archive_router(deps))
     api_router.include_router(excel_router(deps))
     api_router.include_router(batch_router(deps))

{sshler-1.0.2 → sshler-1.0.4}/sshler/api/archive.py

@@ -18,7 +18,8 @@ from ..ssh import SSHError
 from ..ssh_pool import get_pool
 from ..validation import PathValidator, ValidationError
 from .dependencies import APIDependencies
-from .helpers import _normalize_local_path, _normalize_directory_path
+from .files import _remote_path
+from .helpers import _normalize_local_path
 from .rate_limiting import rate_limit_file_ops
 
 logger = logging.getLogger(__name__)
@@ -45,12 +46,14 @@ def _validate_archive_name(name: str, fmt: str) -> str:
     try:
         validated = PathValidator.validate_filename(name)
     except ValidationError as exc:
-        raise HTTPException(status_code=400, detail=str(exc))
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
 
     expected_exts = {"tar.gz": (".tar.gz",), "tgz": (".tgz",), "zip": (".zip",)}
     valid_exts = expected_exts.get(fmt, ())
     if not any(validated.lower().endswith(ext) for ext in valid_exts):
-        raise HTTPException(status_code=400, detail=f"Archive name must end in {' or '.join(valid_exts)}")
+        raise HTTPException(
+            status_code=400, detail=f"Archive name must end in {' or '.join(valid_exts)}"
+        )
 
     return validated
 
@@ -94,7 +97,10 @@ def get_router(deps: APIDependencies) -> APIRouter:
         if not payload.paths:
             raise HTTPException(status_code=400, detail="No paths provided")
         if payload.format not in VALID_FORMATS:
-            raise HTTPException(status_code=400, detail=f"Invalid format. Must be one of: {', '.join(VALID_FORMATS)}")
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid format. Must be one of: {', '.join(VALID_FORMATS)}",
+            )
 
         archive_name = _validate_archive_name(payload.archive_name, payload.format)
         box = deps.get_box_or_404(application_config, name)
@@ -126,7 +132,7 @@ def get_router(deps: APIDependencies) -> APIRouter:
             try:
                 await asyncio.to_thread(_create_local)
             except Exception as exc:
-                raise HTTPException(status_code=500, detail=str(exc))
+                raise HTTPException(status_code=500, detail=str(exc)) from exc
 
             return {"status": "ok", "message": f"Created {archive_name}", "path": str(archive_path)}
 
@@ -134,41 +140,48 @@ def get_router(deps: APIDependencies) -> APIRouter:
         try:
             dest_validated = PathValidator.validate_remote_path(payload.destination)
         except ValidationError as exc:
-            raise HTTPException(status_code=400, detail=str(exc))
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
 
         validated_paths: list[str] = []
         for p in payload.paths:
             try:
                 validated_paths.append(PathValidator.validate_remote_path(p))
             except ValidationError as exc:
-                raise HTTPException(status_code=400, detail=f"Invalid path {p}: {exc}")
-
-        archive_target = str(PurePosixPath(dest_validated) / archive_name)
-        quoted_paths = " ".join(shlex.quote(p) for p in validated_paths)
-
-        if payload.format in ("tar.gz", "tgz"):
-            cmd = f"tar czf {shlex.quote(archive_target)} -C / {quoted_paths}"
-        else:
-            cmd = f"cd / && zip -r {shlex.quote(archive_target)} {quoted_paths}"
+                raise HTTPException(status_code=400, detail=f"Invalid path {p}: {exc}") from exc
 
         ssh_pool = get_pool()
         try:
             async with ssh_pool.connection(
                 box, lambda: deps.connect_for_box(box, application_config)
             ) as connection:
+                # SFTP and the quoted shell command do not expand `~`: resolve it here.
+                dest_resolved = await _remote_path(connection, dest_validated)
+                resolved_paths = [await _remote_path(connection, p) for p in validated_paths]
+                archive_target = str(PurePosixPath(dest_resolved) / archive_name)
+                quoted_paths = " ".join(shlex.quote(p) for p in resolved_paths)
+
+                if payload.format in ("tar.gz", "tgz"):
+                    cmd = f"tar czf {shlex.quote(archive_target)} -C / {quoted_paths}"
+                else:
+                    cmd = f"cd / && zip -r {shlex.quote(archive_target)} {quoted_paths}"
+
                 try:
-                    result = await asyncio.wait_for(
+                    await asyncio.wait_for(
                         connection.run(cmd, check=True),
                         timeout=ARCHIVE_TIMEOUT,
                     )
-                except asyncio.TimeoutError:
-                    raise HTTPException(status_code=504, detail="Archive creation timed out")
+                except TimeoutError as exc:
+                    raise HTTPException(
+                        status_code=504, detail="Archive creation timed out"
+                    ) from exc
         except HTTPException:
             raise
+        except ValidationError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
         except SSHError as exc:
-            raise HTTPException(status_code=502, detail=str(exc))
+            raise HTTPException(status_code=502, detail=str(exc)) from exc
         except Exception as exc:
-            raise HTTPException(status_code=500, detail=str(exc))
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
 
         return {"status": "ok", "message": f"Created {archive_name}", "path": archive_target}
 
@@ -205,7 +218,7 @@ def get_router(deps: APIDependencies) -> APIRouter:
             except HTTPException:
                 raise
             except Exception as exc:
-                raise HTTPException(status_code=500, detail=str(exc))
+                raise HTTPException(status_code=500, detail=str(exc)) from exc
 
             return {"status": "ok", "message": "Extracted", "path": str(dest_dir)}
 
@@ -214,14 +227,10 @@ def get_router(deps: APIDependencies) -> APIRouter:
             validated_archive = PathValidator.validate_remote_path(payload.archive_path)
             validated_dest = PathValidator.validate_remote_path(payload.destination)
         except ValidationError as exc:
-            raise HTTPException(status_code=400, detail=str(exc))
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
 
         name_lower = PurePosixPath(validated_archive).name.lower()
-        if name_lower.endswith((".tar.gz", ".tgz")):
-            cmd = f"tar xzf {shlex.quote(validated_archive)} -C {shlex.quote(validated_dest)}"
-        elif name_lower.endswith(".zip"):
-            cmd = f"unzip -o {shlex.quote(validated_archive)} -d {shlex.quote(validated_dest)}"
-        else:
+        if not name_lower.endswith((".tar.gz", ".tgz", ".zip")):
             raise HTTPException(status_code=400, detail="Unsupported archive format")
 
         ssh_pool = get_pool()
@@ -229,20 +238,33 @@ def get_router(deps: APIDependencies) -> APIRouter:
             async with ssh_pool.connection(
                 box, lambda: deps.connect_for_box(box, application_config)
             ) as connection:
+                # SFTP and the quoted shell command do not expand `~`: resolve it here.
+                archive_resolved = await _remote_path(connection, validated_archive)
+                dest_resolved = await _remote_path(connection, validated_dest)
+                if name_lower.endswith((".tar.gz", ".tgz")):
+                    cmd = (
+                        f"tar xzf {shlex.quote(archive_resolved)} -C {shlex.quote(dest_resolved)}"
+                    )
+                else:
+                    cmd = (
+                        f"unzip -o {shlex.quote(archive_resolved)} -d {shlex.quote(dest_resolved)}"
+                    )
                 try:
                     await asyncio.wait_for(
                         connection.run(cmd, check=True),
                         timeout=ARCHIVE_TIMEOUT,
                     )
-                except asyncio.TimeoutError:
-                    raise HTTPException(status_code=504, detail="Extraction timed out")
+                except TimeoutError as exc:
+                    raise HTTPException(status_code=504, detail="Extraction timed out") from exc
         except HTTPException:
             raise
+        except ValidationError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
         except SSHError as exc:
-            raise HTTPException(status_code=502, detail=str(exc))
+            raise HTTPException(status_code=502, detail=str(exc)) from exc
         except Exception as exc:
-            raise HTTPException(status_code=500, detail=str(exc))
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
 
-        return {"status": "ok", "message": "Extracted", "path": validated_dest}
+        return {"status": "ok", "message": "Extracted", "path": dest_resolved}
 
     return router