gravity-core 1.0.1 → 1.0.3

package/README.md

@@ -14,7 +14,7 @@ Gravity will:
 3. Analyze its position, styles, and visibility
 4. Return specific issues and fixes
 
-## 🚀 Quick Start (2 minutes)
+## 🚀 Quick Start (5 minutes)
 
 ### 1. Install Package
 
@@ -22,21 +22,48 @@ Gravity will:
 npm install gravity-core
 ```
 
-### 2. Load Chrome Extension
+### 2. Setup Extension
 
-1. Go to `chrome://extensions`
-2. Enable "Developer mode"
+```bash
+gravity setup-extension
+```
+
+This extracts the Chrome extension to `~/.gravity-extension`.
+
+### 3. Setup Native Host
+
+```bash
+gravity setup-native-host
+```
+
+This:
+- Auto-detects your Gravity extension ID
+- Asks for confirmation before modifying registry
+- Sets up native messaging for Chrome
+- Optionally restarts Chrome
+
+### 4. Load Extension in Chrome
+
+1. Open Chrome and go to `chrome://extensions`
+2. Enable "Developer mode" (toggle in top right)
 3. Click "Load unpacked"
-4. Select the `extension/` folder from the repo
+4. Select the `~/.gravity-extension` folder
 5. ✅ Done!
 
-### 3. Connect to Tab
+### 5. Test Connection
+
+```bash
+gravity test-connection
+```
 
-1. Click the Gravity extension icon
-2. Click "Connect to Tab"
-3. Status turns 🟢 Green
+This verifies:
+- ✅ Registry key exists
+- ✅ Manifest is valid
+- ✅ Extension ID is configured
+- ✅ Native host is executable
+- ✅ WebSocket connection works
 
-### 4. Configure Your IDE
+### 6. Configure Your IDE
 
 **VSCode:**
 ```json
@@ -70,7 +97,7 @@ Same as VSCode
 **Warp or any IDE with MCP:**
 Add the same config to your IDE's MCP settings.
 
-### 5. Start Diagnosing
+### 7. Start Diagnosing
 
 Ask your AI:
 - "Diagnose the #modal element"
@@ -111,7 +138,7 @@ Your IDE (VSCode, Cursor, Kiro, etc.)
     ↓
 MCP Server (gravity-core)
     ↓
-WebSocket Connection (port 9224)
+Native Messaging Host (Windows Registry)
     ↓
 Chrome Extension (running native bridge)
     ↓
@@ -133,13 +160,15 @@ Browser Tab (DOM, CSS, Layout data)
 
 ### Fix Offscreen Modal
 
-1. Browser: Open page with broken layout
-2. Extension: Click icon → "Connect to Tab" (🟢 Green)
-3. IDE: Ask AI: "Diagnose the .modal element"
-4. AI: Shows "Element extends 50px beyond right edge"
-5. You: Add `max-width: 100%` to CSS
-6. Browser: Refreshes automatically
-7. AI: Diagnose again → ✅ Fixed!
+1. Terminal: Run `gravity setup-extension` and `gravity setup-native-host`
+2. Chrome: Load extension from `~/.gravity-extension`
+3. Browser: Open page with broken layout
+4. Extension: Click icon → "Connect to Tab" (🟢 Green)
+5. IDE: Ask AI: "Diagnose the .modal element"
+6. AI: Shows "Element extends 50px beyond right edge"
+7. You: Add `max-width: 100%` to CSS
+8. Browser: Refreshes automatically
+9. AI: Diagnose again → ✅ Fixed!
 
 ### Debug Hidden Element
 
@@ -150,6 +179,64 @@ Browser Tab (DOM, CSS, Layout data)
 5. You: Change CSS to `display: block`
 6. AI: Diagnose again → ✅ Visible!
 
+## 🔧 CLI Commands
+
+### Setup Extension
+
+Extract the Chrome extension to your home directory:
+
+```bash
+gravity setup-extension
+```
+
+Creates `~/.gravity-extension/` ready to load in Chrome.
+
+### Setup Native Host
+
+Configure native messaging for Chrome:
+
+```bash
+gravity setup-native-host
+```
+
+This command:
+- Auto-detects your Gravity extension ID
+- Asks for confirmation before modifying registry
+- Copies native host to `~/.gravity-host/`
+- Patches manifest with extension ID
+- Writes Windows registry entry
+- Optionally restarts Chrome
+
+### Test Connection
+
+Verify everything is working:
+
+```bash
+gravity test-connection
+```
+
+Checks:
+- Registry key exists
+- Manifest file is valid
+- Extension ID is configured
+- Native host is executable
+- WebSocket connection works
+- Browser handshake succeeds
+
+### Start MCP Server
+
+Run the MCP server (used by your IDE):
+
+```bash
+gravity
+```
+
+### Show Help
+
+```bash
+gravity --help
+```
+
 ## 🔧 API Reference
 
 ### Gravity
@@ -215,27 +302,44 @@ bridge.on('error', (error) => {
 
 ## 🐛 Troubleshooting
 
-**"Not connected to browser"**
-- Make sure Chrome/Edge is open
-- Click extension icon → "Connect to Tab"
-- Status should turn green
+### "Could not find Gravity extension"
+
+**Solution:**
+1. Run `gravity setup-extension`
+2. Open Chrome and go to `chrome://extensions`
+3. Enable "Developer mode"
+4. Click "Load unpacked"
+5. Select `~/.gravity-extension`
+6. Run `gravity setup-native-host`
 
-**"Extension not loaded"**
-- Go to `chrome://extensions`
-- Enable "Developer mode"
-- Click "Load unpacked"
-- Select the `extension/` folder
+### "Registry key not found"
 
-**"Port 9224 already in use"**
-- Edit extension's `background.js`
-- Change `WEBSOCKET_PORT` to 9225
-- Update IDE config with `GRAVITY_PORT: 9225`
+**Solution:**
+- Run `gravity setup-native-host` again
+- You may need to run as Administrator
+- Check that Chrome is installed in the default location
 
-**"Element not found"**
+### "WebSocket connection failed"
+
+**Solution:**
+- Make sure the MCP server is running: `gravity`
+- Check that port 9224 is not blocked by firewall
+- Try a different port: `GRAVITY_PORT=9225 gravity`
+
+### "Element not found"
+
+**Solution:**
 - Check selector is correct
 - Make sure element exists in page
 - Try simpler selector: `div` instead of `#modal`
 
+### "Chrome is running" warning
+
+**Solution:**
+- The setup will ask if you want to restart Chrome
+- Restart Chrome manually if you prefer
+- Changes take effect after restart
+
 ## 📖 Documentation
 
 - [Setup Guide](./SETUP.md) - Complete setup instructions
@@ -256,6 +360,8 @@ bridge.on('error', (error) => {
 - ✅ No external API calls
 - ✅ All data stays local
 - ✅ No user data collection
+- ✅ Registry changes require explicit user confirmation
+- ✅ No silent installations or modifications
 
 ## 📝 License
 
@@ -267,7 +373,7 @@ Contributions welcome! Please open an issue or PR on GitHub.
 
 ## 📞 Support
 
-- [GitHub Issues](https://github.com/gravity/core/issues)
+- [GitHub Issues](https://github.com/DharuNamikaze/Gravity-Package/issues)
 - [Documentation](https://gravity.dev)
 
 ---
@@ -276,6 +382,9 @@ Contributions welcome! Please open an issue or PR on GitHub.
 
 ```bash
 npm install gravity-core
+gravity setup-extension
+gravity setup-native-host
+gravity test-connection
 ```
 
-Then load the extension and configure your IDE. Happy debugging! 🎉
+Then configure your IDE and start debugging! 🎉