shell-mirror 1.5.74 β†’ 1.5.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +313 -298
  2. package/package.json +1 -1
  3. package/public/index.html +17 -2
package/README.md CHANGED
@@ -1,331 +1,346 @@
1
1
  # Shell Mirror
2
2
 
3
- A simple application to securely mirror your local computer's shell to a web browser on any device. It uses Google Authentication to ensure only you can access your shell session.
3
+ **Access your Mac terminal from any device, securely.** Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool.
4
4
 
5
- ## 🎯 Project Goal
5
+ ---
6
+
7
+ ## What is Shell Mirror?
8
+
9
+ Shell Mirror lets you access your Mac terminal from any web browser on any device (phone, tablet, laptop). It uses WebRTC for fast, peer-to-peer terminal mirroring with Google OAuth 2.0 authentication to keep your terminal secure.
10
+
11
+ ### Key Features
12
+
13
+ βœ… **Secure Access** - Google OAuth 2.0 authentication
14
+ βœ… **WebRTC Connection** - Fast, direct peer-to-peer terminal mirroring
15
+ βœ… **Multiple Sessions** - Create and manage multiple terminal sessions
16
+ βœ… **Dashboard** - Visual dashboard to manage connected agents and sessions
17
+ βœ… **Mobile-Friendly** - Optimized for mobile coding (perfect for AI coding tools)
18
+ βœ… **NPM Package** - Easy installation via `npm install -g shell-mirror`
19
+ βœ… **Auto-Start** - Mac agent auto-starts and registers with cloud server
20
+
21
+ ---
22
+
23
+ ## πŸ—οΈ Architecture
24
+
25
+ ```
26
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
27
+ β”‚ User's Browser β”‚
28
+ β”‚ (https://shellmirror.app) β”‚
29
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
30
+ β”‚ β”‚ Dashboard β”‚ Terminal Interface β”‚ β”‚
31
+ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
32
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
33
+ β”‚
34
+ Google OAuth 2.0 Authentication
35
+ β”‚
36
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
37
+ β”‚ Heroku WebSocket Signaling Server β”‚
38
+ β”‚ (wss://shell-mirror-[...].herokuapp.com) β”‚
39
+ β”‚ β”‚
40
+ β”‚ β€’ WebRTC signaling (SDP/ICE exchange) β”‚
41
+ β”‚ β€’ Agent discovery & registration β”‚
42
+ β”‚ β€’ Dashboard real-time updates β”‚
43
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
44
+ β”‚
45
+ WebSocket Connection (both ways)
46
+ β”‚
47
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
48
+ β”‚ Mac Agent (User's Computer) β”‚
49
+ β”‚ β”‚
50
+ β”‚ β€’ Auto-starts on login β”‚
51
+ β”‚ β€’ Registers with cloud server β”‚
52
+ β”‚ β€’ Manages multiple terminal sessions β”‚
53
+ β”‚ β€’ WebRTC peer connection to browser β”‚
54
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
55
+ β”‚
56
+ Terminal Sessions
57
+ β”‚
58
+ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”
59
+ β”‚ Terminal β”‚
60
+ β”‚ (node-pty) β”‚
61
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
62
+ ```
63
+
64
+ ### Components
65
+
66
+ 1. **Frontend (TMDHosting)**: Static website at https://shellmirror.app
67
+ 2. **WebSocket Server (Heroku)**: Node.js signaling server for WebRTC
68
+ 3. **PHP Backend (TMDHosting)**: Agent registration and authentication APIs
69
+ 4. **Mac Agent**: Local terminal mirroring agent (npm package)
70
+ 5. **Dashboard**: Real-time agent and session management interface
71
+
72
+ ---
73
+
74
+ ## πŸš€ Quick Start
75
+
76
+ ### For Users (NPM Package)
77
+
78
+ ```bash
79
+ # Install globally
80
+ npm install -g shell-mirror
81
+
82
+ # Run setup wizard (configures Google OAuth)
83
+ shell-mirror setup
84
+
85
+ # Start the agent
86
+ shell-mirror start
87
+
88
+ # Access from browser
89
+ # Visit: https://shellmirror.app
90
+ ```
91
+
92
+ ### For Developers (Local Development)
93
+
94
+ ```bash
95
+ # Clone repository
96
+ git clone https://github.com/karmalsky/shell-mirror.git
97
+ cd terminal-mirror
6
98
 
7
- The primary goal is to allow a user to see their personal shell session (initially for macOS) running on their own computer, reflected in a web page accessible from their mobile phone or tablet. Access must be securely restricted to the user, leveraging a standard and robust authentication provider.
99
+ # Install dependencies
100
+ npm install
8
101
 
9
- Key objectives:
10
- - **Secure Mirroring**: Provide a real-time, read/write mirror of a user's shell.
11
- - **Robust Authentication**: Use Google OAuth 2.0 to ensure that only the owner can access the terminal session.
12
- - **Web-Based Access**: The web interface should allow a user to log in and connect to their running shell server.
13
- - **Simplicity**: The application should be a simple, standalone server that is easy to set up and run on a personal computer.
102
+ # Configure environment
103
+ cp .env.example .env
104
+ # Edit .env with your Google OAuth credentials
105
+
106
+ # Start local WebSocket server
107
+ npm start
108
+
109
+ # Access at http://localhost:3000
110
+ ```
14
111
 
15
112
  ---
16
113
 
17
- ## πŸ—ΊοΈ Development Plan
114
+ ## πŸ” Google OAuth Setup
115
+
116
+ Shell Mirror requires Google OAuth 2.0 credentials:
18
117
 
19
- To achieve this vision, the project will be pivoted from its original, more complex architecture to a streamlined solution.
118
+ 1. **Google Cloud Console**: https://console.cloud.google.com/
119
+ 2. **Create OAuth Client ID**:
120
+ - Application type: **Web application**
121
+ - Authorized JavaScript origins: `https://shellmirror.app`
122
+ - Authorized redirect URIs: `https://shellmirror.app/auth/google/callback`
123
+ 3. **Copy credentials** to your `.env` file or provide during `shell-mirror setup`
124
+
125
+ For detailed OAuth setup instructions, see the old README in `old_md/README_old.md` (lines 66-98).
126
+
127
+ ---
20
128
 
21
- ### High-Level Plan
129
+ ## πŸ“± Usage
22
130
 
23
- 1. **Simplify the Architecture:**
24
- * **Remove Docker:** Eliminate all Docker-related files (`Dockerfile`, `docker-compose.yml`, etc.) and scripts. The application will run directly on the host machine.
25
- * **Remove Connection Broker:** The `broker.js` service is overly complex for the new goal and will be removed.
131
+ ### Access Your Terminal
26
132
 
27
- 2. **Implement Robust Authentication:**
28
- * **Replace Custom Auth:** Swap the current manual token system (`auth.js`) with a standard, secure **Google OAuth 2.0** login flow using Passport.js.
133
+ 1. **Visit**: https://shellmirror.app
134
+ 2. **Login** with Google account
135
+ 3. **Dashboard** shows your connected Mac agents
136
+ 4. **Connect** to start a terminal session
29
137
 
30
- 3. **Refine the User Experience:**
31
- * **Login Page:** The web interface (`index.html`) will first present a "Login with Google" button.
32
- * **Secure Shell Access:** The shell view will only be loaded and connected *after* a successful login.
138
+ ### Multiple Terminal Sessions
139
+
140
+ - **Create new session**: Click "New Terminal Session" in dashboard
141
+ - **Resume session**: Select from existing sessions list
142
+ - **Switch sessions**: Use session dropdown in terminal interface
143
+ - **Manage sessions**: View active sessions, close inactive ones
144
+
145
+ ### Mac Agent Commands
146
+
147
+ ```bash
148
+ shell-mirror start # Start agent
149
+ shell-mirror stop # Stop agent
150
+ shell-mirror restart # Restart agent
151
+ shell-mirror status # Check status
152
+ shell-mirror setup # Run setup wizard
153
+ ```
33
154
 
34
155
  ---
35
156
 
36
- ### Detailed Implementation Steps
157
+ ## πŸ› οΈ Development & Deployment
158
+
159
+ ### Project Structure
37
160
 
38
- * **Phase 1: Cleanup & Refactoring**
39
- 1. Delete `Dockerfile`, `docker-compose.yml`, `docker-compose.override.yml`, and `.dockerignore`.
40
- 2. Delete `broker.js`.
41
- 3. Uninstall unused dependencies and remove Docker-related commands from `package.json`.
42
- 4. Update `server.js` to remove all logic related to the broker and the old authentication system.
161
+ ```
162
+ terminal-mirror/
163
+ β”œβ”€β”€ server.js # WebSocket signaling server
164
+ β”œβ”€β”€ auth.js # Google OAuth configuration
165
+ β”œβ”€β”€ lib/ # CLI and agent management
166
+ β”‚ β”œβ”€β”€ auto-start.js # Mac agent auto-start logic
167
+ β”‚ β”œβ”€β”€ setup-wizard.js # Interactive setup
168
+ β”‚ └── ...
169
+ β”œβ”€β”€ mac-agent/ # Mac terminal mirroring agent
170
+ β”‚ β”œβ”€β”€ agent.js # Main agent (WebRTC + sessions)
171
+ β”‚ └── http-agent.js # HTTP polling fallback
172
+ β”œβ”€β”€ public/ # Frontend files
173
+ β”‚ β”œβ”€β”€ index.html # Landing page
174
+ β”‚ └── app/ # Dashboard and terminal UI
175
+ β”œβ”€β”€ heroku/ # Heroku WebSocket server deployment
176
+ └── php-backend/ # PHP APIs for agent registration
177
+ ```
43
178
 
44
- * **Phase 2: Google Authentication**
45
- 1. Add new dependencies: `passport`, `passport-google-oauth20`, and `express-session`.
46
- 2. Create a new `auth.js` to configure Passport for the Google login flow.
47
- 3. Add the necessary login (`/auth/google`) and callback (`/auth/google/callback`) routes to `server.js`.
48
- 4. Secure the WebSocket connection by ensuring the user is authenticated via their session.
179
+ ### Deployment
49
180
 
50
- * **Phase 3: Frontend UI**
51
- 1. Modify `public/index.html` to conditionally show a "Login" button or the terminal.
52
- 2. Add client-side logic to check the user's authentication status and initiate the WebSocket connection only when logged in.
181
+ ```bash
182
+ # Deploy WebSocket server to Heroku
183
+ ./deploy-heroku.sh
53
184
 
54
- * **Phase 4: Documentation**
55
- 1. Update this `README.md` to reflect the new, simplified project goals, the plan outlined above, and provide clear instructions on how to set up and run the application, including how to generate Google OAuth credentials.
185
+ # Deploy website/PHP backend to TMDHosting
186
+ node deploy-php.cjs
187
+
188
+ # Publish NPM package (user must run manually per CLAUDE.md)
189
+ ./publish.sh
190
+ ```
191
+
192
+ For detailed deployment instructions, see `DEPLOYMENT-PUBLISHING-GUIDE.md`.
56
193
 
57
194
  ---
58
195
 
59
- ## πŸš€ Getting Started
60
-
61
- ### 1. Prerequisites
62
-
63
- - **Node.js**: Make sure you have Node.js (version 18 or higher) installed on your Mac.
64
- - **Google Account**: You will need a Google account to generate authentication credentials.
65
-
66
- ### 2. Configure Google OAuth 2.0 Credentials
67
-
68
- Before you can run the application, you need to get a **Client ID** and **Client Secret** from the Google Cloud Console.
69
-
70
- 1. **Go to the Google Cloud Console**: [https://console.cloud.google.com/](https://console.cloud.google.com/)
71
-
72
- 2. **Create a new project** (or select an existing one).
73
-
74
- 3. **Enable the "Google People API"**: In the navigation menu, go to **APIs & Services > Library**, search for "Google People API", and click **Enable**.
75
-
76
- 4. **Configure the OAuth Consent Screen**:
77
- * Go to **APIs & Services > OAuth consent screen**.
78
- * Choose **External** and click **Create**.
79
- * Fill in the required fields (app name, user support email, developer contact).
80
- * On the "Scopes" page, you can leave it blank.
81
- * On the "Test users" page, add the Google account email you intend to log in with.
82
-
83
- 5. **Create Credentials**:
84
- * Go to **APIs & Services > Credentials**.
85
- * Click **+ CREATE CREDENTIALS** and select **OAuth client ID**.
86
- * For **Application type**, select **Web application**.
87
-
88
- **For Production (shellmirror.app):**
89
- * Under **Authorized JavaScript origins**, add `https://shellmirror.app`.
90
- * Under **Authorized redirect URIs**, add `https://shellmirror.app/auth/google/callback`.
91
-
92
- **For Local Development:**
93
- * Under **Authorized JavaScript origins**, add `http://localhost:3000`.
94
- * Under **Authorized redirect URIs**, add `http://localhost:3000/auth/google/callback`.
95
-
96
- *Note: You can add both production and development URLs to the same OAuth client.*
97
-
98
- * Click **Create**. You will be shown your **Client ID** and **Client Secret**. Copy these.
99
-
100
- ### 3. Configure the Application
101
-
102
- 1. **Create a `.env` file** in the root of the project by copying the example:
103
- ```bash
104
- cp .env.example .env
105
- ```
106
-
107
- 2. **Edit the `.env` file** and add the credentials you just created:
108
-
109
- **For Production (shellmirror.app):**
110
- ```
111
- BASE_URL=https://shellmirror.app
112
- PORT=3000
113
- HOST=0.0.0.0
114
- GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
115
- GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
116
- SESSION_SECRET=a-very-strong-and-long-random-string
117
- ```
118
-
119
- **For Local Development:**
120
- ```
121
- BASE_URL=http://localhost:3000
122
- PORT=3000
123
- HOST=0.0.0.0
124
- GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
125
- GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
126
- SESSION_SECRET=a-very-strong-and-long-random-string
127
- ```
128
-
129
- *Replace the placeholder values with your actual credentials. Use a long, random string for the `SESSION_SECRET`.*
130
-
131
- ### 4. Install & Run
132
-
133
- 1. **Install dependencies**:
134
- ```bash
135
- npm install
136
- ```
137
-
138
- 2. **Start the server**:
139
- ```bash
140
- npm start
141
- ```
142
-
143
- ### 5. Access Your Terminal
144
-
145
- **For Production:**
146
- - Open your web browser and go to `https://shellmirror.app`
147
- - You will be prompted to log in with your Google account
148
- - Once authenticated, you will see your shell mirrored in the browser
149
- - **macOS users:** You may see a firewall dialog asking if Node.js can accept incoming connections - click "Allow" for full terminal functionality
150
-
151
- **For Local Development:**
152
- - Open your web browser and go to `http://localhost:3000`
153
- - Or access from another device on the same network: `http://<your-macs-ip-address>:3000`
154
- - You will be prompted to log in with your Google account
155
- - Once authenticated, you will see your shell mirrored in the browser
156
- - **macOS users:** You may see a firewall dialog asking if Node.js can accept incoming connections - click "Allow" for full terminal functionality
157
-
158
- ### 6. Deployment Notes
159
-
160
- **For Production Deployment:**
161
- - Ensure your server has SSL/TLS configured (required for HTTPS)
162
- - Set up proper firewall rules and security measures
163
- - Consider using a process manager like PM2 for production
164
- - Make sure the `BASE_URL` environment variable matches your actual domain
165
-
166
- **Environment Variables:**
167
- The application will validate that all required environment variables are set on startup and show helpful error messages if any are missing.
168
-
169
- ### 7. Production Deployment
170
-
171
- **Automated Deployment to www.igori.eu:**
172
-
173
- The project includes an automated deployment script that uploads the application to the production server.
196
+ ## πŸ“Š Monitoring & Logs
174
197
 
198
+ ### Check Status
175
199
  ```bash
176
- npm run deploy
200
+ ./status.sh # Check all services
177
201
  ```
178
202
 
179
- **Deployment Process:**
180
- 1. **Validation**: Checks that all required files exist and syntax is valid
181
- 2. **Upload**: Securely uploads all application files via FTP
182
- 3. **Verification**: Confirms all files were uploaded successfully
183
- 4. **Instructions**: Displays post-deployment setup steps
203
+ ### View Logs
204
+ ```bash
205
+ # Heroku WebSocket server
206
+ heroku logs --tail -a shell-mirror
207
+
208
+ # PHP backend (web)
209
+ https://shellmirror.app/debug.html
210
+
211
+ # Local logs
212
+ tail -f server-debug.log
213
+ ```
214
+
215
+ For complete operations guide, see `OPERATIONS.md`.
216
+
217
+ ---
184
218
 
185
- **Post-Deployment Setup:**
186
- After running the deployment script, you'll need to SSH into your server and:
219
+ ## πŸ“š Documentation
220
+
221
+ - **README.md** (this file) - Overview and quick start
222
+ - **OPERATIONS.md** - Monitoring, logs, troubleshooting
223
+ - **QUICK-REFERENCE.md** - Fast command reference
224
+ - **DEPLOYMENT-PUBLISHING-GUIDE.md** - Deployment procedures
225
+ - **TECHNICAL-NOTES.md** - macOS firewall behavior notes
226
+ - **ANALYTICS_SETUP.md** - Google Analytics and Clarity setup
227
+ - **old_md/** - Archived planning documents and old README
228
+
229
+ ---
230
+
231
+ ## πŸ” Technical Details
232
+
233
+ ### Multiple Sessions Implementation
234
+
235
+ Shell Mirror supports multiple persistent terminal sessions per user:
236
+
237
+ - **SessionManager class** in `mac-agent/agent.js` (line 158)
238
+ - **Dashboard UI** for creating/managing sessions
239
+ - **Session persistence** across browser disconnects
240
+ - **Resource limits**: Max 10 sessions per agent
241
+ - **Auto-cleanup**: Sessions idle > 24 hours are terminated
242
+
243
+ ### WebRTC Connection
244
+
245
+ - **Signaling**: Via Heroku WebSocket server
246
+ - **Data Channel**: For terminal I/O (fast, low latency)
247
+ - **ICE/STUN/TURN**: Automatic NAT traversal
248
+ - **Fallback**: HTTP polling if WebRTC fails
249
+
250
+ ### Security
251
+
252
+ - **Authentication**: Google OAuth 2.0
253
+ - **Authorization**: Session-based access control
254
+ - **Encryption**: WSS (WebSocket Secure) + HTTPS
255
+ - **No credentials stored**: Secure token-based auth
256
+
257
+ ---
258
+
259
+ ## 🌐 Production URLs
260
+
261
+ - **Website**: https://shellmirror.app
262
+ - **WebSocket Server**: https://shell-mirror-30aa5479ceaf.herokuapp.com
263
+ - **NPM Package**: https://www.npmjs.com/package/shell-mirror
264
+ - **Debug Dashboard**: https://shellmirror.app/debug.html
265
+
266
+ ---
267
+
268
+ ## πŸ“¦ NPM Package
269
+
270
+ **Current Version**: 1.5.74
271
+
272
+ ```bash
273
+ # Install
274
+ npm install -g shell-mirror
275
+
276
+ # Usage
277
+ shell-mirror --help
278
+ ```
279
+
280
+ Package includes:
281
+ - Mac agent with WebRTC support
282
+ - Interactive setup wizard
283
+ - Auto-start configuration
284
+ - CLI for agent management
285
+
286
+ ---
287
+
288
+ ## πŸ› Troubleshooting
289
+
290
+ ### Agent Not Connecting
291
+
292
+ ```bash
293
+ # Check agent status
294
+ shell-mirror status
295
+
296
+ # View logs
297
+ tail -f ~/.shell-mirror/agent.log
298
+
299
+ # Restart agent
300
+ shell-mirror restart
301
+ ```
302
+
303
+ ### WebSocket Server Issues
304
+
305
+ ```bash
306
+ # Check server health
307
+ curl https://shell-mirror-30aa5479ceaf.herokuapp.com/health
308
+
309
+ # View Heroku logs
310
+ heroku logs --tail -a shell-mirror
311
+ ```
312
+
313
+ ### Browser Connection Issues
314
+
315
+ - **Debug interface**: https://shellmirror.app/debug-connection.html
316
+ - **Check browser console**: F12 β†’ Console tab
317
+ - **Verify authentication**: https://shellmirror.app/api/auth/status
318
+
319
+ For detailed troubleshooting, see `OPERATIONS.md`.
320
+
321
+ ---
322
+
323
+ ## 🀝 Contributing
324
+
325
+ This is currently a personal project. For bug reports or feature requests, please check the GitHub issues.
326
+
327
+ ---
328
+
329
+ ## πŸ“„ License
330
+
331
+ MIT
332
+
333
+ ---
187
334
 
188
- 1. Install dependencies: `npm install`
189
- 2. Configure environment: `cp .env.example .env` and edit with your Google OAuth credentials
190
- 3. Start the server: `npm start` or `pm2 start server.js --name terminal-mirror`
191
- 4. Set up reverse proxy (nginx) if needed for HTTPS
335
+ ## 🎯 Use Cases
192
336
 
193
- **Security Notes:**
194
- - Ensure `.env` file has proper permissions (600)
195
- - Use a strong `SESSION_SECRET` (generate with: `openssl rand -hex 32`)
196
- - Keep Google OAuth credentials secure
197
- - Set up proper firewall rules
337
+ - **Mobile Coding**: Use Claude Code CLI or Gemini CLI from your phone
338
+ - **Remote Access**: Access your development environment from anywhere
339
+ - **Pair Programming**: Share terminal sessions with collaborators
340
+ - **Quick Fixes**: Make quick changes on the go without VPN/SSH setup
341
+ - **Multi-Device Workflow**: Seamlessly switch between devices
198
342
 
199
343
  ---
200
344
 
201
- ## πŸ› οΈ Development Roadmap
202
-
203
- ### Current Status βœ…
204
- The application now has a solid foundation with:
205
- - Google OAuth 2.0 authentication implemented
206
- - Environment-based configuration for production/development
207
- - Basic shell mirroring via WebSocket
208
- - Secure session management
209
-
210
- ### Phase 5: WebRTC Terminal Mirroring (Current) πŸš€
211
- **Priority: Critical - Active Development**
212
-
213
- **Current Status:** βœ… **BREAKTHROUGH ACHIEVED** - Complete WebRTC terminal mirroring working! ICE candidates generating/exchanging, data channel established, terminal spawning with PID, and resizing functional. **Next:** Terminal I/O testing and production readiness.
214
-
215
- #### Immediate Priority (βœ… COMPLETED)
216
- - [x] **Debug ICE Candidate Exchange**
217
- - βœ… Added comprehensive logging for ICE candidate generation and exchange
218
- - βœ… Both client and agent properly send/receive ICE candidates
219
- - βœ… ICE connection state progresses: new β†’ gathering β†’ checking β†’ connected β†’ completed
220
-
221
- - [x] **Fix Data Channel Establishment**
222
- - βœ… Fixed data channel creation sequence (agent creates, client receives)
223
- - βœ… Data channel event handlers properly set up and working
224
- - βœ… Complete connection state logging implemented
225
-
226
- - [x] **Complete Terminal Integration**
227
- - βœ… Terminal spawns successfully when data channel opens (PID: confirmed)
228
- - βœ… Bidirectional terminal I/O: WebRTC data channel established
229
- - βœ… Terminal resizing functionality verified (152x24 resize logged)
230
-
231
- #### Next Phase: Terminal I/O & Functionality (Current Priority)
232
- - [ ] **Test Complete Terminal I/O**
233
- - βœ… Data channel established - verify command input/output works
234
- - Test typing commands and receiving terminal output
235
- - Verify terminal colors, escape sequences, and formatting
236
- - Test command history, tab completion, and terminal features
237
-
238
- - [ ] **Optimize Terminal Performance**
239
- - Test terminal output streaming performance
240
- - Verify efficient terminal resizing (confirmed working: 152x24)
241
- - Add connection quality monitoring and latency measurement
242
-
243
- - [ ] **Handle Terminal Edge Cases**
244
- - Test long-running commands and large output
245
- - Verify proper handling of terminal interrupt (Ctrl+C)
246
- - Test terminal state persistence and recovery
247
-
248
- #### Production Readiness
249
- - [ ] **Authentication & Security Integration**
250
- - Verify Google OAuth integration works with WebRTC connections
251
- - Test production build script (strips local testing code)
252
- - Validate security measures and user session management
253
-
254
- - [ ] **Deployment & End-to-End Testing**
255
- - Deploy to production environment
256
- - Test from multiple devices (desktop, mobile)
257
- - Validate complete functionality across network conditions
258
-
259
- **Success Criteria:** User connects via browser β†’ discovers Mac agent β†’ establishes WebRTC connection β†’ sees live terminal β†’ types commands β†’ receives output β†’ resizes terminal β†’ maintains persistent session.
260
-
261
- **Architecture Notes:**
262
- - Uses WebRTC for peer-to-peer terminal mirroring (eliminates WebSocket polling)
263
- - Node.js signaling server for WebRTC negotiation
264
- - Mac agent with node-pty for terminal spawning
265
- - Browser client with xterm.js for terminal emulation
266
-
267
- ### Next Development Phases
268
-
269
- #### Phase 1: Core Functionality Enhancement
270
- **Priority: High**
271
- - [ ] **WebSocket Authentication**: Secure WebSocket connections by validating user sessions
272
- - [ ] **Shell Session Management**: Implement proper shell session isolation per user
273
- - [ ] **Connection Resilience**: Add automatic reconnection logic for dropped WebSocket connections
274
- - [ ] **Error Handling**: Improve error handling for authentication failures and connection issues
275
-
276
- #### Phase 2: User Experience Improvements
277
- **Priority: Medium**
278
- - [ ] **Frontend UI Enhancement**:
279
- - Modernize the terminal interface (consider using xterm.js for better terminal emulation)
280
- - Add login/logout UI states
281
- - Implement loading states and connection indicators
282
- - [ ] **Shell Features**:
283
- - Shell resizing support
284
- - Copy/paste functionality
285
- - Shell themes and customization
286
- - [ ] **Mobile Optimization**: Ensure the interface works well on mobile devices
287
-
288
- #### Phase 3: Security & Production Readiness
289
- **Priority: High for Production**
290
- - [ ] **Rate Limiting**: Add rate limiting for authentication and WebSocket connections
291
- - [ ] **Logging & Monitoring**: Implement structured logging and health check endpoints
292
- - [ ] **Session Security**: Add session timeout and secure session storage
293
- - [ ] **HTTPS/WSS**: Ensure all connections use secure protocols in production
294
- - [ ] **Environment Isolation**: Add development/staging/production environment configurations
295
-
296
- #### Phase 4: Advanced Features
297
- **Priority: Low (Future Enhancements)**
298
- - [ ] **Multi-Shell Support**: Allow multiple shell sessions per user
299
- - [ ] **File Upload/Download**: Add secure file transfer capabilities
300
- - [ ] **Shell Recording**: Save and replay shell sessions
301
- - [ ] **Collaboration Features**: Allow shared shell sessions (with proper security)
302
- - [ ] **Resource Monitoring**: Display system resource usage in the interface
303
-
304
- ### Development Guidelines
305
-
306
- #### Code Structure
307
- - Keep `server.js` focused on server setup and routing
308
- - Use `auth.js` for all authentication logic
309
- - Create separate modules for shell management and WebSocket handling
310
- - Follow Node.js best practices for async/await and error handling
311
-
312
- #### Testing Strategy
313
- - Add unit tests for authentication logic
314
- - Implement integration tests for WebSocket functionality
315
- - Test OAuth flow in both development and production environments
316
- - Add automated security testing
317
-
318
- #### Deployment Considerations
319
- - Use PM2 or similar process manager for production
320
- - Implement proper logging with log rotation
321
- - Set up SSL/TLS certificates for HTTPS
322
- - Configure reverse proxy (nginx) if needed
323
- - Monitor application health and performance
324
-
325
- ### Contributing
326
- When working on this project:
327
- 1. Create feature branches for each development phase
328
- 2. Test thoroughly in local environment before production
329
- 3. Update this roadmap as features are completed
330
- 4. Document any new environment variables in `.env.example`
331
- 5. Keep security as the top priority for all changes
345
+ *Last Updated: 2025-01-26*
346
+ *Version: 1.5.74*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shell-mirror",
3
- "version": "1.5.74",
3
+ "version": "1.5.75",
4
4
  "description": "Access your Mac shell from any device securely. Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool.",
5
5
  "main": "server.js",
6
6
  "bin": {
package/public/index.html CHANGED
@@ -872,9 +872,24 @@
872
872
  // Update main CTA buttons
873
873
  const primaryButtons = document.querySelectorAll('.btn-primary');
874
874
  primaryButtons.forEach(button => {
875
- button.textContent = 'Open Dashboard';
876
- button.onclick = openDashboard;
875
+ if (authStatus.isAuthenticated) {
876
+ button.textContent = 'Open Dashboard';
877
+ button.onclick = openDashboard;
878
+ }
877
879
  });
880
+
881
+ // Update the Google login button in step 3 for authenticated users
882
+ const googleButton = document.querySelector('.btn-google');
883
+ if (googleButton && authStatus.isAuthenticated) {
884
+ googleButton.innerHTML = 'πŸ“Š Enter Dashboard';
885
+ googleButton.onclick = (e) => {
886
+ e.preventDefault();
887
+ openDashboard();
888
+ };
889
+ googleButton.style.background = 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)';
890
+ googleButton.style.color = 'white';
891
+ googleButton.style.border = 'none';
892
+ }
878
893
  }
879
894
 
880
895
  // Smooth scrolling for anchor links