ember-native-devtools 1.0.3 → 3.0.0

package/README.md

@@ -0,0 +1,190 @@
+# ember-native-devtools
+
+> Ember Inspector for Node.js environments using WebSocket
+
+A lightweight Socket.IO-based server that enables [Ember Inspector](https://github.com/emberjs/ember-inspector) to work with Ember.js applications running in Node.js environments (SSR, FastBoot, custom runtimes).
+
+## Features
+
+- ✅ **No Browser Dependency** - Works with any Node.js Ember runtime
+- ✅ **Simple Setup** - ~250 lines of code total
+- ✅ **Uses Official ember-inspector** - No modifications needed
+- ✅ **Full Feature Support** - All inspector features work
+- ✅ **Easy Maintenance** - Update via `npm update ember-inspector`
+
+## Architecture
+
+```
+Inspector UI (Browser) ↔ Socket.IO ↔ Relay Server ↔ Socket.IO ↔ Node.js Ember App
+```
+
+The server acts as a simple relay between the Ember Inspector UI (running in your browser) and your Node.js Ember application, using ember-inspector's built-in WebSocket adapter.
+
+## Installation
+
+```bash
+npm install ember-native-devtools socket.io-client
+```
+
+## Quick Start
+
+### 1. Start the Inspector Server
+
+```bash
+npx ember-inspector-server
+```
+
+Or programmatically:
+
+```javascript
+import { createInspectorServer } from 'ember-native-devtools/server';
+
+const server = await createInspectorServer({
+  port: 9229,
+  host: 'localhost',
+  verbose: true
+});
+```
+
+### 2. Set Up Your Ember App
+
+```javascript
+import { setupEmberInspector, loadEmberDebug } from 'ember-native-devtools/client';
+
+// After your Ember app boots
+setupEmberInspector({
+  serverUrl: 'http://localhost:9229',
+  appName: 'My Ember App'
+});
+
+// Load ember_debug (loads node_modules/ember-inspector/dist/websocket/ember_debug.js)
+loadEmberDebug();
+```
+
+### 3. Open Inspector UI
+
+Open your browser to: `http://localhost:9229`
+
+## Configuration
+
+### Server Options
+
+```javascript
+createInspectorServer({
+  port: 9229,           // Port to listen on (default: 9229)
+  host: 'localhost',    // Host to bind to (default: 'localhost')
+  verbose: false        // Enable verbose logging (default: false)
+});
+```
+
+### Client Options
+
+```javascript
+setupEmberInspector({
+  serverUrl: 'http://localhost:9229',  // Inspector server URL
+  appName: 'My App',                   // App name for identification
+  autoConnect: true,                   // Auto-connect on setup (default: true)
+  verbose: false                       // Enable verbose logging (default: false)
+});
+```
+
+## Environment Variables
+
+- `PORT` - Server port (default: 9229)
+- `HOST` - Server host (default: localhost)
+- `INSPECTOR_URL` - Inspector server URL for client (default: http://localhost:9229)
+
+## Examples
+
+See [example-usage.js](src/example-usage.js) for complete examples including:
+- Basic setup
+- Express integration
+- Environment-specific configuration
+- Error handling
+- Testing setup
+
+## Documentation
+
+- [Implementation Guide](src/README.md) - Complete usage guide
+- [Architecture](.github/REVISED_ARCHITECTURE.md) - System design and architecture
+- [Example Usage](src/example-usage.js) - Practical examples
+
+## How It Works
+
+1. **Inspector Server** - A Socket.IO server that serves the ember-inspector UI and relays messages
+2. **Ember App Client** - Connects to the server and sets up `global.EMBER_INSPECTOR_CONFIG.remoteDebugSocket`
+3. **ember_debug** - Loaded from `ember-inspector/dist/websocket/ember_debug.js` (built into ember-inspector)
+4. **Inspector UI** - Connects to the server and communicates with your app
+
+## Use Cases
+
+- **FastBoot/SSR Apps** - Debug server-side rendered Ember applications
+- **Custom Node.js Runtimes** - Inspect Ember apps in custom Node.js environments
+- **Development Tooling** - Build development tools for non-browser Ember environments
+- **Testing** - Inspect Ember apps during automated testing
+
+## Troubleshooting
+
+### Server won't start
+- Check if port 9229 is already in use
+- Try a different port: `PORT=9230 npx ember-inspector-server`
+
+### App won't connect
+- Verify server is running
+- Check serverUrl matches server address
+- Check firewall settings
+
+### Inspector UI won't load
+- Verify ember-inspector is installed: `npm list ember-inspector`
+- Check browser console for errors
+
+### No data in Inspector
+- Verify ember_debug is loaded (check console for "✅ Ember Inspector debug loaded")
+- Verify `global.EMBER_INSPECTOR_CONFIG.remoteDebugSocket` is set
+- Check that Ember app has booted before calling setupEmberInspector
+
+## Security
+
+⚠️ **Important**: This implementation is for development only!
+
+For production use:
+- Add authentication (tokens, API keys)
+- Use HTTPS/WSS
+- Restrict CORS origins
+- Add rate limiting
+- Use environment-specific configuration
+
+## Migration from v1.x
+
+Version 2.0 is a complete rewrite that removes the Selenium/Chrome dependency:
+
+**Old (v1.x):**
+- Required Selenium WebDriver
+- Required Chrome/Chromedriver
+- Complex setup with bundled DevTools
+- ~1000+ lines of code
+
+**New (v2.x):**
+- Pure Node.js with Socket.IO
+- No browser dependencies
+- Simple setup with ember-inspector's built-in WebSocket adapter
+- ~250 lines of code
+
+To migrate, simply update your package.json and follow the Quick Start guide above.
+
+## Contributing
+
+Contributions are welcome! Please see the [implementation guide](src/README.md) for details on the architecture.
+
+## License
+
+MIT
+
+## Credits
+
+- [Ember Inspector](https://github.com/emberjs/ember-inspector) - The official Ember debugging tool
+- [Socket.IO](https://socket.io/) - Real-time bidirectional event-based communication
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.

package/package.json

@@ -1,34 +1,52 @@
 {
   "name": "ember-native-devtools",
-  "version": "1.0.3",
+  "version": "3.0.0",
+  "description": "Ember Inspector for Node.js environments using WebSocket",
   "repository": {
     "type": "git",
     "url": "git@github.com:ember-native/ember-devtools.git"
   },
+  "type": "module",
+  "main": "src/inspector-server.mjs",
+  "exports": {
+    ".": "./src/inspector-server.js",
+    "./server": "./src/inspector-server.js",
+    "./client": "./src/setup-inspector.js"
+  },
   "bin": {
-    "ember-devtools": "bin/devtools.js"
+    "ember-inspector-server": "src/inspector-server.mjs"
   },
   "engines": {
     "node": ">=18"
   },
   "files": [
-    "bin",
-    "download"
+    "src/"
+  ],
+  "keywords": [
+    "ember",
+    "inspector",
+    "devtools",
+    "debugging",
+    "websocket",
+    "nodejs",
+    "ssr",
+    "fastboot"
   ],
   "dependencies": {
-    "selenium-webdriver": "^4.25.0",
-    "chromedriver": "^129.0.2",
-    "ember-inspector": "^4.13.1"
+    "express": "^4.21.2",
+    "socket.io": "^4.8.1",
+    "ember-inspector": "^4.15.1"
+  },
+  "peerDependencies": {
+    "socket.io-client": "^4.0.0"
   },
   "devDependencies": {
-    "@babel/parser": "^7.25.6",
-    "@babel/traverse": "^7.25.6",
-    "website-scraper": "^5.3.1",
-    "website-scraper-puppeteer": "^1.1.0",
-    "@rollup/plugin-commonjs": "^28.0.0",
-    "release-plan": "^0.9.0"
+    "release-plan": "^0.16.0"
   },
+  "author": "Patrick Pircher",
+  "license": "MIT",
   "scripts": {
-    "run": "node bin/devtools.js"
+    "start": "node src/inspector-server.mjs",
+    "server": "node src/inspector-server.mjs"
   }
 }

package/src/README.md

@@ -0,0 +1,207 @@
+# Implementation Guide
+
+This directory contains the complete implementation for the Ember Inspector WebSocket server.
+
+## Files
+
+1. **inspector-server.js** - Socket.IO relay server (~130 lines)
+2. **setup-inspector.js** - Ember app setup helper (~120 lines)
+
+## Installation
+
+### 1. Install Dependencies
+
+```bash
+# In your project root
+npm install express socket.io socket.io-client ember-inspector
+```
+
+### 2. Start the Inspector Server
+
+```bash
+# Copy inspector-server.js to your project
+cp .github/implementation/inspector-server.js ./
+
+# Run the server
+node inspector-server.js
+```
+
+Or use it programmatically:
+
+```javascript
+import { createInspectorServer } from './inspector-server.mjs';
+
+const server = await createInspectorServer({
+  port: 9229,
+  host: 'localhost',
+  verbose: true
+});
+
+// Later, to stop:
+await server.stop();
+```
+
+### 3. Set Up Your Ember App
+
+```javascript
+// Copy setup-inspector.js to your project
+import { setupEmberInspector, loadEmberDebug } from './setup-inspector.js';
+
+// After your Ember app boots
+setupEmberInspector({
+  serverUrl: 'http://localhost:9229',
+  appName: 'My Ember App',
+  verbose: true
+});
+
+// Load ember_debug (if in browser environment)
+loadEmberDebug();
+```
+
+## Usage
+
+### Starting Everything
+
+**Terminal 1: Start Inspector Server**
+```bash
+node inspector-server.js
+```
+
+**Terminal 2: Start Your Ember App**
+```bash
+# Your Ember app should call setupEmberInspector() on boot
+node your-ember-app.js
+```
+
+**Browser: Open Inspector UI**
+```
+http://localhost:9229
+```
+
+## Expected Output
+
+### Server Console
+```
+🔍 Ember Inspector Server
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📡 Server running at: http://localhost:9229
+🌐 Inspector UI: http://localhost:9229
+🔌 WebSocket: ws://localhost:9229
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Waiting for connections...
+
+✅ Ember app connected
+✅ Inspector UI connected
+```
+
+### Ember App Console
+```
+[Ember Inspector] Connecting to inspector server at http://localhost:9229...
+✅ Connected to Ember Inspector server
+✅ Ember Inspector debug loaded
+```
+
+## Configuration
+
+### Server Options
+
+```javascript
+createInspectorServer({
+  port: 9229,           // Port to listen on
+  host: 'localhost',    // Host to bind to
+  verbose: false        // Enable verbose logging
+});
+```
+
+### Client Options
+
+```javascript
+setupEmberInspector({
+  serverUrl: 'http://localhost:9229',  // Inspector server URL
+  appName: 'My App',                   // App name for identification
+  autoConnect: true,                   // Auto-connect on setup
+  verbose: false                       // Enable verbose logging
+});
+```
+
+## Environment Variables
+
+- `PORT` - Server port (default: 9229)
+- `HOST` - Server host (default: localhost)
+- `INSPECTOR_URL` - Inspector server URL for client (default: http://localhost:9229)
+
+## Troubleshooting
+
+### Server won't start
+- Check if port 9229 is already in use
+- Try a different port: `PORT=9230 node inspector-server.js`
+
+### App won't connect
+- Verify server is running
+- Check serverUrl matches server address
+- Check firewall settings
+
+### Inspector UI won't load
+- Verify ember-inspector is installed: `npm list ember-inspector`
+- Check browser console for errors
+- Verify server is serving static files from correct path
+
+### No data in Inspector
+- Verify ember_debug is loaded (check browser console)
+- Verify `window.EMBER_INSPECTOR_CONFIG.remoteDebugSocket` is set
+- Check that Ember app has booted before calling setupEmberInspector
+
+## Integration with Existing Projects
+
+### For FastBoot/SSR Apps
+
+```javascript
+// In your FastBoot app
+import { setupEmberInspector } from './setup-inspector.js';
+
+// After FastBoot initializes
+setupEmberInspector({
+  serverUrl: process.env.INSPECTOR_URL || 'http://localhost:9229'
+});
+```
+
+### For Custom Node.js Runtimes
+
+```javascript
+// In your custom runtime
+import { setupEmberInspector } from './setup-inspector.js';
+
+// Set up global environment
+global.EMBER_INSPECTOR_CONFIG = {
+  remoteDebugSocket: null  // Will be set by setupEmberInspector
+};
+
+// After Ember loads
+setupEmberInspector();
+```
+
+## Next Steps
+
+1. Test with your Ember app
+2. Customize server/client as needed
+3. Add authentication if needed
+4. Deploy to production (with proper security)
+
+## Security Considerations
+
+⚠️ **Important**: This implementation is for development only!
+
+For production use:
+- Add authentication (tokens, API keys)
+- Use HTTPS/WSS
+- Restrict CORS origins
+- Add rate limiting
+- Use environment-specific configuration
+
+## Support
+
+For issues or questions:
+- Check the REVISED_ARCHITECTURE.md for design details
+- Review ember-inspector documentation
+- Check Socket.IO documentation

package/src/example-usage.js

@@ -0,0 +1,199 @@
+// ============================================================================
+// EXAMPLE 1: Starting the Inspector Server
+// ============================================================================
+
+import { createInspectorServer } from './inspector-server.mjs';
+
+// Start server with default options
+const server = await createInspectorServer();
+
+// Or with custom options
+const customServer = await createInspectorServer({
+  port: 9230,
+  host: '0.0.0.0',  // Listen on all interfaces
+  verbose: true      // Enable detailed logging
+});
+
+// Stop server when done
+// await server.stop();
+
+
+// ============================================================================
+// EXAMPLE 2: Setting Up Ember App (Browser Environment)
+// ============================================================================
+
+import { setupEmberInspector, loadEmberDebug } from './setup-inspector.js';
+
+// In your Ember app's boot sequence
+async function bootEmberApp() {
+  // ... your Ember app initialization ...
+  
+  // Set up inspector connection
+  const inspector = setupEmberInspector({
+    serverUrl: 'http://localhost:9229',
+    appName: 'My Ember App',
+    verbose: true
+  });
+
+  // Load ember_debug after Ember boots
+  loadEmberDebug();
+
+  // Optional: disconnect later
+  // inspector.disconnect();
+}
+
+
+// ============================================================================
+// EXAMPLE 3: Setting Up Ember App (Node.js Environment)
+// ============================================================================
+
+import { setupEmberInspector } from './setup-inspector.js';
+
+// For Node.js Ember apps (SSR, FastBoot, etc.)
+function setupNodeEmberApp() {
+  // Set up inspector
+  const inspector = setupEmberInspector({
+    serverUrl: process.env.INSPECTOR_URL || 'http://localhost:9229',
+    appName: process.env.APP_NAME || 'Ember SSR App',
+    autoConnect: true,
+    verbose: process.env.NODE_ENV === 'development'
+  });
+
+  // The inspector will automatically connect
+  // ember_debug will be loaded when available
+  
+  return inspector;
+}
+
+
+// ============================================================================
+// EXAMPLE 4: Complete Setup with Error Handling
+// ============================================================================
+
+async function setupInspectorWithErrorHandling() {
+  try {
+    // Start server
+    const server = await createInspectorServer({
+      port: process.env.INSPECTOR_PORT || 9229,
+      verbose: true
+    });
+
+    console.log('Inspector server started successfully');
+
+    // Set up client
+    const inspector = setupEmberInspector({
+      serverUrl: `http://localhost:${process.env.INSPECTOR_PORT || 9229}`,
+      appName: 'My App'
+    });
+
+    // Handle process termination
+    process.on('SIGINT', async () => {
+      console.log('\nShutting down...');
+      inspector.disconnect();
+      await server.stop();
+      process.exit(0);
+    });
+
+    return { server, inspector };
+  } catch (error) {
+    console.error('Failed to set up inspector:', error);
+    process.exit(1);
+  }
+}
+
+
+// ============================================================================
+// EXAMPLE 5: Using with Express App
+// ============================================================================
+
+import express from 'express';
+import { createInspectorServer } from './inspector-server.mjs';
+
+async function setupWithExpress() {
+  // Your existing Express app
+  const app = express();
+  
+  // ... your routes ...
+
+  // Start your app
+  const appServer = app.listen(3000, () => {
+    console.log('App running on http://localhost:3000');
+  });
+
+  // Start inspector server on different port
+  const inspectorServer = await createInspectorServer({
+    port: 9229
+  });
+
+  return { appServer, inspectorServer };
+}
+
+
+// ============================================================================
+// EXAMPLE 6: Environment-Specific Configuration
+// ============================================================================
+
+const config = {
+  development: {
+    serverUrl: 'http://localhost:9229',
+    verbose: true,
+    autoConnect: true
+  },
+  staging: {
+    serverUrl: 'http://staging-inspector.example.com',
+    verbose: false,
+    autoConnect: true
+  },
+  production: {
+    // Don't enable inspector in production!
+    serverUrl: null,
+    verbose: false,
+    autoConnect: false
+  }
+};
+
+function setupForEnvironment(env = 'development') {
+  const envConfig = config[env];
+  
+  if (!envConfig.serverUrl) {
+    console.log('Inspector disabled for this environment');
+    return null;
+  }
+
+  return setupEmberInspector(envConfig);
+}
+
+
+// ============================================================================
+// EXAMPLE 7: Testing Setup
+// ============================================================================
+
+import { createInspectorServer } from './inspector-server.mjs';
+import { setupEmberInspector } from './setup-inspector.js';
+
+async function testInspectorSetup() {
+  console.log('Starting inspector server...');
+  const server = await createInspectorServer({ verbose: true });
+
+  console.log('Connecting client...');
+  const inspector = setupEmberInspector({
+    serverUrl: 'http://localhost:9229',
+    verbose: true
+  });
+
+  // Wait for connection
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  if (inspector.isConnected) {
+    console.log('✅ Inspector setup successful!');
+  } else {
+    console.log('❌ Inspector setup failed');
+  }
+
+  // Cleanup
+  inspector.disconnect();
+  await server.stop();
+}
+
+// Run test
+// testInspectorSetup();