devsh 0.1.0

package/AGENTS.md

@@ -0,0 +1,87 @@
+# devsh CLI - Agent Instructions
+
+devsh is a CLI for managing cloud development VMs. Use these commands to help users work with remote development environments.
+
+## Quick Reference
+
+```bash
+# Authentication
+devsh login               # Login (opens browser)
+devsh logout              # Logout
+devsh whoami              # Show current user and team
+
+# VM Lifecycle
+devsh start [path]        # Create VM, optionally sync directory
+devsh ls                  # List all VMs
+devsh status <id>         # Show VM details and URLs
+devsh pause <id>          # Pause VM (preserves state, saves cost)
+devsh resume <id>         # Resume paused VM
+devsh delete <id>         # Delete VM permanently
+
+# Access VM
+devsh code <id>           # Open VS Code in browser
+devsh ssh <id>            # SSH into VM
+devsh vnc <id>            # Open VNC desktop
+devsh pty <id>            # Interactive terminal session
+
+# Work with VM
+devsh exec <id> "cmd"     # Run command in VM
+devsh sync <id> <path>    # Sync local files to VM
+devsh sync <id> <path> --pull  # Pull files from VM
+
+# Browser Automation (control Chrome in VNC)
+devsh computer open <id> <url>           # Navigate to URL
+devsh computer snapshot <id>             # Get interactive elements (@e1, @e2...)
+devsh computer click <id> <selector>     # Click element (@e1 or CSS selector)
+devsh computer type <id> "text"          # Type into focused element
+devsh computer fill <id> <sel> "value"   # Clear and fill input
+devsh computer screenshot <id> [file]    # Take screenshot
+devsh computer press <id> <key>          # Press key (enter, tab, escape)
+```
+
+## VM IDs
+
+VM IDs look like `cmux_abc12345`. Always use the full ID when running commands.
+
+## Common Workflows
+
+### Create and access a VM
+```bash
+devsh start ./my-project    # Creates VM, syncs directory, returns ID
+devsh code cmux_abc123      # Opens VS Code
+```
+
+### Run commands remotely
+```bash
+devsh exec cmux_abc123 "npm install"
+devsh exec cmux_abc123 "npm run dev"
+```
+
+### Sync files
+```bash
+devsh sync cmux_abc123 .              # Push current dir to VM
+devsh sync cmux_abc123 ./dist --pull  # Pull build output from VM
+```
+
+### Browser automation
+```bash
+devsh computer open cmux_abc123 "https://localhost:3000"
+devsh computer snapshot cmux_abc123   # See clickable elements
+devsh computer click cmux_abc123 @e1  # Click first element
+```
+
+### End of session
+```bash
+devsh pause cmux_abc123    # Pause to save costs (can resume later)
+# OR
+devsh delete cmux_abc123   # Delete permanently
+```
+
+## Tips
+
+- Run `devsh login` first if not authenticated
+- Use `devsh whoami` to check current user and team
+- Use `devsh ls` to see all VMs and their states
+- Paused VMs preserve state and can be resumed instantly
+- The `devsh pty` command requires an interactive terminal
+- Browser automation commands work on the Chrome instance in the VNC desktop

package/README.md

@@ -0,0 +1,73 @@
+# devsh
+
+Cloud VMs for development - spawn isolated dev environments instantly.
+
+## Installation
+
+```bash
+npm install -g devsh
+```
+
+## Quick Start
+
+```bash
+# Login
+devsh login
+
+# Create a VM
+devsh start                     # Returns ID
+
+# Access the VM
+devsh code <id>          # Open VS Code in browser
+devsh ssh <id>           # SSH into VM
+
+# Run commands
+devsh exec <id> "npm install"
+
+# Manage lifecycle
+devsh pause <id>         # Pause (preserves state)
+devsh resume <id>        # Resume
+devsh delete <id>        # Delete permanently
+
+# List all VMs
+devsh ls
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `devsh login` | Login via browser |
+| `devsh start [path]` | Create new VM, optionally sync directory |
+| `devsh ls` | List all VMs |
+| `devsh code <id>` | Open VS Code in browser |
+| `devsh vnc <id>` | Open VNC desktop in browser |
+| `devsh ssh <id>` | SSH into VM |
+| `devsh pty <id>` | Open interactive terminal |
+| `devsh exec <id> "cmd"` | Execute command |
+| `devsh sync <id> <path>` | Sync files to VM |
+| `devsh pause <id>` | Pause VM |
+| `devsh resume <id>` | Resume VM |
+| `devsh delete <id>` | Delete VM |
+
+## Browser Automation
+
+Control Chrome in the VNC desktop:
+
+```bash
+devsh computer open <id> https://example.com
+devsh computer snapshot <id>       # Get interactive elements
+devsh computer click <id> @e1      # Click element
+devsh computer type <id> "hello"   # Type text
+devsh computer screenshot <id>     # Take screenshot
+```
+
+## Platform Support
+
+- macOS (Apple Silicon & Intel)
+- Linux (x64 & ARM64)
+- Windows (x64)
+
+## License
+
+MIT

package/bin/devsh

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORMS = {
+  "darwin-arm64": "devsh-darwin-arm64",
+  "darwin-x64": "devsh-darwin-x64",
+  "linux-arm64": "devsh-linux-arm64",
+  "linux-x64": "devsh-linux-x64",
+  "win32-x64": "devsh-win32-x64",
+};
+
+// Map platform to local directory name (for development)
+const LOCAL_DIRS = {
+  "darwin-arm64": "darwin-arm64",
+  "darwin-x64": "darwin-x64",
+  "linux-arm64": "linux-arm64",
+  "linux-x64": "linux-x64",
+  "win32-x64": "win32-x64",
+};
+
+function getBinaryPath() {
+  const platform = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORMS[platform];
+  const localDir = LOCAL_DIRS[platform];
+
+  if (!pkg) {
+    console.error(`devsh: Unsupported platform: ${platform}`);
+    console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+    process.exit(1);
+  }
+
+  const binName = process.platform === "win32" ? "devsh.exe" : "devsh";
+
+  // Try to find the platform-specific package from node_modules
+  try {
+    const pkgPath = require.resolve(`${pkg}/package.json`);
+    const pkgDir = path.dirname(pkgPath);
+    const binPath = path.join(pkgDir, "bin", binName);
+
+    if (fs.existsSync(binPath)) {
+      return binPath;
+    }
+  } catch (e) {
+    // Package not found in node_modules
+  }
+
+  // Try local development path (sibling directory)
+  const localBinPath = path.join(__dirname, "..", "..", localDir, "bin", binName);
+  if (fs.existsSync(localBinPath)) {
+    return localBinPath;
+  }
+
+  console.error(`devsh: Could not find binary for platform: ${platform}`);
+  console.error(`Make sure ${pkg} is installed.`);
+  console.error("");
+  console.error("Try reinstalling with:");
+  console.error("  npm install devsh");
+  process.exit(1);
+}
+
+function main() {
+  const binPath = getBinaryPath();
+  const args = process.argv.slice(2);
+
+  // Use spawn for better signal handling (especially for PTY)
+  const child = spawn(binPath, args, {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  child.on("error", (err) => {
+    console.error(`devsh: Failed to start: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      // Re-raise the signal
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  // Forward signals to child
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  for (const sig of signals) {
+    process.on(sig, () => {
+      child.kill(sig);
+    });
+  }
+}
+
+main();

package/lib/postinstall.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+// Post-install message for devsh
+// Only show in interactive terminals to avoid noise in CI
+
+const isCI = process.env.CI === 'true' ||
+             process.env.CONTINUOUS_INTEGRATION === 'true' ||
+             process.env.BUILD_NUMBER !== undefined ||
+             process.env.GITHUB_ACTIONS === 'true';
+
+const isInteractive = process.stdout.isTTY && !isCI;
+
+if (isInteractive) {
+  const message = `
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│   devsh installed successfully!                          │
+│                                                         │
+│   Get started:                                          │
+│     $ devsh login         # Login to your account       │
+│     $ devsh start         # Create a cloud VM           │
+│     $ devsh --help        # See all commands            │
+│                                                         │
+│   Documentation: https://github.com/karlorz/cmux          │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+`;
+  console.log(message);
+}

package/llms.txt

@@ -0,0 +1,70 @@
+# devsh
+
+> Cloud VMs for development - spawn isolated dev environments instantly
+
+devsh is a CLI tool for managing cloud development VMs. It provides instant access to fully configured development environments with VS Code, VNC desktop, SSH, and browser automation.
+
+## Installation
+
+```bash
+npm install -g devsh
+```
+
+## Commands
+
+### Authentication
+- `devsh login` - Login via browser
+- `devsh logout` - Logout
+- `devsh whoami` - Show current user and team
+
+### VM Management
+- `devsh start [path]` - Create new VM, optionally sync a directory
+- `devsh ls` - List all VMs (aliases: list, ps)
+- `devsh status <id>` - Show VM status and URLs
+- `devsh pause <id>` - Pause VM (preserves state)
+- `devsh resume <id>` - Resume paused VM
+- `devsh delete <id>` - Delete VM permanently
+
+### Accessing VMs
+- `devsh code <id>` - Open VS Code in browser
+- `devsh ssh <id>` - SSH into VM
+- `devsh vnc <id>` - Open VNC desktop in browser
+- `devsh pty <id>` - Interactive terminal session
+
+### Working with VMs
+- `devsh exec <id> "command"` - Execute command in VM
+- `devsh sync <id> <path>` - Sync local directory to VM
+- `devsh sync <id> <path> --pull` - Pull from VM to local
+
+### Browser Automation
+Control Chrome running in the VNC desktop:
+- `devsh computer open <id> <url>` - Navigate to URL
+- `devsh computer snapshot <id>` - Get accessibility tree with element refs (@e1, @e2)
+- `devsh computer click <id> <selector>` - Click element (use @ref or CSS selector)
+- `devsh computer type <id> "text"` - Type into focused element
+- `devsh computer fill <id> <selector> "value"` - Clear and fill input
+- `devsh computer screenshot <id> [file]` - Take screenshot
+- `devsh computer press <id> <key>` - Press key (enter, tab, escape, etc.)
+
+## Examples
+
+Create a VM and run a dev server:
+```bash
+devsh start ./my-app
+devsh exec cmux_abc123 "npm install && npm run dev"
+devsh code cmux_abc123
+```
+
+Automate browser testing:
+```bash
+devsh computer open cmux_abc123 "http://localhost:3000"
+devsh computer snapshot cmux_abc123
+devsh computer click cmux_abc123 @e1
+devsh computer screenshot cmux_abc123 test.png
+```
+
+## Links
+
+- Homepage: https://github.com/karlorz/cmux
+- Documentation: https://github.com/karlorz/cmux
+- GitHub: https://github.com/karlorz/cmux

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "devsh",
+  "version": "0.1.0",
+  "description": "Cloud VMs for development - spawn isolated dev environments instantly",
+  "keywords": [
+    "cli",
+    "devbox",
+    "cloud",
+    "vm",
+    "development",
+    "sandbox",
+    "remote",
+    "vscode"
+  ],
+  "homepage": "https://github.com/karlorz/cmux",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karlorz/cmux.git",
+    "directory": "packages/devsh"
+  },
+  "license": "MIT",
+  "author": "karlorz",
+  "bin": {
+    "devsh": "bin/devsh"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "AGENTS.md",
+    "llms.txt"
+  ],
+  "scripts": {
+    "postinstall": "node lib/postinstall.js"
+  },
+  "optionalDependencies": {
+    "devsh-darwin-arm64": "0.1.0",
+    "devsh-darwin-x64": "0.1.0",
+    "devsh-linux-arm64": "0.1.0",
+    "devsh-linux-x64": "0.1.0",
+    "devsh-win32-x64": "0.1.0"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}