synapse-sdk 1.0.0b3__tar.gz → 1.0.0b5__tar.gz

{synapse_sdk-1.0.0b3 → synapse_sdk-1.0.0b5}/.gitignore

@@ -34,6 +34,7 @@ messages.pot
 
 # Frontend development (keep only built assets)
 node_modules/
+dist/
 npm-debug.log*
 
 config.yaml*

{synapse_sdk-1.0.0b3/synapse_sdk.egg-info → synapse_sdk-1.0.0b5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapse-sdk
-Version: 1.0.0b3
+Version: 1.0.0b5
 Summary: synapse sdk
 Author-email: datamaker <developer@datamaker.io>
 License: MIT

synapse_sdk-1.0.0b5/docs/cli-usage.md

@@ -0,0 +1,280 @@
+---
+id: cli-usage
+title: CLI Usage Guide
+sidebar_position: 4
+---
+
+# CLI Usage Guide
+
+The Synapse SDK provides a powerful interactive CLI for managing your development workflow, from configuration to plugin development and code editing.
+
+## Getting Started
+
+Launch the interactive CLI:
+
+```bash
+synapse
+```
+
+Or run specific commands directly:
+
+```bash
+# Start development tools immediately
+synapse --dev-tools
+
+# Show help
+synapse --help
+```
+
+## Main Menu Options
+
+When you run `synapse`, you'll see the main menu:
+
+```
+🚀 Synapse SDK
+Select an option:
+  🌐 Run Dev Tools
+  💻 Open Code-Server IDE
+  ⚙️  Configuration
+  🔌 Plugin Management
+  🚪 Exit
+```
+
+## 🌐 Run Dev Tools
+
+Launches the Synapse development tools dashboard with:
+
+- **Interactive UI**: Web-based dashboard for managing agents and jobs
+- **Real-time Monitoring**: Live view of agent status and job execution
+- **Plugin Management**: Upload, test, and manage plugins through the UI
+
+### Usage
+```bash
+# Launch dev tools from CLI menu
+synapse
+
+# Or start directly
+synapse --dev-tools
+```
+
+## 💻 Open Code-Server IDE
+
+Opens a web-based VS Code environment for plugin development. Supports both agent-based and local code-server instances.
+
+### Agent Code-Server
+
+Connect to a remote code-server running on an agent:
+
+- **Automatic Setup**: Synapse configures the workspace and installs dependencies
+- **Plugin Encryption**: Local plugin code is encrypted and securely transferred
+- **Workspace Sync**: Your local project is available in the agent environment
+
+### Local Code-Server
+
+Launch a local code-server instance:
+
+- **Port Detection**: Automatically reads port from `~/.config/code-server/config.yaml`
+- **Folder Parameter**: Opens with correct workspace directory
+- **Browser Integration**: Automatically opens browser with proper URL
+
+### Usage Examples
+
+```bash
+# Interactive menu (recommended)
+synapse
+# Select "💻 Open Code-Server IDE"
+
+# Direct command
+synapse code-server
+
+# With specific options
+synapse code-server --agent my-agent --workspace /path/to/project
+
+# Don't open browser automatically
+synapse code-server --no-open-browser
+```
+
+### Code-Server Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--agent` | Specific agent ID to use | Current agent or prompt |
+| `--workspace` | Project directory path | Current directory |
+| `--open-browser/--no-open-browser` | Open browser automatically | `--open-browser` |
+
+### Local Code-Server Installation
+
+If code-server isn't installed locally, the CLI provides installation instructions:
+
+```bash
+# Recommended: Install script
+curl -fsSL https://code-server.dev/install.sh | sh
+
+# Using npm
+npm install -g code-server
+
+# Using yarn
+yarn global add code-server
+```
+
+For more options, visit: https://coder.com/docs/code-server/latest/install
+
+## ⚙️ Configuration
+
+Interactive configuration wizard for setting up:
+
+- **Backend Connection**: Configure API endpoints and authentication
+- **Agent Selection**: Choose and configure development agents
+- **Token Management**: Manage access tokens and authentication
+
+### Configuration Files
+
+Synapse stores configuration in:
+- **Backend Config**: `~/.synapse/devtools.yaml`
+- **Agent Config**: `~/.synapse/devtools.yaml` (agent section)
+- **Code-Server Config**: `~/.config/code-server/config.yaml`
+
+## 🔌 Plugin Management
+
+Comprehensive plugin development and management tools:
+
+### Create New Plugin
+
+```bash
+synapse
+# Select "🔌 Plugin Management" → "Create new plugin"
+```
+
+Interactive wizard creates:
+- Plugin directory structure
+- Configuration files (`config.yaml`)
+- Example plugin code
+- Requirements and dependencies
+
+### Run Plugin Locally
+
+Test plugins in different environments:
+
+```bash
+# Script execution (local)
+synapse plugin run my_action '{"param": "value"}' --run-by script
+
+# Agent execution (remote)
+synapse plugin run my_action '{"param": "value"}' --run-by agent
+
+# Backend execution (cloud)
+synapse plugin run my_action '{"param": "value"}' --run-by backend
+```
+
+### Publish Plugin
+
+Deploy plugins to your Synapse backend:
+
+```bash
+synapse
+# Select "🔌 Plugin Management" → "Publish plugin"
+```
+
+Options:
+- **Debug Mode**: Test deployment with verbose logging
+- **Production Mode**: Deploy for live use
+
+## Command Reference
+
+### Main Commands
+
+```bash
+# Interactive CLI (main menu)
+synapse
+
+# Development tools
+synapse --dev-tools
+
+# Direct commands
+synapse config         # Configuration wizard
+synapse devtools       # Development dashboard
+synapse code-server    # Code editing environment
+synapse plugin         # Plugin management
+```
+
+### Code-Server Command
+
+```bash
+synapse code-server [OPTIONS]
+
+Options:
+  --agent TEXT                    Agent name or ID
+  --open-browser / --no-open-browser
+                                  Open in browser [default: open-browser]
+  --workspace TEXT                Workspace directory path (defaults to current directory)
+  --help                          Show this message and exit.
+```
+
+### Plugin Commands
+
+```bash
+# Create plugin
+synapse plugin create
+
+# Run plugin
+synapse plugin run ACTION PARAMS [OPTIONS]
+
+# Publish plugin  
+synapse plugin publish [OPTIONS]
+```
+
+## Tips & Best Practices
+
+### Code-Server Development
+
+1. **Plugin Detection**: When opening code-server, Synapse automatically detects if your workspace contains a plugin and encrypts it for secure transfer to agents.
+
+2. **Workspace Paths**: Agent workspaces typically use `/home/coder/workspace` - this is normal for containerized environments.
+
+3. **Port Configuration**: Local code-server port is read from your config file, defaulting to 8880 if not configured.
+
+### Configuration Management
+
+1. **Token Security**: Store API tokens securely and rotate them regularly
+2. **Agent Selection**: Use descriptive agent names to identify their purpose
+3. **Backend URLs**: Ensure backend URLs are accessible from your development environment
+
+### Plugin Development
+
+1. **Local Testing**: Always test plugins locally with `--run-by script` before deploying
+2. **Debug Mode**: Use debug mode for initial deployments to catch issues early
+3. **Version Control**: Use git to track plugin changes and manage versions
+
+## Troubleshooting
+
+### Code-Server Issues
+
+**Problem**: "Code-server is not available"
+- **Solution**: Ensure the agent has code-server support enabled
+
+**Problem**: Browser doesn't open automatically
+- **Solution**: Manually copy the provided URL to your browser
+
+**Problem**: Wrong port displayed
+- **Solution**: Check `~/.config/code-server/config.yaml` for correct port configuration
+
+### Configuration Issues
+
+**Problem**: "No backend configured"
+- **Solution**: Run `synapse config` to set up backend connection
+
+**Problem**: "Invalid token (401)"
+- **Solution**: Generate a new API token and update configuration
+
+**Problem**: "Connection timeout"
+- **Solution**: Check network connectivity and backend URL accessibility
+
+### Plugin Issues
+
+**Problem**: Plugin not detected in workspace
+- **Solution**: Ensure your directory has a valid `config.yaml` file
+
+**Problem**: Plugin execution fails
+- **Solution**: Check plugin dependencies and syntax, test locally first
+
+For more troubleshooting help, see the [Troubleshooting Guide](./troubleshooting.md).

synapse_sdk-1.0.0b5/docs/faq.md

@@ -0,0 +1,179 @@
+---
+id: faq
+title: Frequently Asked Questions
+sidebar_position: 9
+---
+
+# Frequently Asked Questions
+
+Common questions and answers about Synapse SDK.
+
+## Installation & Setup
+
+### Q: What Python versions are supported?
+
+Synapse SDK requires **Python 3.10 or higher**.
+
+```bash
+pip install "synapse-sdk[all,devtools]"
+```
+
+### Q: How do I install code-server for local development?
+
+You have several options:
+
+```bash
+# Recommended: Install script
+curl -fsSL https://code-server.dev/install.sh | sh
+
+# Using npm
+npm install -g code-server
+
+# Using yarn
+yarn global add code-server
+```
+
+For more installation methods, visit: [code-server installation guide](https://coder.com/docs/code-server/latest/install)
+
+## CLI Usage
+
+### Q: How do I start the Synapse CLI?
+
+Simply run:
+
+```bash
+synapse
+```
+
+This opens the interactive menu where you can access all Synapse features.
+
+### Q: What's the difference between agent and local code-server?
+
+- **Agent Code-Server**: Runs on a remote agent with your project files synced. Includes plugin encryption and secure transfer.
+- **Local Code-Server**: Runs on your local machine. Faster startup, uses your local environment and settings.
+
+### Q: How do I configure the code-server port?
+
+Code-server port is automatically detected from `~/.config/code-server/config.yaml`. If no config exists, it defaults to port 8880.
+
+Example config:
+
+```yaml
+bind-addr: 127.0.0.1:8880
+auth: password
+password: your-password-here
+cert: false
+```
+
+### Q: Why does the agent workspace path differ from my local path?
+
+Agents run in containerized environments where your local project is mounted to `/home/coder/workspace`. This is normal and ensures consistent paths across different development environments.
+
+## Code-Server Troubleshooting
+
+### Q: Code-server shows "not available" error
+
+This usually means:
+
+1. The agent doesn't have code-server support enabled
+2. Network connectivity issues
+3. Agent is not properly configured
+
+**Solution**: Reinstall the agent with code-server support, or check agent configuration.
+
+### Q: Browser doesn't open automatically
+
+This happens in headless environments or when display is not available.
+
+**Solution**: Manually copy the provided URL (including the `?folder=` parameter) to your browser.
+
+### Q: Plugin not detected in workspace
+
+**Solution**: Ensure your directory contains a valid `config.yaml` file with plugin metadata:
+
+```yaml
+name: my-plugin
+version: 1.0.0
+description: My awesome plugin
+entry_point: main.py
+```
+
+### Q: How does plugin encryption work?
+
+When opening code-server with an agent, Synapse:
+
+1. Detects if your workspace contains a plugin
+2. Creates a ZIP archive of the plugin files
+3. Encrypts the archive using AES-256 encryption
+4. Securely transfers it to the agent
+5. Decrypts and extracts it in the agent workspace
+
+This ensures your plugin code is protected during transfer.
+
+## Configuration
+
+### Q: Where are configuration files stored?
+
+- **Synapse Config**: `~/.synapse/devtools.yaml`
+- **Code-Server Config**: `~/.config/code-server/config.yaml`
+
+### Q: How do I reset my configuration?
+
+```bash
+# Remove configuration files
+rm ~/.synapse/devtools.yaml
+rm ~/.config/code-server/config.yaml
+
+# Run configuration wizard
+synapse config
+```
+
+### Q: What if I get "Invalid token (401)" error?
+
+This means your API token is expired or invalid.
+
+**Solution**:
+
+1. Generate a new token from your Synapse backend
+2. Run `synapse config` to update the token
+3. Test connection with `synapse --dev-tools`
+
+## Plugin Development
+
+### Q: How do I create a new plugin?
+
+Use the interactive plugin creator:
+
+```bash
+synapse
+# Select "🔌 Plugin Management" → "Create new plugin"
+```
+
+This creates a complete plugin structure with examples and documentation.
+
+### Q: How do I test plugins locally?
+
+```bash
+# Test with local script execution
+synapse plugin run my_action '{"param": "value"}' --run-by script
+
+# Test with agent execution
+synapse plugin run my_action '{"param": "value"}' --run-by agent
+```
+
+Always test locally before publishing to ensure your plugin works correctly.
+
+### Q: Plugin publishing fails with errors
+
+Common issues:
+
+1. **Missing dependencies**: Ensure `requirements.txt` includes all needed packages
+2. **Syntax errors**: Test locally first with `--run-by script`
+3. **Configuration errors**: Check `config.yaml` format and required fields
+4. **Backend connectivity**: Ensure backend is accessible and token is valid
+
+**Solution**: Use debug mode for detailed error information:
+
+```bash
+synapse plugin publish --debug
+```

{synapse_sdk-1.0.0b3 → synapse_sdk-1.0.0b5}/docs/installation.md

@@ -33,10 +33,10 @@ For additional features, install with extras:
 pip install synapse-sdk[all]
 
 # Install with dashboard dependencies (FastAPI, Uvicorn)
-pip install synapse-sdk[dashboard]
+pip install synapse-sdk[devtools]
 
 # Install both
-pip install synapse-sdk[all,dashboard]
+pip install "synapse-sdk[all,devtools]"
 ```
 
 ### Install from Source
@@ -49,7 +49,7 @@ cd synapse-sdk
 pip install -e .
 
 # With optional dependencies
-pip install -e ".[all,dashboard]"
+pip install -e ".[all,devtools]"
 ```
 
 ## Verify Installation

synapse_sdk-1.0.0b5/docs/quickstart.md

@@ -0,0 +1,78 @@
+---
+id: quickstart
+title: Quickstart Guide
+sidebar_position: 3
+---
+
+# Quickstart Guide
+
+Get up and running with Synapse SDK in minutes.
+
+## Interactive CLI
+
+Launch the Synapse CLI to access all features through an interactive menu:
+
+```bash
+synapse
+```
+
+This opens the main menu with options for:
+
+- 🌐 **Dev Tools**: Web-based dashboard for agent and job management
+- 💻 **Code-Server IDE**: Web-based VS Code for plugin development
+- ⚙️ **Configuration**: Setup backend connections and agents
+- 🔌 **Plugin Management**: Create, test, and publish plugins
+
+## Quick Commands
+
+For faster access to specific features:
+
+```bash
+# Start development tools immediately
+synapse --dev-tools
+
+# Configure backend and agents
+synapse config
+
+# Open code editing environment
+synapse code-server
+
+# Create a new plugin
+synapse plugin create
+```
+
+## Your First Plugin
+
+1. **Create a plugin**:
+
+   ```bash
+   synapse
+   # Select "🔌 Plugin Management" → "Create new plugin"
+   ```
+
+2. **Edit in Code-Server**:
+
+   ```bash
+   synapse
+   # Select "💻 Open Code-Server IDE"
+   ```
+
+3. **Test locally**:
+
+   ```bash
+   synapse plugin run my_action '{"param": "value"}' --run-by script
+   ```
+
+4. **Publish to backend**:
+
+   ```bash
+   synapse
+   # Select "🔌 Plugin Management" → "Publish plugin"
+   ```
+
+## Next Steps
+
+- Read the complete [CLI Usage Guide](./cli-usage.md)
+- Learn about [Core Concepts](./concepts/index.md)
+- Explore the [API Reference](./api/index.md)
+- Check [Frequently Asked Questions](./faq.md)

{synapse_sdk-1.0.0b3 → synapse_sdk-1.0.0b5}/synapse_sdk/cli/__init__.py

@@ -273,7 +273,7 @@ def cli(ctx, dev_tools):
                         message='Select an option:',
                         choices=[
                             ('🌐 Run Dev Tools', 'devtools'),
-                            ('💻 Code-Server IDE', 'code_server'),
+                            ('💻 Open Code-Server IDE', 'code_server'),
                             ('⚙️  Configuration', 'config'),
                             ('🔌 Plugin Management', 'plugin'),
                             ('🚪 Exit', 'exit'),