Projects/cli/README.md

# MioBook Sandbox Extension CLI (`ie-cli`)

Welcome to the **MioBook Sandbox Extension CLI** (`ie-cli`). This developer toolkit provides a command-line interface for researchers, software developers, and system builders to initialize, validate, deploy, and manage custom sandboxed tools and workspace extension panels in the MioBook platform.

To support different developer ecosystems and environments (e.g., CI/CD containers, local development VMs, or lightweight shell scripts), the CLI is structured in three languages:
1. **Go (Compiled Binary)** – The primary compiled standalone tool. Fast, dependency-free, and cross-compiled for all major platforms.
2. **Node.js** (`ie-cli.js`) – An alternative script implementation built on Node.js.
3. **Homebrew Formula** (`ie-cli.rb`) – A package configuration for macOS users.

---

## 🚀 Installation & System Setup

### Option 1: Standalone Go Binary Installer (Recommended)
We provide pre-compiled cross-platform Go binaries inside the `bin/` directory. You can use our automated shell installer to automatically detect your system architecture (Apple Silicon, Intel Mac, or Linux x86_64) and install the command globally:

```bash
# Set execute permissions on the installer script
chmod +x install.sh

# Run the installer (will request sudo permissions if /usr/local/bin requires it)
./install.sh
```

### Option 2: Local Compilation via Makefile
If you have Go installed on your system, you can compile and install directly from the source code:

```bash
# Build the binary locally in the current folder
make build

# Install the binary to /usr/local/bin
make install

# (Optional) Recompile all cross-platform targets (Darwin ARM64/AMD64, Linux, Windows)
make compile-all
```

### Option 3: Global npm Installation
If you prefer Node.js, you can install the Node package globally using npm:

```bash
# Install the local package globally
npm install -g .
```

---

## 🛠️ CLI Command Matrix Reference

Regardless of which runtime you choose, command syntax and arguments are standardized.

| Command | Arguments / Flags | Description |
|---|---|---|
| `help` | `[subcommand]` | Displays general help or detailed usage instructions for a specific subcommand. |
| `init` | None | Bootstraps a new custom tool project (creates `tool.json` and `tool.html`). |
| `login` | `--username -u`, `--password -p` | Authenticates with the platform and persists a JWT token locally. |
| `logout` | None | Clears the locally stored token and session credentials. |
| `whoami` | None | Displays current authentication state, user email, role, and active subscription plan. |
| `validate`| `--file -f` | Parses files and checks against iframe sandbox restrictions (forbidden storage, network, cookies, etc.). |
| `deploy`  | `--file -f` | Compiles and deploys a new custom tool to the extension store. |
| `update`  | `--id`, `--file -f` | Updates the configuration and HTML structure of a deployed tool. |
| `delete`  | `--id` | Permanently deletes a tool from the extension store. |
| `list`    | None | Lists all tools owned by the currently authenticated developer. |
| `status`  | `--id` | Queries live information (likes, installation state, active status) of a tool. |
| `logs`    | `--id`, `--limit` | Fetches deployment and sandbox execution logs for a tool. |

---

## 📖 Command Walkthroughs & Examples

### 1. Help Commands
Display detailed subcommand usage guidelines:
```bash
# General usage help
ie-cli help

# Detailed help for the 'deploy' command
ie-cli help deploy
```

### 2. Initialize a New Extension Project
Generate a standard starter template with metadata in your current working directory:
```bash
ie-cli init
```
This interactive prompt generates:
- `tool.json`: Contains metadata (name, description, version, category, public/private state, and subscription requirements).
- `tool.html`: A starter HTML template with styling, icons, and interactive elements.

### 3. Validate Sandbox Guidelines
Verify that your HTML code doesn't violate secure iframe policies:
```bash
ie-cli validate --file ./tool.html
```
*Validation checks for forbidden accesses such as: `localStorage`, `sessionStorage`, `document.cookie`, `XMLHttpRequest`, and `fetch()`.*

### 4. Authenticate with the Server
Log in to save a persistent session on your machine:
```bash
ie-cli login --username devtester --password "Pass123!"
```
To verify who you are logged in as:
```bash
ie-cli whoami
```

### 5. Deploy to the Platform
Publish your validated tool to the platform's extension store:
```bash
ie-cli deploy --file ./tool.html
```
On success, this prints your **Tool ID** (e.g., `42`) and its public marketplace URL.

### 6. Fetch Execution Logs
Inspect the deployment pipeline output or runtime logs:
```bash
# Fetch recent logs for all tools
ie-cli logs --limit 10

# Fetch logs for a specific tool ID
ie-cli logs --id 42 --limit 5
```

---

## 🔐 Configuration & Session Security

### Local JSON Config Store
When you authenticate using `ie-cli login`, a configuration file is securely saved to:
`~/.ie-research-cli.json`

This file contains your persistent session token, host mapping, and the ID of your last deployed extension. You can revoke this token and log out at any time:
```bash
ie-cli logout
```

### Environmental Overrides (CI/CD Pipelines)
For headless systems, GitHub Actions, or automated build agents where interactive login is unavailable, the CLI supports direct environment variable configurations:

- **`IE_TOKEN`** – Setting this variable overrides local configuration files and uses the token directly for all API calls.
- **`IE_HOST`** – Setting this variable overrides the default host address (e.g., in staging or integration testing environments).

Example:
```bash
export IE_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
export IE_HOST="http://my-staging-server:9092"
ie-cli list
```

---

## 🛠️ Automated CI/CD Integration (GitHub Actions)

You can easily integrate `ie-cli` into your GitHub repository to automate code validation and auto-deployment to the MioBook extension store.

Create a file named `.github/workflows/deploy.yml` in your tool repository:

```yaml
name: Validate & Deploy MioBook Extension

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Install Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.20'

      - name: Compile and Install ie-cli
        run: |
          cd cli
          go build -o ie-cli main.go config.go utils.go commands.go
          sudo mv ie-cli /usr/local/bin/

      - name: Validate Custom Extension
        run: |
          ie-cli validate --file ./tool.html

      - name: Deploy to MioBook Store
        env:
          IE_TOKEN: ${{ secrets.MIOBOOK_JWT_TOKEN }}
          IE_HOST: "http://api.miobook.com"
        run: |
          ie-cli deploy --file ./tool.html
```

---

## 🔍 Troubleshooting & Common Errors

### 1. `Error: Not logged in. Use 'ie-cli login' first.`
- **Cause**: The CLI could not find your credentials file at `~/.ie-research-cli.json`.
- **Solution**: Execute `ie-cli login` with your credentials, or set the `IE_TOKEN` environment variable.

### 2. `Error: Sandbox validation failed with X warnings`
- **Cause**: Your `tool.html` code contains blocked API symbols (like `localStorage` or `fetch()`).
- **Solution**: Replace raw storage or AJAX calls with standard message brokers. To send a notification:
  ```javascript
  window.parent.postMessage({
    type: "SEND_NOTIFICATION",
    payload: { title: "Title", body: "Message", priority: "medium" }
  }, "*");
  ```

### 3. `Error: Request failed with status 403 (Forbidden)`
- **Cause**: You are attempting to update (`update`) or delete (`delete`) an extension owned by another developer account.
- **Solution**: Check that you are logged in as the correct author, or deploy it as a new extension using `deploy`.