mstro-app 0.1.47

package/LICENSE

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

package/README.md

@@ -0,0 +1,177 @@
+# mstro
+
+Luxurious remote interface for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Run AI-powered coding sessions from any browser while Claude executes locally on any of your machines.
+
+**mstro** is the CLI client for [mstro.app](https://mstro.app). It runs on your machine (laptop, cloud VM, CI server) and connects to the mstro.app web interface via a secure relay. You write prompts in the browser, Claude Code runs in your terminal.
+
+**Get started at [mstro.app](https://mstro.app)** — create an account, then install this CLI to connect your machine.
+
+## How It Works
+
+```
+Browser (mstro.app)  <--WebSocket-->  Platform Server (relay)  <--WebSocket-->  mstro (your machine)
+                                                                           |
+                                                                      Claude Code CLI
+```
+
+1. `mstro` starts a local server and connects to the mstro.app platform server
+2. You open [mstro.app](https://mstro.app) in any browser and see your connected machine
+3. Prompts you send in the browser are relayed to your machine
+4. Claude Code runs locally with full access to your project files
+5. Output streams back to the browser in real-time
+
+Run Claude Code on a powerful remote machine and interact with it from your phone, tablet, or any device with a browser.
+
+## Installation
+
+```bash
+npm install -g mstro
+```
+
+Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI available in your PATH).
+
+## Quick Start
+
+```bash
+mstro login              # Authenticate this device with your mstro.app account
+mstro                    # Start mstro in your project directory
+```
+
+On first run, mstro will offer to set up the **Security Bouncer** - a tool permission manager that protects against dangerous operations. Say yes.
+
+Then open [mstro.app](https://mstro.app) in your browser. Your machine appears as a connected "orchestra." Start prompting.
+
+## Security Bouncer
+
+The Bouncer replaces the default human-in-the-loop approval model with an agent-in-the-loop approach. An AI reviewer is better suited to evaluate tool calls than a human — it has full context on what should and shouldn't run, responds in milliseconds instead of interrupting your flow, and frees you up to focus on higher-level work while Claude Code executes autonomously. The result is faster, safer workflows without the constant approval prompts. 
+
+The bouncer hook is installed globally at `~/.claude/hooks/bouncer.sh` and applies to all Claude Code sessions, but the level of protection depends on how Claude Code is running:
+
+**Mstro sessions (headless)** get the full 2-layer system:
+
+1. **Pattern matching** (<5ms): Known-safe operations are allowed instantly. Known-dangerous patterns (destructive commands, fork bombs) are blocked instantly.
+2. **AI analysis** (~200-500ms): Ambiguous operations are reviewed by a fast AI model to determine if they look like legitimate development work or prompt injection.
+
+**Claude Code terminal REPL** (`claude`) gets 1-layer protection:
+
+1. **Pattern matching only**: Blocks critical threats (fork bombs, `rm -rf /`, disk overwrites). Allows everything else. The AI analysis layer requires a running mstro server.
+
+### Configure
+
+The bouncer is set up automatically on first run. To reconfigure or install manually:
+
+```bash
+mstro configure-hooks
+```
+
+This installs a hook at `~/.claude/hooks/bouncer.sh` and registers it in `~/.claude/settings.json`.
+
+Set `BOUNCER_USE_AI=false` to disable the AI analysis layer (pattern matching only).
+
+## CLI Reference
+
+### Commands
+
+```bash
+mstro                       # Start the client server
+mstro login                 # Authenticate this device with mstro.app
+mstro logout                # Sign out
+mstro whoami                # Show current user and device info
+mstro status                # Show connection and auth status
+mstro setup-terminal        # Enable web terminal (compiles native module)
+mstro configure-hooks       # Install/reconfigure Security Bouncer
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port <port>` | Start on a specific port (default: 4101, auto-increments if busy) |
+| `-w, --working-dir <dir>` | Set working directory |
+| `-v, --verbose` | Verbose output |
+| `--dev` | Connect to local platform at localhost:4102 |
+| `--version` | Show version |
+| `--help` | Show help |
+
+## Multiple Instances
+
+Run multiple mstro instances for different projects. Each auto-selects an available port:
+
+```
+$ mstro                           # Project A → port 4101
+$ mstro                           # Project B → port 4102
+```
+
+Each instance appears as a separate orchestra in the web interface.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Override server port |
+| `BOUNCER_USE_AI` | Set to `false` to disable AI analysis layer |
+| `PLATFORM_URL` | Platform server URL (default: `https://api.mstro.app`) |
+
+## Config Files
+
+mstro stores config in `~/.mstro/`:
+
+| File | Purpose |
+|------|---------|
+| `~/.mstro/credentials.json` | Device auth token (created by `mstro login`) |
+| `~/.claude/hooks/bouncer.sh` | Security Bouncer hook |
+| `~/.claude/logs/bouncer.log` | Bouncer audit log |
+
+## Requirements
+
+- **Node.js 18+**
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** installed and authenticated
+
+### Optional: Web Terminal
+
+The web terminal feature requires a native module (`node-pty`). mstro works without it - you just won't have the terminal tab in the browser.
+
+On first run, mstro will automatically attempt to compile `node-pty`. If your system has build tools installed, it just works. If not, mstro will let you know what to install:
+
+- **macOS**: `xcode-select --install`
+- **Linux (Debian/Ubuntu)**: `sudo apt install build-essential python3`
+- **Linux (Fedora/RHEL)**: `sudo dnf install gcc-c++ make python3`
+- **Windows**: `npm install -g windows-build-tools`
+
+After installing build tools, run:
+
+```bash
+mstro setup-terminal
+```
+
+### Optional: Persistent Terminals
+
+Install [tmux](https://github.com/tmux/tmux) for terminal sessions that survive restarts:
+
+```bash
+# macOS
+brew install tmux
+
+# Debian/Ubuntu
+sudo apt install tmux
+```
+
+## Links
+
+- **Web App**: [mstro.app](https://mstro.app)
+- **GitHub**: [github.com/mstro-app/mstro](https://github.com/mstro-app/mstro)
+
+## Telemetry
+
+Mstro collects anonymous error reports and usage data to improve the software. No personal data or code is collected.
+
+```bash
+mstro telemetry off    # Disable telemetry
+mstro telemetry on     # Enable telemetry
+```
+
+See [PRIVACY.md](./PRIVACY.md) for details.
+
+## License
+
+MIT

package/bin/commands/config.js

@@ -0,0 +1,145 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * mstro telemetry command
+ *
+ * Enable or disable anonymous telemetry (error reporting and usage analytics).
+ *
+ * Usage:
+ *   mstro telemetry           Show current status
+ *   mstro telemetry on        Enable telemetry
+ *   mstro telemetry off       Disable telemetry
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Colors
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+};
+
+function log(msg, color = '') {
+  console.log(`${color}${msg}${colors.reset}`);
+}
+
+const MSTRO_DIR = join(homedir(), '.mstro');
+const CONFIG_FILE = join(MSTRO_DIR, 'config.json');
+
+/**
+ * Read current config
+ */
+function readConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write config
+ */
+function writeConfig(config) {
+  if (!existsSync(MSTRO_DIR)) {
+    mkdirSync(MSTRO_DIR, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Parse on/off value
+ */
+function parseOnOff(value) {
+  const lower = value.toLowerCase();
+  if (lower === 'true' || lower === '1' || lower === 'on' || lower === 'yes' || lower === 'enable') {
+    return true;
+  }
+  if (lower === 'false' || lower === '0' || lower === 'off' || lower === 'no' || lower === 'disable') {
+    return false;
+  }
+  return null;
+}
+
+function showStatus() {
+  const config = readConfig();
+  const envDisabled = process.env.MSTRO_TELEMETRY === '0' || process.env.MSTRO_TELEMETRY === 'false';
+  const configEnabled = config.telemetry !== false;
+
+  log('\n  Telemetry Status\n', colors.bold + colors.cyan);
+
+  if (envDisabled) {
+    log('  Status: disabled (via MSTRO_TELEMETRY env var)', colors.yellow);
+  } else if (!configEnabled) {
+    log('  Status: disabled', colors.yellow);
+  } else {
+    log('  Status: enabled', colors.green);
+  }
+
+  log('');
+  log('  Mstro collects anonymous error reports and usage data', colors.dim);
+  log('  to improve the software. No personal data or code is collected.', colors.dim);
+  log('');
+  log('  Usage:', colors.bold);
+  log('    mstro telemetry on     Enable telemetry', colors.dim);
+  log('    mstro telemetry off    Disable telemetry', colors.dim);
+  log('');
+  log('  Privacy policy: https://github.com/mstro-app/mstro/blob/main/cli/PRIVACY.md', colors.dim);
+  log('');
+}
+
+function setTelemetry(enabled) {
+  const config = readConfig();
+  config.telemetry = enabled;
+  writeConfig(config);
+
+  if (enabled) {
+    log('\n  Telemetry enabled', colors.green);
+    log('  Thank you for helping improve mstro!\n', colors.dim);
+  } else {
+    log('\n  Telemetry disabled', colors.yellow);
+    log('  No data will be sent.\n', colors.dim);
+  }
+}
+
+/**
+ * Main telemetry command
+ */
+export async function telemetry(args = []) {
+  const action = args[0];
+
+  if (!action) {
+    showStatus();
+    return;
+  }
+
+  if (action === '--help' || action === '-h') {
+    showStatus();
+    return;
+  }
+
+  const value = parseOnOff(action);
+  if (value === null) {
+    log(`\n  Unknown option: ${action}`, colors.red);
+    log('  Usage: mstro telemetry [on|off]\n', colors.dim);
+    process.exit(1);
+  }
+
+  setTelemetry(value);
+}
+
+// Keep 'config' as alias for backwards compatibility
+export { telemetry as config };
+
+export default telemetry;

package/bin/commands/login.js

@@ -0,0 +1,313 @@
+/**
+ * mstro login command
+ *
+ * Authenticates this device with the user's mstro.app account using device code flow.
+ *
+ * Flow:
+ * 1. Request device code from platform
+ * 2. Open browser to authorization URL
+ * 3. Poll platform until user approves
+ * 4. Save credentials locally
+ */
+
+import { exec } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { arch, homedir, hostname, type } from 'node:os';
+import { join } from 'node:path';
+
+// Colors
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+};
+
+function log(msg, color = '') {
+  console.log(`${color}${msg}${colors.reset}`);
+}
+
+const MSTRO_DIR = join(homedir(), '.mstro');
+const CREDENTIALS_FILE = join(MSTRO_DIR, 'credentials.json');
+const CLIENT_ID_FILE = join(MSTRO_DIR, 'client-id');
+const PROD_PLATFORM_URL = 'https://api.mstro.app';
+const DEV_PLATFORM_URL = 'http://localhost:4102';
+
+/**
+ * Get or create client ID
+ */
+function getClientId() {
+  if (!existsSync(MSTRO_DIR)) {
+    mkdirSync(MSTRO_DIR, { recursive: true, mode: 0o700 });
+  }
+
+  if (existsSync(CLIENT_ID_FILE)) {
+    try {
+      const id = readFileSync(CLIENT_ID_FILE, 'utf-8').trim();
+      if (id && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+        return id;
+      }
+    } catch {
+      // Generate new
+    }
+  }
+
+  const newId = crypto.randomUUID();
+  writeFileSync(CLIENT_ID_FILE, newId, 'utf-8');
+  return newId;
+}
+
+/**
+ * Check if already logged in
+ */
+function isLoggedIn() {
+  if (!existsSync(CREDENTIALS_FILE)) {
+    return false;
+  }
+
+  try {
+    const creds = JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
+    return !!(creds.token && creds.userId && creds.email);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get stored credentials
+ */
+function getCredentials() {
+  if (!existsSync(CREDENTIALS_FILE)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save credentials
+ */
+function saveCredentials(creds) {
+  if (!existsSync(MSTRO_DIR)) {
+    mkdirSync(MSTRO_DIR, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Open URL in default browser
+ */
+function openBrowser(url) {
+  // Validate URL to prevent command injection via malicious server responses
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    log(`\n  Invalid URL received. Please open this URL manually:`, colors.yellow);
+    log(`  ${url}\n`, colors.cyan);
+    return;
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    log(`\n  Unexpected URL protocol. Please open this URL manually:`, colors.yellow);
+    log(`  ${url}\n`, colors.cyan);
+    return;
+  }
+
+  const platform = process.platform;
+  let cmd;
+
+  if (platform === 'darwin') {
+    cmd = `open "${parsed.href}"`;
+  } else if (platform === 'win32') {
+    cmd = `start "" "${parsed.href}"`;
+  } else {
+    cmd = `xdg-open "${parsed.href}"`;
+  }
+
+  exec(cmd, (err) => {
+    if (err) {
+      log(`\n  Could not open browser automatically.`, colors.yellow);
+      log(`  Please open this URL manually:`, colors.dim);
+      log(`  ${url}\n`, colors.cyan);
+    }
+  });
+}
+
+/**
+ * Request device code from platform
+ */
+async function requestDeviceCode(clientId, platformUrl) {
+  const machineHostname = hostname();
+  const osType = type().toLowerCase();
+  const cpuArch = arch();
+  const nodeVersion = process.version;
+
+  const response = await fetch(`${platformUrl}/api/auth/device/request`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId,
+      machineHostname,
+      osType,
+      cpuArch,
+      nodeVersion,
+    }),
+  });
+
+  const text = await response.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (_e) {
+    throw new Error(`Server returned invalid JSON (status ${response.status}): ${text.slice(0, 200)}`);
+  }
+
+  if (!response.ok) {
+    throw new Error(data.error || data.message || 'Failed to request device code');
+  }
+
+  return data;
+}
+
+/**
+ * Poll for authorization result
+ */
+async function pollForAuth(deviceCode, interval, platformUrl, maxAttempts = 180) {
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+    attempts++;
+
+    try {
+      const response = await fetch(`${platformUrl}/api/auth/device/poll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode }),
+      });
+
+      const text = await response.text();
+      let data;
+      try {
+        data = JSON.parse(text);
+      } catch (_e) {
+        throw new Error(`Server returned invalid JSON (status ${response.status}): ${text.slice(0, 200)}`);
+      }
+
+      if (response.ok) {
+        // Success!
+        return data;
+      }
+
+      // Handle specific error codes
+      switch (data.error) {
+        case 'authorization_pending':
+          // Still waiting, continue polling
+          process.stdout.write('.');
+          break;
+
+        case 'expired_token':
+          throw new Error('Authorization request expired. Please try again.');
+
+        case 'access_denied':
+          throw new Error('Authorization denied by user.');
+
+        default:
+          throw new Error(data.error || 'Unknown error during authorization');
+      }
+    } catch (err) {
+      if (err.message.includes('fetch')) {
+        // Network error, retry
+        process.stdout.write('x');
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  throw new Error('Authorization timed out. Please try again.');
+}
+
+/**
+ * Main login command
+ */
+export async function login(args = []) {
+  const forceReauth = args.includes('--force') || args.includes('-f');
+  const devMode = args.includes('--dev');
+  const platformUrl = devMode ? DEV_PLATFORM_URL : PROD_PLATFORM_URL;
+
+  log('\n  Mstro Login\n', colors.bold + colors.cyan);
+
+  if (devMode) {
+    log(`  [DEV MODE] Using ${platformUrl}\n`, colors.yellow);
+  }
+
+  // Check if already logged in
+  if (isLoggedIn() && !forceReauth) {
+    const creds = getCredentials();
+    log(`  Already logged in as ${creds.email}`, colors.green);
+    log(`  Use "mstro logout" to sign out, or "mstro login --force" to re-authenticate.\n`, colors.dim);
+    return;
+  }
+
+  const clientId = getClientId();
+
+  log('  Requesting authorization...', colors.dim);
+
+  try {
+    // Step 1: Request device code
+    const { deviceCode, userCode, verificationUrlComplete, interval } = await requestDeviceCode(clientId, platformUrl);
+
+    // Step 2: Show code and open browser
+    log('');
+    log(`  Your authorization code: ${userCode}`, colors.bold);
+    log('');
+    log('  Opening browser to complete login...', colors.dim);
+    log(`  If browser doesn't open, visit: ${verificationUrlComplete}`, colors.dim);
+    log('');
+
+    openBrowser(verificationUrlComplete);
+
+    // Step 3: Poll for result
+    log('  Waiting for authorization', colors.dim);
+    process.stdout.write('  ');
+
+    const result = await pollForAuth(deviceCode, interval, platformUrl);
+
+    // Step 4: Save credentials
+    const credentials = {
+      token: result.accessToken,
+      userId: result.user.id,
+      email: result.user.email,
+      name: result.user.name,
+      clientId,
+      createdAt: new Date().toISOString(),
+    };
+
+    saveCredentials(credentials);
+
+    log('');
+    log('');
+    log(`  Logged in as ${result.user.email}`, colors.bold + colors.green);
+    log('');
+    log('  This device is now connected to your mstro.app account.', colors.dim);
+    log('  Any "mstro" commands will sync with your web dashboard.', colors.dim);
+    log('');
+    log('  Run "mstro" to start an orchestra.', colors.cyan);
+    log('');
+  } catch (err) {
+    log('');
+    log(`  Login failed: ${err.message}`, colors.red);
+    log('');
+    process.exit(1);
+  }
+}
+
+export default login;