envio-cloud 0.3.0

package/README.md

@@ -0,0 +1,261 @@
+# envio-cloud
+
+CLI for [Envio's Hosted Service](https://envio.dev) — deploy, manage, and monitor blockchain indexers powered by [HyperIndex](https://docs.envio.dev/docs/HyperIndex/overview).
+
+## Install
+
+```bash
+npm install -g envio-cloud
+```
+
+Or run directly with npx:
+
+```bash
+npx envio-cloud deployment metrics hyperindex b3ead3a mjyoung114
+```
+
+## Quick Start
+
+```bash
+# Authenticate with GitHub (opens browser)
+envio-cloud login
+
+# List public indexers
+envio-cloud indexer list
+
+# View deployment metrics (no auth required)
+envio-cloud deployment metrics hyperindex b3ead3a mjyoung114
+```
+
+## Authentication
+
+### Browser Login (default)
+
+```bash
+envio-cloud login
+```
+
+Opens your browser to sign in via [envio.dev](https://envio.dev). No local server or OAuth credentials required. Session lasts 30 days.
+
+### Token Login (CI/CD)
+
+```bash
+# Via flag
+envio-cloud login --token ghp_YOUR_TOKEN
+
+# Via environment variable
+export ENVIO_GITHUB_TOKEN=ghp_YOUR_TOKEN
+envio-cloud login
+```
+
+Required token scopes: `read:org`, `read:user`, `user:email`.
+
+### Session Management
+
+```bash
+envio-cloud token    # Check current session status
+envio-cloud logout   # Remove stored credentials
+```
+
+## Commands
+
+### Indexer Commands
+
+#### `envio-cloud indexer list`
+
+List all public indexers on the platform.
+
+```bash
+envio-cloud indexer list
+envio-cloud indexer list --org myorg
+envio-cloud indexer list --limit 10
+envio-cloud indexer list -o json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--org` | Filter by organisation ID |
+| `--limit` | Max number of results (default: 1000) |
+| `-o, --output` | Output format: `json` |
+
+#### `envio-cloud indexer get <name> <organisation>`
+
+View details and deployments for a specific indexer.
+
+```bash
+envio-cloud indexer get hyperindex mjyoung114
+envio-cloud indexer get hyperindex mjyoung114 -o json
+```
+
+#### `envio-cloud indexer add` (requires auth)
+
+Add a new indexer to the platform.
+
+```bash
+envio-cloud indexer add --name my-indexer --repo my-repo
+envio-cloud indexer add --name my-indexer --repo my-repo --branch main --tier development
+envio-cloud indexer add --name my-indexer --repo my-repo --dry-run
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-n, --name` | Indexer name (required) | |
+| `-r, --repo` | GitHub repository (required) | |
+| `-b, --branch` | Git branch | `envio` |
+| `-d, --root-dir` | Root directory | `./` |
+| `-c, --config-file` | Config file path | `config.yaml` |
+| `-t, --tier` | Service tier | `development` |
+| `-a, --access-type` | Access type | `public` |
+| `-e, --env-file` | Path to .env file | |
+| `--auto-deploy` | Auto-deploy on push | `true` |
+| `--dry-run` | Preview without creating | |
+| `-y, --yes` | Skip confirmation | |
+
+### Deployment Commands
+
+#### `envio-cloud deployment metrics <indexer> <commit> <organisation>`
+
+Real-time indexing metrics per chain. **No auth required.**
+
+```bash
+envio-cloud deployment metrics hyperindex b3ead3a mjyoung114
+envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 -o json
+envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 --watch
+```
+
+Example output:
+
+```
+Deployment Metrics: mjyoung114/hyperindex (commit: b3ead3a)
+
+CHAIN   PROGRESS   BLOCK HEIGHT   PROCESSED    EVENTS    HYPERSYNC   SYNCED AT
+143     100.00%    62456629       62456630     577336    yes         2026-03-18 16:52
+999     100.00%    30166822       30166822     1161921   yes         2026-03-18 16:52
+
+Total chains: 2 | Total events: 1739257 | Status: fully synced
+```
+
+| Flag | Description |
+|------|-------------|
+| `--watch` | Auto-refresh every 10 seconds |
+| `-o, --output` | Output format: `json` |
+
+#### `envio-cloud deployment status <indexer> <commit> <organisation>`
+
+Sync progress and completion percentage. **No auth required.**
+
+```bash
+envio-cloud deployment status hyperindex b3ead3a mjyoung114
+envio-cloud deployment status hyperindex b3ead3a mjyoung114 --watch-till-synced
+envio-cloud deployment status hyperindex b3ead3a mjyoung114 -o json
+```
+
+#### `envio-cloud deployment info <indexer> <commit> <organisation>`
+
+Aggregator configuration (cache, DB exposure). **No auth required.**
+
+```bash
+envio-cloud deployment info hyperindex b3ead3a mjyoung114
+envio-cloud deployment info hyperindex b3ead3a mjyoung114 -o json
+```
+
+#### `envio-cloud deployment promote <indexer> <commit> <organisation>` (requires auth)
+
+Promote a deployment to production.
+
+```bash
+envio-cloud deployment promote myindexer abc1234 myorg
+```
+
+### Repository Commands
+
+#### `envio-cloud repos` (requires auth)
+
+List GitHub repositories linked to your organisation.
+
+```bash
+envio-cloud repos
+envio-cloud repos -o json
+```
+
+## JSON Output
+
+All commands support `-o json` for machine-readable output with a consistent envelope:
+
+```json
+{
+  "ok": true,
+  "data": [ ... ]
+}
+```
+
+On error:
+
+```json
+{
+  "ok": false,
+  "error": "error message"
+}
+```
+
+### Piping Examples
+
+```bash
+# Get event count with jq
+envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 -o json \
+  | jq '.data[].num_events_processed'
+
+# List indexer names for an org
+envio-cloud indexer list --org enviodev -o json \
+  | jq -r '.data[].indexer_id'
+
+# Check if fully synced
+envio-cloud deployment metrics hyperindex b3ead3a mjyoung114 -o json \
+  | jq '.data | all(.latest_processed_block >= .block_height)'
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `-q, --quiet` | Suppress informational messages, output data only |
+| `-o, --output` | Output format: `json` (on supported commands) |
+| `--config` | Config file path (default: `~/.envio-cloud.yaml`) |
+| `-h, --help` | Help for any command |
+| `-v, --version` | Print version |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (including empty results) |
+| 1 | User error (bad arguments, not logged in) |
+| 2 | API or server error |
+
+## Alternative Installation
+
+### Go
+
+```bash
+go install github.com/enviodev/hosted-service-cli@latest
+```
+
+### From Source
+
+```bash
+git clone https://github.com/enviodev/hosted-service-cli.git
+cd hosted-service-cli
+go build -o envio-cloud .
+```
+
+### GitHub Releases
+
+Download prebuilt binaries from [GitHub Releases](https://github.com/enviodev/hosted-service-cli/releases).
+
+## Links
+
+- [Envio Documentation](https://docs.envio.dev)
+- [HyperIndex Overview](https://docs.envio.dev/docs/HyperIndex/overview)
+- [Hosted Service Guide](https://docs.envio.dev/docs/HyperIndex/hosted-service)
+- [GitHub Repository](https://github.com/enviodev/hosted-service-cli)
+- [Report Issues](https://github.com/enviodev/hosted-service-cli/issues)

package/bin/envio-cloud

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Map Node.js platform/arch to our package names
+const PLATFORMS = {
+  "darwin-arm64": "@envio-dev/envio-cloud-darwin-arm64",
+  "darwin-x64": "@envio-dev/envio-cloud-darwin-x64",
+  "linux-x64": "@envio-dev/envio-cloud-linux-x64",
+  "linux-arm64": "@envio-dev/envio-cloud-linux-arm64",
+  "win32-x64": "@envio-dev/envio-cloud-win32-x64",
+};
+
+function getBinaryPath() {
+  const platformKey = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORMS[platformKey];
+
+  if (!pkg) {
+    throw new Error(
+      `Unsupported platform: ${platformKey}\n` +
+        `envio-cloud supports: ${Object.keys(PLATFORMS).join(", ")}`
+    );
+  }
+
+  // Try to find the binary in the platform package
+  try {
+    const pkgPath = require.resolve(`${pkg}/package.json`);
+    const binDir = path.join(path.dirname(pkgPath), "bin");
+    const binName = process.platform === "win32" ? "envio-cloud.exe" : "envio-cloud";
+    const binPath = path.join(binDir, binName);
+
+    if (fs.existsSync(binPath)) {
+      return binPath;
+    }
+  } catch (e) {
+    // Package not found via require.resolve
+  }
+
+  // Fallback: check if binary was installed via postinstall download
+  const localBin = path.join(
+    __dirname,
+    process.platform === "win32" ? "envio-cloud.exe" : "envio-cloud-binary"
+  );
+  if (fs.existsSync(localBin)) {
+    return localBin;
+  }
+
+  throw new Error(
+    `Could not find envio-cloud binary for ${platformKey}.\n` +
+      `Try reinstalling: npm install envio-cloud`
+  );
+}
+
+try {
+  const binPath = getBinaryPath();
+  const result = execFileSync(binPath, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (e) {
+  if (e.status !== undefined) {
+    // execFileSync throws with status code on non-zero exit
+    process.exit(e.status);
+  }
+  console.error(e.message);
+  process.exit(1);
+}

package/install.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const { existsSync } = require("fs");
+const path = require("path");
+
+// Map Node.js platform/arch to package names
+const PLATFORMS = {
+  "darwin-arm64": "@envio-dev/envio-cloud-darwin-arm64",
+  "darwin-x64": "@envio-dev/envio-cloud-darwin-x64",
+  "linux-x64": "@envio-dev/envio-cloud-linux-x64",
+  "linux-arm64": "@envio-dev/envio-cloud-linux-arm64",
+  "win32-x64": "@envio-dev/envio-cloud-win32-x64",
+};
+
+function verifyInstallation() {
+  const platformKey = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORMS[platformKey];
+
+  if (!pkg) {
+    console.warn(
+      `Warning: envio-cloud does not have a prebuilt binary for ${platformKey}.`
+    );
+    console.warn(
+      "You can build from source: go install github.com/enviodev/hosted-service-cli@latest"
+    );
+    return;
+  }
+
+  // Check if the platform package was installed (via optionalDependencies)
+  try {
+    const pkgPath = require.resolve(`${pkg}/package.json`);
+    const binDir = path.join(path.dirname(pkgPath), "bin");
+    const binName = process.platform === "win32" ? "envio-cloud.exe" : "envio-cloud";
+    const binPath = path.join(binDir, binName);
+
+    if (existsSync(binPath)) {
+      return; // Binary found, we're good
+    }
+  } catch (e) {
+    // Package not installed
+  }
+
+  // Check for fallback binary
+  const localBin = path.join(
+    __dirname,
+    "bin",
+    process.platform === "win32" ? "envio-cloud.exe" : "envio-cloud-binary"
+  );
+  if (existsSync(localBin)) {
+    return;
+  }
+
+  console.warn(
+    `Warning: envio-cloud binary for ${platformKey} was not installed.`
+  );
+  console.warn("This can happen if npm was run with --no-optional.");
+  console.warn("Alternatives:");
+  console.warn("  1. Reinstall without --no-optional: npm install envio-cloud");
+  console.warn(
+    "  2. Install via Go: go install github.com/enviodev/hosted-service-cli@latest"
+  );
+  console.warn(
+    "  3. Download from: https://github.com/enviodev/hosted-service-cli/releases"
+  );
+}
+
+verifyInstallation();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "envio-cloud",
+  "version": "0.3.0",
+  "description": "CLI for Envio's Hosted Service — manage and monitor blockchain indexers powered by HyperIndex",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/enviodev/hosted-service-cli.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "envio-cloud": "bin/envio-cloud"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "optionalDependencies": {
+    "@envio-dev/envio-cloud-darwin-arm64": "0.3.0",
+    "@envio-dev/envio-cloud-darwin-x64": "0.3.0",
+    "@envio-dev/envio-cloud-linux-x64": "0.3.0",
+    "@envio-dev/envio-cloud-linux-arm64": "0.3.0",
+    "@envio-dev/envio-cloud-win32-x64": "0.3.0"
+  },
+  "keywords": [
+    "envio",
+    "hyperindex",
+    "blockchain",
+    "indexer",
+    "hosted-service",
+    "cli",
+    "web3"
+  ],
+  "homepage": "https://docs.envio.dev/docs/HyperIndex/hosted-service",
+  "bugs": {
+    "url": "https://github.com/enviodev/hosted-service-cli/issues"
+  }
+}