@fenwave/agent 1.1.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(ls:*)",
+      "Bash(cd /Users/seif/Work/Fenwave Platform/fenwave-agent && npm pack:*)",
+      "Bash(node -p:*)"
+    ]
+  }
+}

package/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci --only=production
+
+COPY . .
+
+EXPOSE 3001
+
+CMD ["node", "index.js"]

package/LICENSE

@@ -0,0 +1,29 @@
+Copyright (c) 2025 Fenwave (Fenleap). All Rights Reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and associated documentation files (the "Software") are the
+proprietary property of Fenwave (Fenleap) and are protected by copyright law.
+
+TERMS AND CONDITIONS:
+
+1. LICENSE GRANT: Fenwave grants authorized customers a limited, non-exclusive,
+   non-transferable license to use the Software solely for their internal
+   business purposes in connection with Fenwave services.
+
+2. RESTRICTIONS: You may NOT:
+   - Copy, modify, or distribute the Software
+   - Reverse engineer, decompile, or disassemble the Software
+   - Create derivative works based on the Software
+   - Sublicense, rent, lease, or lend the Software
+   - Use the Software for any purpose other than as authorized by Fenwave
+
+3. OWNERSHIP: Fenwave retains all right, title, and interest in and to the
+   Software, including all intellectual property rights.
+
+4. NO WARRANTY: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
+
+5. LIMITATION OF LIABILITY: IN NO EVENT SHALL FENWAVE BE LIABLE FOR ANY
+   DAMAGES ARISING FROM THE USE OF THIS SOFTWARE.
+
+For licensing inquiries, contact: support@fenwave.com

package/README.md

@@ -0,0 +1,434 @@
+# Fenwave Agent
+
+The Fenwave Agent is a command-line tool that runs locally on developer machines to manage Docker containers, registries, and local development environments. It communicates with the Fenwave Backstage platform for authentication and session management.
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+## Architecture
+
+The Fenwave Agent consists of three main components:
+
+1. **Agent CLI** - Command-line interface for managing the agent and Docker operations
+2. **WebSocket Server** - Handles real-time communication with the Fenwave DevApp web application
+3. **Fenwave DevApp** - Next.js web application that provides a dashboard for managing containers, images, volumes, and more
+
+### Communication Flow
+
+```
+┌─────────────────────┐
+│  Backstage Backend  │
+│  (Authentication)   │
+└──────────┬──────────┘
+           │
+           │ HTTPS (Session Creation)
+           │
+           ▼
+    ┌──────────────┐         WebSocket (Port 3001)         ┌─────────────────┐
+    │ Agent CLI    │◄────────────────────────────────────►│ Fenwave DevApp  │
+    │ (Node.js)    │                                       │ (Next.js)       │
+    └──────┬───────┘                                       └────────┬────────┘
+           │                                                         │
+           │ Docker API                                              │ HTTP API
+           │                                                         │
+           ▼                                                         ▼
+    ┌─────────────┐                                         ┌─────────────────┐
+    │   Docker    │                                         │   Browser UI    │
+    │   Engine    │                                         │  (localhost)    │
+    └─────────────┘                                         └─────────────────┘
+```
+
+### WebSocket Authentication
+
+The agent uses token-based authentication for WebSocket connections:
+
+1. **Token Generation**: Agent generates a cryptographically secure 256-bit random token on startup
+2. **Token Storage**: Token is saved to `~/.fenwave/ws-token` with restricted permissions (0600)
+3. **Token Sharing**: The token file is mounted as a read-only volume in the Fenwave DevApp Docker container
+4. **Authentication Flow**:
+   - Client connects to WebSocket → Server sends `auth_required` challenge
+   - Client reads token from `/api/ws-token` endpoint → Sends `auth` message with token
+   - Server validates token → Responds with `auth_success` or `auth_error`
+   - Only authenticated clients can send/receive messages
+
+## Prerequisites
+
+Before installing the Fenwave Agent, ensure you have:
+
+- **Docker Desktop** (version 20.10 or later)
+  - Download: https://www.docker.com/products/docker-desktop
+  - Verify: `docker --version`
+
+- **Node.js** (version 18 or later)
+  - Download: https://nodejs.org
+  - Verify: `node --version`
+
+- **AWS CLI** (for ECR authentication)
+  - Download: https://aws.amazon.com/cli/
+  - Verify: `aws --version`
+  - Configure AWS credentials with ECR access
+
+- **Backstage Access**
+  - Access to your organization's Fenwave Backstage instance
+  - Valid user credentials
+
+## Installation
+
+### Option 1: Via Backstage (Recommended)
+
+1. Log in to your Fenwave Backstage instance
+2. Navigate to the Agent Installer page
+3. Click "Generate Installation Token"
+4. Follow the platform-specific installation instructions
+5. The installer will:
+   - Download the agent binary
+   - Configure AWS credentials
+   - Authenticate with Backstage
+   - Pull the Fenwave DevApp Docker image
+   - Start the agent
+
+### Option 2: Manual Installation
+
+1. **Clone the repository**:
+   ```bash
+   git clone <repository-url>
+   cd local-env/agent
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Configure environment**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Link the CLI globally** (optional):
+   ```bash
+   npm link
+   ```
+
+5. **Configure AWS credentials**:
+   ```bash
+   aws configure
+   # Enter your AWS Access Key ID and Secret Access Key
+   ```
+
+## Configuration
+
+The agent stores its configuration in `~/.fenwave/config/agent.json`. Configuration is set during the `fenwave init` command and persists across agent restarts and npm package updates.
+
+**Configuration file location:** `~/.fenwave/config/agent.json`
+
+**Available options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `backendUrl` | Backstage backend URL | `http://localhost:7007` |
+| `frontendUrl` | Backstage frontend URL | `http://localhost:3000` |
+| `appBuilderUrl` | App Builder API URL | Same as `backendUrl` |
+| `containerName` | Docker container name for Fenwave DevApp | `fenwave-devapp` |
+| `containerPort` | Port for Fenwave DevApp HTTP server | `3003` |
+| `wsPort` | Port for WebSocket server | `3001` |
+| `agentRootDir` | Directory for agent data (relative to home) | `.fenwave` |
+| `registriesDir` | Subdirectory for registry data | `registries` |
+| `containerDataDir` | Container data mount path | `/data` |
+| `awsRegion` | AWS region for ECR | `eu-west-1` |
+| `awsAccountId` | AWS account ID for ECR | Set from Backstage |
+| `dockerImage` | Docker image to use | Computed from AWS config |
+| `authTimeoutMs` | Authentication timeout in milliseconds | `60000` |
+
+**Configure during initialization:**
+```bash
+fenwave init \
+  --token <registration-token> \
+  --backend-url http://localhost:7007 \
+  --frontend-url http://localhost:3000 \
+  --aws-region eu-west-1
+```
+
+Note: The AWS Account ID is automatically retrieved from Backstage during device registration.
+
+**View current configuration:**
+```bash
+cat ~/.fenwave/config/agent.json
+```
+
+**Environment variable fallback:** If the configuration file doesn't exist, the agent will fall back to environment variables (for backwards compatibility).
+
+### Directory Structure
+
+The agent creates the following directory structure in your home directory:
+
+```
+~/.fenwave/
+├── config/
+│   └── agent.json        # Agent configuration (0600 permissions)
+├── session/
+│   └── config.json       # Backstage session information
+├── device/
+│   └── credential.json   # Device credentials (encrypted)
+├── setup/
+│   └── state.json        # Setup wizard state
+├── agent/
+│   └── info.json         # Agent runtime information
+├── npm/
+│   └── token             # NPM authentication token
+├── ws-token              # WebSocket authentication token (0600 permissions)
+└── registries/           # Docker registry configurations
+    ├── dockerhub.json
+    ├── ecr.json
+    └── ...
+```
+
+## Usage
+
+### Starting the Agent
+
+```bash
+# Start the agent (authenticates with Backstage)
+fenwave login
+
+# The agent will:
+# 1. Open your browser for Backstage authentication
+# 2. Create a session with the Backstage backend
+# 3. Authenticate with AWS ECR
+# 4. Pull the latest Fenwave DevApp Docker image
+# 5. Start the Fenwave DevApp container
+# 6. Start the WebSocket server
+
+# After successful startup, you'll see:
+# ✅ Fenwave Agent Started Successfully
+# 🌐 Fenwave DevApp Dashboard: http://localhost:3003
+# 🔌 WebSocket Server: ws://localhost:3001
+# 👤 User: user:default/your-username
+```
+
+### Accessing the Dashboard
+
+Once the agent is running, open your browser to:
+
+```
+http://localhost:3003
+```
+
+The dashboard provides:
+- **Containers**: View, start, stop, restart, and delete containers
+- **Images**: Pull, push, tag, and delete Docker images
+- **Volumes**: Create, backup, restore, and delete volumes
+- **Apps**: Deploy and manage multi-container applications
+- **Registries**: Connect to Docker registries (Docker Hub, ECR, private registries)
+- **Logs**: Stream real-time container logs
+- **Metrics**: View system and container resource usage
+- **Terminal**: Execute commands in running containers
+
+### Agent Commands
+
+```bash
+# Start agent and authenticate
+fenwave login
+
+# Logout and clear session
+fenwave logout
+
+# Check agent status
+fenwave status
+
+# Show agent version
+fenwave --version
+
+# Get help
+fenwave --help
+```
+
+### Docker Operations
+
+All Docker operations are performed through the web dashboard at `http://localhost:3003`. The agent provides a WebSocket API for:
+
+- Container management (start, stop, restart, delete, create, inspect)
+- Image management (pull, push, tag, delete, inspect)
+- Volume management (create, delete, inspect, backup, restore)
+- Registry management (connect, disconnect, list images)
+- Log streaming (real-time container logs)
+- Metrics collection (system and container stats)
+- Terminal sessions (exec into containers)
+
+## Security
+
+### Authentication & Authorization
+
+1. **Backstage Authentication**: Users must authenticate with Backstage before using the agent
+2. **Session Management**: Sessions are stored locally with expiration timestamps
+3. **WebSocket Token**: Cryptographically secure random token for WebSocket authentication
+4. **File Permissions**: Sensitive files (session.json, ws-token) use restrictive permissions (0600)
+
+### Network Security
+
+1. **Local-Only Communication**: WebSocket server only accepts connections from localhost
+2. **No External Exposure**: The agent does not expose any ports to the internet
+3. **TLS for Backstage**: Communication with Backstage backend uses HTTPS
+4. **ECR Authentication**: AWS credentials required for Docker image pulling
+
+### Best Practices
+
+1. **Never share your session token** - Each user has a unique session
+2. **Keep Docker updated** - Use the latest Docker Desktop version
+3. **Rotate AWS credentials regularly** - Follow your organization's security policies
+4. **Monitor agent logs** - Check for suspicious activity
+5. **Use strong Backstage passwords** - Enable 2FA if available
+
+## Troubleshooting
+
+### Agent won't start
+
+**Problem**: Agent fails to start with authentication errors
+
+**Solutions**:
+1. Check Backstage is running: `curl http://localhost:7007/api/health`
+2. Clear existing session: `rm ~/.fenwave/session.json`
+3. Verify internet connectivity
+4. Check firewall settings
+
+### Docker image pull fails
+
+**Problem**: Failed to pull local-env image from ECR
+
+**Solutions**:
+1. Verify AWS credentials: `aws sts get-caller-identity`
+2. Check ECR access: `aws ecr describe-repositories --region eu-west-1`
+3. Authenticate manually: `aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin <account>.dkr.ecr.eu-west-1.amazonaws.com`
+4. Check network/VPN connection
+
+### WebSocket connection fails
+
+**Problem**: Fenwave DevApp cannot connect to agent
+
+**Solutions**:
+1. Check agent is running: `docker ps | grep fenwave-devapp`
+2. Verify WebSocket server is listening: `lsof -i :3001`
+3. Check token file exists: `ls -la ~/.fenwave/ws-token`
+4. Restart the agent: `fenwave logout && fenwave login`
+5. Check browser console for detailed error messages
+
+### Container won't start
+
+**Problem**: Fenwave DevApp container fails to start
+
+**Solutions**:
+1. Check Docker is running: `docker info`
+2. Verify port 3003 is available: `lsof -i :3003`
+3. Check container logs: `docker logs fenwave-devapp`
+4. Remove existing container: `docker rm -f fenwave-devapp`
+5. Pull latest image: `docker pull <ecr-image>`
+
+### Session expired
+
+**Problem**: Agent reports session expired
+
+**Solutions**:
+1. Logout and login again: `fenwave logout && fenwave login`
+2. Check Backstage backend is accessible
+3. Verify system clock is synchronized
+
+## Development
+
+### Running in Development Mode
+
+```bash
+# Install dependencies
+npm install
+
+# Set up environment
+cp .env.example .env
+
+# Run the agent locally (without Docker)
+node index.js login
+
+# For Fenwave DevApp development (build from source)
+# Set DOCKER_IMAGE=fenwave-devapp in .env
+# Build image: docker build -t fenwave-devapp ..
+```
+
+### Building the Docker Image
+
+```bash
+# Build production image
+cd ../  # Go to local-env root
+docker build -f Dockerfile.prod -t fenwave-devapp:latest .
+
+# Test the image
+docker run -d \
+  --name fenwave-devapp-test \
+  -p 3003:3003 \
+  -v ~/.fenwave:/app/.fenwave:ro \
+  -e NEXT_PUBLIC_WS_URL=ws://host.docker.internal:3001 \
+  fenwave-devapp:latest
+
+# Check logs
+docker logs -f fenwave-devapp-test
+```
+
+### Publishing to ECR
+
+```bash
+# Run the publish script
+cd ../  # Go to local-env root
+./scripts/publish-image.sh v1.0.0
+
+# The script will:
+# 1. Authenticate with AWS ECR
+# 2. Build the Docker image
+# 3. Tag with version and 'latest'
+# 4. Push to ECR
+```
+
+### Project Structure
+
+```
+agent/
+├── index.js                    # Main entry point
+├── auth.js                     # Authentication & session management
+├── containerManager.js         # Docker container operations
+├── websocket-server.js         # WebSocket server setup
+├── cli-commands.js             # CLI command definitions
+├── docker-actions/             # WebSocket action handlers
+│   ├── containers.js           # Container operations
+│   ├── images.js               # Image operations
+│   ├── volumes.js              # Volume operations
+│   ├── apps.js                 # Application management
+│   ├── registry.js             # Registry operations
+│   ├── logs.js                 # Log streaming
+│   ├── metrics.js              # Metrics collection
+│   ├── terminal.js             # Terminal sessions
+│   └── general.js              # General utilities
+├── store/                      # Persistent storage
+│   ├── agentStore.js           # Agent info storage
+│   └── registryStore.js        # Registry configurations
+├── package.json                # Dependencies
+├── .env.example                # Environment template
+└── README.md                   # This file
+```
+
+## Support
+
+For issues, questions, or feature requests:
+
+1. Check the [Troubleshooting](#troubleshooting) section
+2. Review the [Fenwave documentation](https://docs.fenwave.com)
+3. Contact your Fenwave administrator
+4. File an issue in the repository (if applicable)
+
+## License
+
+Copyright © 2025 Fenwave. All rights reserved.