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:

# 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:

# 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:

# 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:

# 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:

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:

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:

ie-cli login --username devtester --password "Pass123!"

To verify who you are logged in as:

ie-cli whoami

5. Deploy to the Platform

Publish your validated tool to the platform's extension store:

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:

# 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:

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:

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:

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:

  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.