@wangyaoshen/remux 0.3.8-dev.bab6c95

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,47 @@
+---
+name: Bug report
+about: Report a regression or defect in the current Zellij-era product path
+title: "[bug] "
+labels: ["bug"]
+assignees: []
+---
+
+## Summary
+
+Describe the problem in one paragraph.
+
+## Affected Layer
+
+- [ ] backend gateway
+- [ ] zellij integration
+- [ ] web frontend
+- [ ] docs / devex
+- [ ] tests / CI
+
+## Environment
+
+- Remux version:
+- Node.js version:
+- Zellij version:
+- Browser / device:
+
+## Reproduction
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What should have happened?
+
+## Validation
+
+- [ ] `npm run typecheck`
+- [ ] `npm test`
+- [ ] `npm run build`
+
+## Notes
+
+Include logs, screenshots, or links when relevant.
+

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,38 @@
+---
+name: Feature request
+about: Propose a feature aligned with the current Zellij-era roadmap
+title: "[feature] "
+labels: ["enhancement"]
+assignees: []
+---
+
+## Summary
+
+What capability should Remux gain?
+
+## Scope Bucket
+
+- [ ] v1 must ship
+- [ ] v1.5 optional
+- [ ] research / future
+
+## Surfaces
+
+- [ ] Inspect
+- [ ] Live
+- [ ] Control
+- [ ] gateway / runtime
+- [ ] docs / devex
+
+## User Outcome
+
+What becomes possible or easier after this lands?
+
+## Acceptance
+
+How will we know the work is done?
+
+## Risks / Dependencies
+
+What could block or complicate this?
+

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Summary
+
+- what changed
+- why it changed
+
+## Area
+
+- [ ] backend gateway
+- [ ] zellij integration
+- [ ] web frontend
+- [ ] docs / devex
+- [ ] tests / CI
+
+## Validation
+
+- [ ] `npm run check:terminology`
+- [ ] `npm run typecheck`
+- [ ] `npm test`
+- [ ] `npm run build`
+
+## Acceptance Notes
+
+List the user-visible or maintainer-visible acceptance outcomes here.
+
+## Risk
+
+Call out migration risk, compatibility risk, or follow-up work.
+

package/.github/dependabot.yml

@@ -0,0 +1,33 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+    groups:
+      npm-patch-minor:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:30"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "deps(ci)"

package/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+    branches: [dev, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm test
+
+  swift-test:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - run: cd packages/RemuxKit && swift build && swift test
+
+  # ── Dev prerelease: publish @dev tag on push to dev ──
+  prerelease:
+    if: github.ref == 'refs/heads/dev' && github.event_name == 'push'
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+
+      - name: Set prerelease version
+        run: |
+          BASE=$(node -p "require('./package.json').version")
+          SHA=$(git rev-parse --short HEAD)
+          PREID="${BASE}-dev.${SHA}"
+          npm version "$PREID" --no-git-tag-version
+          echo "Publishing @wangyaoshen/remux@${PREID} to @dev tag"
+
+      - name: Publish @dev
+        run: pnpm publish --access public --no-git-checks --tag dev
+        continue-on-error: true
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/deploy.yml

@@ -0,0 +1,65 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to deploy (main or dev)"
+        required: true
+        default: "dev"
+        type: choice
+        options: [main, dev]
+
+jobs:
+  deploy:
+    runs-on: [self-hosted, remux-deploy]
+    timeout-minutes: 10
+
+    steps:
+      - name: Resolve target
+        id: target
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            BRANCH="${{ inputs.branch }}"
+          else
+            BRANCH="${GITHUB_REF#refs/heads/}"
+          fi
+          echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
+          if [ "$BRANCH" = "main" ]; then
+            echo "app=remux-main" >> "$GITHUB_OUTPUT"
+            echo "worktree=$HOME/.remux/runtime-worktrees/runtime-main" >> "$GITHUB_OUTPUT"
+          else
+            echo "app=remux-dev" >> "$GITHUB_OUTPUT"
+            echo "worktree=$HOME/.remux/runtime-worktrees/runtime-dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Pull latest code
+        working-directory: ${{ steps.target.outputs.worktree }}
+        run: |
+          git fetch origin ${{ steps.target.outputs.branch }}
+          git checkout --detach origin/${{ steps.target.outputs.branch }}
+
+      - name: Install dependencies
+        working-directory: ${{ steps.target.outputs.worktree }}
+        run: |
+          # Use the same Node.js that the launchd service runs (node@20)
+          # to ensure native modules (better-sqlite3, node-pty) are compiled
+          # for the correct NODE_MODULE_VERSION
+          export PATH="/opt/homebrew/opt/node@20/bin:$PATH"
+          node --version
+          pnpm install
+
+      - name: Build
+        working-directory: ${{ steps.target.outputs.worktree }}
+        run: |
+          export PATH="/opt/homebrew/opt/node@20/bin:$PATH"
+          pnpm run build
+
+      - name: Restart launchd service
+        run: |
+          SERVICE="com.remux.${{ steps.target.outputs.branch }}"
+          launchctl kickstart -k "gui/$(id -u)/${SERVICE}"
+          sleep 2
+          launchctl print "gui/$(id -u)/${SERVICE}" 2>&1 | head -5

package/.github/workflows/publish.yml

@@ -0,0 +1,138 @@
+name: Publish
+
+# Triggered by release-please creating a tag, or manual tag push
+on:
+  push:
+    tags: ['v[0-9]+.[0-9]+.[0-9]+']
+
+jobs:
+  # ── npm publish (@latest) ────────────────────────────
+  npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm test
+      - run: pnpm publish --access public --no-git-checks --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # ── Docker image → ghcr.io ──────────────────────────
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  # ── macOS app (.dmg) → GitHub Release ────────────────
+  macos:
+    runs-on: macos-15
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Build GhosttyKit xcframework
+        run: |
+          cd vendor/ghostty
+          zig build -Demit-xcframework=true -Dxcframework-target=native -Doptimize=ReleaseFast
+
+      - name: Build macOS app (release)
+        run: |
+          cd apps/macos
+          swift build -c release
+
+      - name: Create .app bundle and DMG
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          bash scripts/build-dmg.sh "$VERSION"
+
+      - name: Upload DMG to GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          DMG="build/Remux-${VERSION}-arm64.dmg"
+          if [ -f "$DMG" ]; then
+            gh release upload "$TAG" "$DMG" --clobber
+            echo "✓ Uploaded $DMG to release $TAG"
+          else
+            echo "⚠ DMG not found, uploading .app as zip"
+            cd build && zip -r "Remux-${VERSION}-arm64.zip" Remux.app
+            gh release upload "$TAG" "Remux-${VERSION}-arm64.zip" --clobber
+          fi
+
+  # ── Update Homebrew tap ─────────────────────────────
+  homebrew:
+    needs: [npm, macos]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Update Homebrew formula and cask
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+
+          git clone https://x-access-token:${GH_TOKEN}@github.com/yaoshenwang/homebrew-tap /tmp/tap
+          cd /tmp/tap
+
+          # Update cask version
+          sed -i "s/version \".*\"/version \"${VERSION}\"/" Casks/remux-app.rb
+
+          # Update formula URL
+          sed -i "s|remux-.*\.tgz|remux-${VERSION}.tgz|" Formula/remux.rb
+
+          # Compute sha256 for npm tarball
+          NPM_SHA=$(curl -sL "https://registry.npmjs.org/@wangyaoshen/remux/-/remux-${VERSION}.tgz" | sha256sum | cut -d' ' -f1)
+          sed -i "s/sha256 \".*\"/sha256 \"${NPM_SHA}\"/" Formula/remux.rb
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --cached --quiet || git commit -m "Update to v${VERSION}"
+          git push origin main

package/.github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: node

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/ghostty"]
+	path = vendor/ghostty
+	url = https://github.com/ghostty-org/ghostty.git

package/.nvmrc

@@ -0,0 +1 @@
+25

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.6"
+}

package/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+本文件为代理在本仓库工作时的指令手册。所有规则必须严格遵守。
+
+## 项目概述
+
+Remux 是一个基于 Web 的远程终端控制台，使用 ghostty-web 渲染 + node-pty 直接管理 shell PTY（无 Zellij 依赖）。通过 tunnel 让用户从手机、平板或其他电脑监控和控制终端会话。以 npm 包分发（`npx @wangyaoshen/remux`）。使用 pnpm 作为包管理器。
+
+- **GitHub**: github.com/yaoshenwang/remux
+- **许可证**: MIT
+
+## 沟通语言
+
+所有与用户的交流必须使用中文。代码注释和 commit message 使用英文。
+
+## 分支纪律（强制）
+
+- 维护 `main`（生产）和 `dev`（开发）两个长期分支
+- **禁止直接在 `main` 或 `dev` 上修改代码**
+- 所有开发工作从 `dev` 创建 feature 分支，使用 `git worktree` 隔离开发
+- 完成后合并回 `dev`，`dev` 定期合并到 `main` 发布
+- **禁止直接 push 到 main**
+
+### 分支命名规范
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 功能 | `feat/<简短描述>` | `feat/websocket-reconnect` |
+| 修复 | `fix/<简短描述>` | `fix/resize-debounce` |
+| 维护 | `chore/<简短描述>` | `chore/remove-unused-deps` |
+| 更新 | `update/<简短描述>` | `update/bump-dependencies` |
+
+### Worktree 路径
+
+`.worktrees/<分支短名>`，例如 `.worktrees/websocket-reconnect`
+
+### 版本管理
+
+- 遵循 SemVer。AI 仅可自行 bump patch 版本
+- Minor/Major 版本变更需用户明确批准
+- 每次 feature 合并到 `dev` 后 bump patch
+
+## 常用命令
+
+```bash
+pnpm start
+pnpm run dev
+pnpm test
+```
+
+### 构建检查（强制）
+
+合并到 `dev` 之前必须通过：
+
+```bash
+pnpm test
+```
+
+## 开发规范
+
+### TDD 强制
+
+非平凡的代码变更必须采用 TDD：先写测试（红）→ 实现（绿）→ 重构。
+
+### 评估验收原则
+
+- 实现前先定义可衡量的成功标准，覆盖四维度：结果、过程、风格、效率
+- 先写确定性检查（文件存在、命令执行、输出匹配），再加定性评估
+- 用实际失败驱动测试覆盖扩展，不靠猜测穷举
+- 完整方法论参见 skill `eval-driven-development`
+
+### 开源复用优先（强制）
+
+- **优先寻找并复用成熟开源项目的代码、库或设计**，而非从零实现
+- 实现新功能前，先调研是否有质量可靠的 npm 包、开源库或可参考的开源项目实现
+- 可以直接引入的依赖就引入依赖；不能直接引入但思路成熟的，参考其架构和接口设计再实现
+- 参考来源必须在 commit message 或代码注释中标注（例如 `// Adapted from vercel-labs/agent-browser`）
+- 自造轮子仅在以下情况允许：无合适开源方案、现有方案与项目架构严重不兼容、许可证不兼容（GPL 等）
+- 定期关注同领域项目（cmux、warp、wave-terminal 等）的新特性和技术选型
+
+### 安全要点
+
+- 单一 WebSocket 端点 `/ws`，使用 `REMUX_TOKEN` 环境变量进行 token 认证
+- shell 相关命令使用参数数组，禁止退化为 shell 拼接字符串
+
+### 浏览器自动化（强制）
+
+- 使用 `playwright-cli` 进行所有浏览器自动化测试和页面检查
+- **禁止使用 chrome-devtools MCP**
+- 常用命令：
+  - `playwright-cli open <url>` — 打开页面
+  - `playwright-cli snapshot` — 获取页面快照和元素 ref
+  - `playwright-cli click <ref>` — 点击元素
+  - `playwright-cli eval '<js>'` — 执行 JavaScript
+  - `playwright-cli screenshot` — 截图
+  - `playwright-cli -s=<session>` — 指定会话操作
+
+### 交付流程（强制）
+
+1. 在 feature 分支完成开发 + 自测（`pnpm test` 全部通过）
+2. 确认功能开发完全后，立即合并到 `dev`
+3. 立刻 push 到远程 `origin/dev`，禁止只做本地合并
+4. 基于远程 `dev` 对应的真实环境执行必要的实机验证
+5. 验证通过后再向用户报告完成；若验证失败，继续修复并重复上述流程，禁止未合并或未推送就交付

package/Dockerfile

@@ -0,0 +1,23 @@
+# E16-006: Docker self-hosted image for Remux
+FROM node:20-slim
+
+WORKDIR /app
+
+# Install only production dependencies
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile --prod
+
+# Copy built server and assets
+COPY server.js ./
+COPY node_modules/ghostty-web/dist/ ./node_modules/ghostty-web/dist/
+COPY node_modules/ghostty-web/ghostty-vt.wasm ./node_modules/ghostty-web/
+
+# Default port
+ENV PORT=8767
+
+EXPOSE 8767
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD node -e "fetch('http://localhost:8767/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+ENTRYPOINT ["node", "server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yaoshen Wang
+
+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.