@the-agenticflow/openflows 0.1.3 → 0.1.6

package/.env.example

@@ -0,0 +1,60 @@
+# OpenFlows Configuration
+# Copy this file to .env and fill in your values
+# 
+# Quick Start Options:
+# ===================
+# 
+# Option 1: Fireworks AI (Recommended - no proxy needed)
+# ------------------------------------------------------
+# Get your key from: https://fireworks.ai
+FIREWORKS_API_KEY=your-fireworks-api-key
+
+# Option 2: Anthropic Direct
+# --------------------------
+# Get your key from: https://console.anthropic.com
+# ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# Option 3: Custom Gateway (requires built-in proxy)
+# --------------------------------------------------
+# The proxy will auto-start when you use this option
+# GATEWAY_URL=https://your-gateway.com/v1
+# GATEWAY_API_KEY=your-gateway-api-key
+
+# ===================
+# Required Settings
+# ===================
+
+# GitHub Personal Access Token (required)
+# Get from: https://github.com/settings/tokens
+# Needs: repo, read:user, read:org
+GITHUB_PERSONAL_ACCESS_TOKEN=your-github-pat
+
+# Target repository (owner/repo format)
+GITHUB_REPOSITORY=owner/repo-name
+
+# ===================
+# Optional Settings
+# ===================
+
+# Logging level (trace, debug, info, warn, error)
+RUST_LOG=info
+
+# Proxy port (if using built-in proxy)
+# PROXY_PORT=8765
+
+# GitHub MCP type: "hosted" (default) or "docker"
+# GITHUB_MCP_TYPE=hosted
+
+# ===================
+# Advanced
+# ===================
+
+# Custom model backend (overrides registry)
+# MODEL_BACKEND=accounts/fireworks/models/glm-5
+
+# Model provider mapping (for proxy mode)
+# Format: prefix=provider,prefix=provider
+# MODEL_PROVIDER_MAP=glm=openai,gpt=openai,claude=anthropic
+
+# Fallback order for direct mode
+# LLM_FALLBACK=anthropic,gemini,openai

package/README.md

@@ -1,174 +1,217 @@
-# @the-agenticflow/openflows npm Package
+# @the-agenticflow/openflows
 
-## Installation
+**Autonomous AI Development Team** — Install and run with zero configuration knowledge required.
+
+## Quick Start
 
 ```bash
-# Install globally
+# 1. Install globally
 npm install -g @the-agenticflow/openflows
 
-# Or use with npx (no install needed)
-npx @the-agenticflow/openflows setup
+# 2. Run setup wizard (configures API keys)
+openflows-setup
+
+# 3. Start the autonomous team
+openflows
 ```
 
-## What Gets Installed
+That's it! The package handles everything automatically.
+
+## How It Works
 
-The post-install script (`scripts/install.js`) downloads platform-specific binaries from GitHub Releases:
+### Zero-Configuration Philosophy
 
-1. **Detects Platform**
-   - macOS: `x86_64-apple-darwin` or `aarch64-apple-darwin`
-   - Linux: `x86_64-unknown-linux-gnu/musl` or `aarch64-unknown-linux-gnu`
+You don't need to know about proxies, MCP servers, or backend routing. The package:
 
-2. **Downloads Binary**
-   - Fetches latest release from GitHub API
-   - Falls back to `v0.1.3` if API unavailable
-   - Downloads tarball containing:
-     - `agentflow` - Main orchestration binary
-     - `agentflow-setup` - Interactive TUI setup wizard
-     - `agentflow-dashboard` - Real-time monitoring TUI
-     - `agentflow-doctor` - System diagnostics tool
-     - `orchestration/` - Agent configurations
-     - `LICENSE` - MIT License
+1. **Installs all dependencies** - Including `mcp-proxy` for GitHub connectivity
+2. **Auto-detects your setup** - Fireworks key? Direct mode. Gateway? Proxy starts automatically
+3. **Manages the proxy lifecycle** - Starts/stops the built-in proxy as needed
+4. **Provides helpful errors** - Clear messages when something needs attention
 
-3. **Extracts to Package**
-   - Extracts to `bin/` directory
-   - Renames binaries to `*-bin` for Node.js wrappers
-   - Sets executable permissions
+### Configuration Modes
 
-## Commands Available
+| Mode | What You Need | Proxy Required? |
+|------|---------------|-----------------|
+| **Fireworks Direct** | `FIREWORKS_API_KEY` | No |
+| **Anthropic Direct** | `ANTHROPIC_API_KEY` | No |
+| **Custom Gateway** | `GATEWAY_URL` + `GATEWAY_API_KEY` | Auto-started |
+
+### Commands
 
 ```bash
 openflows              # Start orchestration
-openflows-setup        # Run setup wizard
-openflows-dashboard    # Launch monitoring TUI
-openflows-doctor       # Run diagnostics
+openflows-setup        # Interactive setup wizard (TUI)
+openflows-dashboard    # Real-time monitoring (TUI)
+openflows-doctor       # System diagnostics
+openflows --help       # Show help
+openflows --version    # Show version
 ```
 
-## Troubleshooting
+## What Gets Installed
 
-### Permission Denied (sudo install)
+The post-install script downloads platform-specific binaries from GitHub Releases:
 
-**Problem**: `EACCES: permission denied, open '/tmp/openflows-...'`
+| Binary | Purpose |
+|--------|---------|
+| `agentflow` | Main orchestration engine |
+| `agentflow-setup` | Interactive TUI setup wizard |
+| `agentflow-dashboard` | Real-time monitoring TUI |
+| `agentflow-doctor` | System diagnostics tool |
+| `anthropic-proxy` | Built-in Anthropic-to-OpenAI proxy |
 
-**Solution**: Fixed in v0.1.3 - install script now uses package-local `.tmp` directory instead of `/tmp`.
+Additionally:
+- **mcp-proxy** is installed via npm for GitHub MCP connectivity
+- **.env.example** is included for reference
+
+## Environment Configuration
+
+Create a `.env` file in your project directory:
 
-**Workaround for older versions**:
 ```bash
-# Install without sudo
-mkdir -p ~/.npm-global
-npm config set prefix '~/.npm-global'
-echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
-source ~/.bashrc
-npm install -g @the-agenticflow/openflows
+# Required
+GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxx
+GITHUB_REPOSITORY=owner/repo-name
+
+# Choose one API provider
+FIREWORKS_API_KEY=fw_xxxxx        # Recommended - direct mode
+# ANTHROPIC_API_KEY=sk-ant-xxxx   # Direct mode
+# GATEWAY_URL=...                 # Proxy auto-starts
+# GATEWAY_API_KEY=...             # For custom gateways
 ```
 
-### Network Issues (DNS/API failures)
+Run `openflows-setup` for a guided configuration experience.
 
-**Problem**: `getaddrinfo EAI_AGAIN api.github.com` or `undefined` in filename
+## Advanced Options
 
-**Solution**: Fixed in v0.1.3 - script now:
-- Has timeout handling for GitHub API
-- Falls back to known version `v0.1.3` if API fails
-- Validates API response before using
+### Disable Auto-Proxy
 
-**Manual fix**:
 ```bash
-# Build from source instead
-git clone https://github.com/The-AgenticFlow/OpenFlows.git
-cd OpenFlows
-cargo build --release --bin agentflow-setup
-sudo cp target/release/agentflow-setup /usr/local/bin/
+openflows --no-proxy
 ```
 
-### Binary Not Found
+### Proxy-Only Mode (Testing)
 
-**Problem**: Command not found after install
+```bash
+openflows --proxy-only
+# Starts only the built-in proxy on port 8765
+```
+
+### Custom Proxy Port
 
-**Solution**: Ensure `npm bin -g` is in your PATH
 ```bash
-# Check where global bins are installed
-npm bin -g
+PROXY_PORT=9000 openflows
+```
 
-# Add to PATH if needed
-echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
-source ~/.bashrc
+### Docker MCP (Alternative)
+
+If you prefer Docker for GitHub MCP:
+
+```bash
+export GITHUB_MCP_TYPE=docker
+openflows
 ```
 
-## Publishing New Versions
+## Troubleshooting
 
-When a new GitHub release is created:
+### `mcp-proxy` Installation Issues
 
-1. **Update package.json version**:
-   ```bash
-   cd packaging/npm
-   # Edit package.json: "version": "0.1.4"
-   ```
+The post-install script attempts to install `mcp-proxy` (Python tool from PyPI) automatically. If you see errors:
 
-2. **Update fallback version in install.js**:
-   ```javascript
-   // Line 126
-   tag = 'v0.1.4'; // Update fallback
+1. **Install manually:**
+   ```bash
+   # Recommended (fastest)
+   uv tool install mcp-proxy
+   
+   # Alternative
+   pipx install mcp-proxy
    ```
 
-3. **Test locally**:
+2. **Use Docker mode instead:**
    ```bash
-   npm pack
-   npm install -g the-agenticflow-openflows-0.1.4.tgz
-   openflows-setup --help
+   export GITHUB_MCP_TYPE=docker
+   openflows
    ```
 
-4. **Publish to npm**:
+The `mcp-proxy` tool bridges stdio to HTTP MCP servers like GitHub Copilot's MCP endpoint.
+
+### Permission Denied
+
+Ensure you're not using `sudo` for npm install:
+
+```bash
+# Configure npm to use user-writable directory
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Now install without sudo
+npm install -g @the-agenticflow/openflows
+```
+
+### Network Issues
+
+If GitHub API is unreachable:
+
+1. The installer falls back to a known version
+2. Or build from source:
    ```bash
-   npm publish --access public
+   git clone https://github.com/The-AgenticFlow/AgentFlow.git
+   cd AgentFlow
+   cargo build --release
    ```
 
-## Files Included in npm Package
+### GitHub 401 Unauthorized
 
-```
-@the-agenticflow/openflows/
-├── package.json        # Package metadata
-├── README.md           # This file
-├── bin/
-│   ├── openflows.js           # Node.js wrapper
-│   ├── openflows-setup.js     # Node.js wrapper
-│   ├── openflows-dashboard.js # Node.js wrapper
-│   └── openflows-doctor.js    # Node.js wrapper
-└── scripts/
-    └── install.js      # Post-install binary downloader
-```
+Ensure your `GITHUB_PERSONAL_ACCESS_TOKEN` is valid with these scopes:
+- `repo` (full repository access)
+- `read:user`
+- `read:org`
 
-## Technical Details
+## Platform Support
 
-### Platform Detection Logic
+| OS | Architecture | Status |
+|----|--------------|--------|
+| macOS | x86_64 (Intel) | ✅ |
+| macOS | aarch64 (M1/M2) | ✅ |
+| Linux | x86_64 (glibc) | ✅ |
+| Linux | x86_64 (musl) | ✅ |
+| Linux | aarch64 | ✅ |
 
-```javascript
-// OS detection
-darwin  → apple-darwin
-linux   → unknown-linux-gnu OR unknown-linux-musl
+## Development
 
-// Architecture detection
-x64   → x86_64
-arm64 → aarch64
+### Testing Locally
 
-// Musl detection (Linux only)
-ldd --version | grep -q musl → use musl variant
+```bash
+cd packaging/npm
+npm pack
+npm install -g the-agenticflow-openflows-0.1.4.tgz
+openflows-setup --help
 ```
 
-### Fallback Chain
+### Publishing
 
-1. Try GitHub API for latest release
-2. If API fails → use hardcoded `v0.1.3`
-3. Download `gnu` variant
-4. If `gnu` fails on x86_64 Linux → try `musl` variant
-5. Extract and install
+1. Update version in `package.json`
+2. Update fallback version in `scripts/install.js`
+3. Test locally with `npm pack`
+4. Publish: `npm publish --access public`
 
-### Binary Wrappers
+## Files Included
 
-Each command (`openflows`, `openflows-setup`, etc.) is a Node.js wrapper that:
-- Calls the downloaded binary (`*-bin`)
-- Passes through all arguments
-- Inherits stdio for interactive TUI
-- Exits with binary's exit code
+```
+@the-agenticflow/openflows/
+├── package.json        # Package metadata
+├── README.md           # This file
+├── .env.example        # Configuration template
+├── bin/
+│   ├── openflows.js           # Main wrapper (handles proxy)
+│   ├── openflows-setup.js     # Setup wizard wrapper
+│   ├── openflows-dashboard.js # Dashboard wrapper
+│   └── openflows-doctor.js    # Doctor wrapper
+└── scripts/
+    └── install.js      # Post-install script
+```
 
 ## License
 
-MIT - see LICENSE file in downloaded tarball or GitHub repository.
+MIT - See [LICENSE](https://github.com/The-AgenticFlow/AgentFlow/blob/main/LICENSE)

package/bin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Yemele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.