@fenwave/agent 1.1.0 → 1.1.1

package/README.md

@@ -1,434 +1,68 @@
 # 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
+The Fenwave Agent is a CLI tool for managing Docker containers and local development environments. It integrates with the Fenwave platform for seamless developer experience.
 
 ## 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
+- **Fenwave Platform Access** - Valid credentials from your organization
 
 ## 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
+npm install -g @fenwave/agent
 ```
 
-**Environment variable fallback:** If the configuration file doesn't exist, the agent will fall back to environment variables (for backwards compatibility).
+## Quick Start
 
-### Directory Structure
+### 1. Initialize the Agent
 
-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
+Get your registration token from the Fenwave platform, then run:
 
 ```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
+fenwave init --token <your-registration-token>
 ```
 
-### 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
+### 2. Start the Agent
 
 ```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)
+### 3. Access the Dashboard
 
-## Security
+Open your browser to `http://localhost:3003`
 
-### Authentication & Authorization
+## Commands
 
-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)
+| Command | Description |
+|---------|-------------|
+| `fenwave init` | Initialize and configure the agent |
+| `fenwave login` | Start the agent and authenticate |
+| `fenwave logout` | Stop the agent and clear session |
+| `fenwave status` | Check agent and registration status |
+| `fenwave --help` | Show all available commands |
 
-### Network Security
+## Dashboard Features
 
-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
+- Container management (start, stop, restart, logs)
+- Docker image management
+- Volume management
+- Registry connections
+- Real-time metrics
 
 ## 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:
+**Agent won't start?**
+- Ensure Docker Desktop is running
+- Check your network connection
+- Try `fenwave logout` then `fenwave login`
 
-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)
+**Need help?**
+- Run `fenwave --help` for command options
+- Contact your Fenwave administrator
 
 ## License
 
-Copyright © 2025 Fenwave. All rights reserved.
+Copyright 2025 Fenwave. All rights reserved. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenwave/agent",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Fenwave Docker Agent and CLI",
   "keywords": [
     "fenwave",