@zeko-labs/faucet-cli 0.0.0

package/README.md

@@ -0,0 +1,168 @@
+# Faucet CLI
+
+> **Public mirror** — This repository is automatically synced from a private monorepo. Development happens in the monorepo; this repo is a read-only source mirror. See [zeko-labs/faucet-cli](https://github.com/zeko-labs/faucet-cli) for issues and releases.
+
+Command-line client for the Zeko testnet faucet. Claim testnet tokens and verify your GitHub authentication from the terminal.
+
+Written in Rust for fast startup and single-binary distribution. Distributed via npm with platform-specific packages.
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g @zeko-labs/faucet-cli
+```
+
+Or run without installing via `npx`:
+
+```bash
+npx @zeko-labs/faucet-cli whoami
+```
+
+### Supported platforms
+
+| Platform      | Package                              |
+| ------------- | ------------------------------------ |
+| macOS arm64   | `@zeko-labs/faucet-cli-darwin-arm64` |
+| macOS x64     | `@zeko-labs/faucet-cli-darwin-x64`   |
+| Linux x64     | `@zeko-labs/faucet-cli-linux-x64`    |
+| Linux arm64   | `@zeko-labs/faucet-cli-linux-arm64`  |
+| Windows x64   | `@zeko-labs/faucet-cli-win32-x64`    |
+| Windows arm64 | `@zeko-labs/faucet-cli-win32-arm64`  |
+
+The correct platform package is installed automatically via `optionalDependencies`.
+
+## Authentication
+
+Every command requires a **GitHub personal access token** (classic or fine-grained).
+The CLI resolves the token in this order:
+
+1. `--token <value>` flag (highest priority)
+2. `GITHUB_TOKEN` environment variable
+
+```bash
+# Using the flag
+zeko-faucet whoami --token ghp_xxx
+
+# Using the environment variable
+export GITHUB_TOKEN=ghp_xxx
+zeko-faucet whoami
+```
+
+## Commands
+
+### `whoami`
+
+Verify your GitHub token and display the associated account.
+
+```bash
+zeko-faucet whoami
+zeko-faucet whoami --token ghp_xxx
+zeko-faucet whoami --json
+```
+
+**Example output:**
+
+```
+Authenticated as octocat (#1).
+Name: The Octocat
+Profile: https://github.com/octocat
+Created: 2011-01-25T18:44:36Z
+Token source: env
+```
+
+### `claim <address>`
+
+Submit a faucet claim for the given Mina address on the `zeko-testnet` chain.
+
+```bash
+zeko-faucet claim B62qexample
+zeko-faucet claim B62qexample --token ghp_xxx
+zeko-faucet claim B62qexample --json
+```
+
+**Example output:**
+
+```
+Claim submitted for B62qexample.
+Chain: zeko-testnet
+Amount: 100
+Transaction: 5Jtxxx
+Explorer: https://zekoscan.io/devnet/tx/5Jtxxx
+```
+
+## Global Flags
+
+| Flag      | Description                                             |
+| --------- | ------------------------------------------------------- |
+| `--token` | GitHub personal access token (overrides `GITHUB_TOKEN`) |
+| `--json`  | Emit machine-readable JSON instead of human text        |
+
+## Exit Codes
+
+| Code | Meaning              |
+| ---- | -------------------- |
+| `0`  | Success              |
+| `1`  | General error        |
+| `2`  | Authentication error |
+| `3`  | Rate limited         |
+| `4`  | Invalid address      |
+
+Scripts and CI pipelines can use exit codes to branch on specific failure types:
+
+```bash
+zeko-faucet claim B62qexample
+case $? in
+  0) echo "Claim succeeded" ;;
+  2) echo "Bad token — check GITHUB_TOKEN" ;;
+  3) echo "Rate limited — try again later" ;;
+  4) echo "Invalid Mina address" ;;
+  *) echo "Something went wrong" ;;
+esac
+```
+
+## JSON Mode
+
+Pass `--json` to any command for machine-readable output suitable for piping into `jq` or other tools.
+
+**Success:**
+
+```json
+{
+	"success": true,
+	"address": "B62qexample",
+	"chain": "zeko-testnet",
+	"amount": "100",
+	"hash": "5Jtxxx",
+	"explorer_url": "https://zekoscan.io/devnet/tx/5Jtxxx"
+}
+```
+
+**Error:**
+
+```json
+{
+	"success": false,
+	"code": "rate_limited",
+	"message": "You have already claimed tokens recently."
+}
+```
+
+## Development
+
+Requires [Rust](https://rustup.rs/) and [pnpm](https://pnpm.io/).
+
+```bash
+# Build
+moon faucet-cli:build
+
+# Run integration tests
+moon faucet-cli:test
+
+# Lint
+moon faucet-cli:lint
+
+# Check (fast compile check)
+moon faucet-cli:check
+```

package/bin/zeko-faucet.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process"
+import { createRequire } from "node:module"
+
+const require = createRequire(import.meta.url)
+const platformKey = `${process.platform}-${process.arch}`
+const ext = process.platform === "win32" ? ".exe" : ""
+
+let binPath
+try {
+	binPath = require.resolve(`@zeko-labs/faucet-cli-${platformKey}/bin/zeko-faucet${ext}`)
+} catch {
+	console.error(
+		`@zeko-labs/faucet-cli does not support ${process.platform}-${process.arch}. ` +
+			"Please open an issue at https://github.com/nicekind/zeko-ui/issues"
+	)
+	process.exit(1)
+}
+
+try {
+	execFileSync(binPath, process.argv.slice(2), { stdio: "inherit" })
+} catch (e) {
+	process.exit(e.status ?? 1)
+}

package/npm/darwin-arm64/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @zeko-labs/faucet-cli-darwin-arm64
+
+## 0.1.1

package/npm/darwin-arm64/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@zeko-labs/faucet-cli-darwin-arm64",
+	"version": "0.0.0",
+	"description": "Darwin arm64 binary for @zeko-labs/faucet-cli",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"darwin"
+	],
+	"cpu": [
+		"arm64"
+	],
+	"files": [
+		"bin"
+	]
+}

package/npm/darwin-x64/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @zeko-labs/faucet-cli-darwin-x64
+
+## 0.1.1

package/npm/darwin-x64/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@zeko-labs/faucet-cli-darwin-x64",
+	"version": "0.0.0",
+	"description": "Darwin x64 binary for @zeko-labs/faucet-cli",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"darwin"
+	],
+	"cpu": [
+		"x64"
+	],
+	"files": [
+		"bin"
+	]
+}

package/npm/linux-arm64/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @zeko-labs/faucet-cli-linux-arm64
+
+## 0.1.1

package/npm/linux-arm64/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@zeko-labs/faucet-cli-linux-arm64",
+	"version": "0.0.0",
+	"description": "Linux arm64 binary for @zeko-labs/faucet-cli",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"linux"
+	],
+	"cpu": [
+		"arm64"
+	],
+	"files": [
+		"bin"
+	]
+}

package/npm/linux-x64/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @zeko-labs/faucet-cli-linux-x64
+
+## 0.1.1

package/npm/linux-x64/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@zeko-labs/faucet-cli-linux-x64",
+	"version": "0.0.0",
+	"description": "Linux x64 binary for @zeko-labs/faucet-cli",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"linux"
+	],
+	"cpu": [
+		"x64"
+	],
+	"files": [
+		"bin"
+	]
+}

package/npm/win32-arm64/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @zeko-labs/faucet-cli-win32-arm64
+
+## 0.1.1

package/npm/win32-arm64/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@zeko-labs/faucet-cli-win32-arm64",
+	"version": "0.0.0",
+	"description": "Windows arm64 binary for @zeko-labs/faucet-cli",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"win32"
+	],
+	"cpu": [
+		"arm64"
+	],
+	"files": [
+		"bin"
+	]
+}

package/npm/win32-x64/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @zeko-labs/faucet-cli-win32-x64
+
+## 0.1.1

package/npm/win32-x64/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@zeko-labs/faucet-cli-win32-x64",
+	"version": "0.0.0",
+	"description": "Windows x64 binary for @zeko-labs/faucet-cli",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"os": [
+		"win32"
+	],
+	"cpu": [
+		"x64"
+	],
+	"files": [
+		"bin"
+	]
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zeko-labs/faucet-cli",
+  "version": "0.0.0",
+  "description": "Public CLI for claiming Zeko testnet faucet funds and verifying GitHub authentication.",
+  "type": "module",
+  "keywords": [
+    "zeko",
+    "faucet",
+    "cli",
+    "rust"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "npm"
+  ],
+  "bin": {
+    "zeko-faucet": "./bin/zeko-faucet.js"
+  },
+  "optionalDependencies": {
+    "@zeko-labs/faucet-cli-linux-x64": "0.0.0",
+    "@zeko-labs/faucet-cli-linux-arm64": "0.0.0",
+    "@zeko-labs/faucet-cli-darwin-arm64": "0.0.0",
+    "@zeko-labs/faucet-cli-win32-x64": "0.0.0",
+    "@zeko-labs/faucet-cli-darwin-x64": "0.0.0",
+    "@zeko-labs/faucet-cli-win32-arm64": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.10",
+    "vitest": "3.2.4"
+  }
+}