@r5n/hydra 0.5.8 → 0.6.0

package/LICENSE

@@ -1,201 +1 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright R5N Labs
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+See [../LICENSE](../LICENSE)

package/README.md

@@ -1,364 +1,182 @@
-<div align="center">
-  <a href="https://github.com/r5n-labs">
-    <img src="https://avatars.githubusercontent.com/u/99986752?s=400&v=4" alt="R5N Labs" width="100" height="100">
-  </a>
-
-  <p><strong>The GitHub Runner Manager That Actually Scales 🚀</strong></p>
-  <p><em>🏊 Made for developers who'd rather be coding than configuring</em></p>
-  
-  <h1>Hydra</h1>
-
-  <p>
-    <a href="https://www.npmjs.com/package/@r5n/hydra">
-      <img src="https://img.shields.io/npm/v/@r5n/hydra.svg" alt="npm version">
-    </a>
-    <a href="https://github.com/r5n-labs/clis/blob/main/packages/hydra/LICENSE">
-      <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License">
-    </a>
-    <img src="https://img.shields.io/badge/bundle%20size-~73KB-green.svg" alt="Bundle Size">
-  </p>
-</div>
-
----
+# Hydra
 
-## Overview
-
-Tired of manually setting up GitHub Actions runners? Hydra transforms hours of tedious work into a single command. Create, manage, and monitor dozens of self-hosted runners with the simplicity you've been craving.
+<div align="center">
 
-### ✨ Why Hydra?
+[![npm version](https://img.shields.io/npm/v/@r5n/hydra.svg)](https://www.npmjs.com/package/@r5n/hydra)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)
+![Bundle Size](https://img.shields.io/badge/bundle_size-~110KB-green.svg)
 
-- 🚀 **Lightning Fast** - Create 20 runners in the time it takes to manually create 1
-- 🔧 **Smart Profiles** - Define once, deploy anywhere with reusable configs
-- 📊 **Live Insights** - See exactly what your runners are doing in real-time
-- 🏃 **73KB of Pure Speed** - Installs before your coffee finishes brewing
-- 🎯 **Works Everywhere** - macOS, Linux, Windows - we've got you covered
+Manage GitHub Actions self-hosted runners.
 
-## 🎯 What Can You Do?
+</div>
 
-<details>
-<summary><strong>Create a fleet of runners in seconds</strong></summary>
+## Quick Start
 
 ```bash
-$ hydra create -t $TOKEN -u https://github.com/myorg/repo -m 10 -l "gpu,docker"
-⠋ Downloading runner package... (2.1s)
-✔ Created runner gpu-runner-1
-✔ Created runner gpu-runner-2
-✔ Created runner gpu-runner-3
-✔ Created runner gpu-runner-4
-✔ Created runner gpu-runner-5
-✔ Created runner gpu-runner-6
-✔ Created runner gpu-runner-7
-✔ Created runner gpu-runner-8
-✔ Created runner gpu-runner-9
-✔ Created runner gpu-runner-10
-✅ All 10 runners created successfully in 8.3s
-```
-</details>
-
-<details>
-<summary><strong>Monitor your runner army</strong></summary>
+# Install
+bun add -g @r5n/hydra
 
-```bash
-$ hydra status -p production
-┌─────────────────┬─────────┬───────────┬──────────────┐
-│ Name            │ Status  │ Busy      │ Labels       │
-├─────────────────┼─────────┼───────────┼──────────────┤
-│ prod-runner-1   │ ✅ Idle │ No        │ linux,docker │
-│ prod-runner-2   │ ✅ Idle │ No        │ linux,docker │
-│ prod-runner-3   │ 🔄 Busy │ Yes (2m)  │ linux,docker │
-│ prod-runner-4   │ ✅ Idle │ No        │ linux,docker │
-│ prod-runner-5   │ ❌ Offline │ -      │ linux,docker │
-└─────────────────┴─────────┴───────────┴──────────────┘
-Summary: 3 idle, 1 busy, 1 offline
-```
-</details>
+# Initialize config
+hydra init
 
-<details>
-<summary><strong>Monitor runner status</strong></summary>
+# Create runners
+hydra create -t $TOKEN -u https://github.com/org/repo -m 3
 
-```bash
-$ hydra status -p production
-🔍 Checking runner status...
-✅ Runner 1: Online (idle)
-✅ Runner 2: Online (busy - job #1234)
-✅ Runner 3: Online (idle)
-   ✓ Created runner-4
-   ✓ Created runner-5
-
-🔍 Monitoring continues... (press Ctrl+C to stop)
+# Check status
+hydra status -t $TOKEN -u https://github.com/org/repo
 ```
-</details>
-
-## 📦 Installation
-
-```bash
-# Using Bun (recommended)
-bun add -g @r5n/hydra
-hydra --help
 
-# Direct usage (no installation)
-bunx @r5n/hydra --help
-```
+## Why?
 
-## 🚀 Quick Start
+Setting up self-hosted runners manually is tedious. Hydra automates it:
 
-### 1. Initialize Configuration
+- Create multiple runners in parallel
+- Reusable profile configs
+- Monitor runner status
+- Cross-platform (macOS, Linux, Windows)
 
-```bash
-# Interactive setup
-hydra init
+## Commands
 
-# Use TOML format
-hydra init --toml
-```
+### `hydra init`
 
-### 2. Create Runners
+Create a config file with profiles.
 
 ```bash
-# Basic usage
-hydra create -t YOUR_TOKEN -u https://github.com/org/repo
-
-# Create multiple runners with labels
-hydra create -t YOUR_TOKEN -u REPO_URL -m 3 -l "docker,gpu"
-
-# Using a profile
-hydra create -p production -t YOUR_TOKEN
+hydra init              # Interactive
+hydra init --toml       # Use TOML format
 ```
 
-### 3. Monitor Status
-
-```bash
-# Check runner status
-hydra status -t YOUR_TOKEN -u REPO_URL
-
-# JSON output for automation
-hydra status -t YOUR_TOKEN -u REPO_URL --json
-```
+### `hydra create`
 
-## 📖 Commands
+Create and register new runners.
 
-### `hydra init`
-Initialize a new configuration file with profiles.
+```bash
+# Basic
+hydra create -t TOKEN -u REPO_URL
 
-**Options:**
-- `-t, --toml` - Use TOML format instead of JSON
+# Multiple with labels
+hydra create -t TOKEN -u REPO_URL -m 5 -l "docker,gpu"
 
-### `hydra create`
-Create and register new GitHub runner machines.
+# Using profile
+hydra create -p production -t TOKEN
+```
 
 **Options:**
-- `-t, --token` - GitHub Personal Access Token (required)
-- `-u, --url` - GitHub repository/organization URL (required)
-- `-m, --numberOfMachines` - Number of runners to create (default: 1)
-- `-n, --name` - Runner name prefix (default: "runner")
-- `-l, --labels` - Comma-separated custom labels
-- `-d, --directory` - Runners directory (default: "./gh-runners")
-- `-o, --os` - Operating system: osx, linux, windows (default: "osx")
-- `-O, --overwrite` - Overwrite existing runners
-- `-p, --profile` - Use configuration profile
-- `-c, --config` - Configuration file path
+- `-t, --token` — GitHub PAT (required)
+- `-u, --url` — Repo/org URL (required)
+- `-m, --numberOfMachines` — Number of runners (default: 1)
+- `-n, --name` — Runner name prefix
+- `-l, --labels` — Comma-separated labels
+- `-d, --directory` — Runners directory
+- `-o, --os` — OS: osx, linux, windows
+- `-p, --profile` — Use config profile
 
 ### `hydra run`
-Start existing GitHub runner machines.
 
-**Options:**
-- `-t, --token` - GitHub Personal Access Token (required)
-- `-u, --url` - GitHub repository/organization URL (required)
-- `-m, --numberOfMachines` - Number of runners (default: 1)
-- `-n, --name` - Runner name prefix
-- `-d, --directory` - Runners directory
-- `-p, --profile` - Use configuration profile
-- `-c, --config` - Configuration file path
+Start existing runners.
+
+```bash
+hydra run -t TOKEN -u REPO_URL -m 3
+hydra run -p production -t TOKEN
+```
 
 ### `hydra remove`
-Remove GitHub runner machines.
 
-**Options:**
-- `-t, --token` - GitHub Personal Access Token (required)
-- `-u, --url` - GitHub repository/organization URL (required)
-- `-m, --numberOfMachines` - Number of runners (default: 1)
-- `-n, --name` - Runner name prefix
-- `-d, --directory` - Runners directory
-- `-f, --force` - Force removal without unregistering
-- `-p, --profile` - Use configuration profile
-- `-c, --config` - Configuration file path
+Remove runners and unregister from GitHub.
 
-### `hydra status`
-Check the status of GitHub runner machines.
+```bash
+hydra remove -t TOKEN -u REPO_URL -m 3
+hydra remove -p production -t TOKEN -f  # Force without unregistering
+```
 
-**Options:**
-- `-t, --token` - GitHub Personal Access Token (required)
-- `-u, --url` - GitHub repository/organization URL (required)
-- `-d, --directory` - Runners directory
-- `-j, --json` - Output as JSON
-- `-p, --profile` - Use configuration profile
-- `-c, --config` - Configuration file path
+### `hydra status`
 
-### `hydra help`
-Show help information for commands.
+Check runner status.
 
 ```bash
-hydra help
-hydra help create
-hydra create --help
+hydra status -t TOKEN -u REPO_URL
+hydra status -p production -t TOKEN --json
 ```
 
-## 🔧 Configuration
-
-### The Magic of Profiles 🎭
+## Configuration
 
-Stop typing the same commands over and over. Profiles let you define your runner configurations once and reuse them everywhere:
+### Profiles
 
-#### Example: `hydra.json`
+Save common configs in `hydra.json` or `hydra.toml`:
 
 ```json
 {
   "profiles": {
-    "default": {
-      "name": "runner",
-      "numberOfMachines": 1,
-      "directory": "./gh-runners",
-      "os": "osx"
-    },
     "production": {
       "url": "https://github.com/org/repo",
       "name": "prod-runner",
       "numberOfMachines": 3,
-      "labels": "production,linux,docker",
-      "directory": "/opt/runners/prod",
+      "labels": "linux,docker",
+      "directory": "/opt/runners",
       "os": "linux"
     },
-    "development": {
+    "dev": {
       "url": "https://github.com/org/dev-repo",
       "name": "dev-runner",
       "numberOfMachines": 2,
-      "labels": "development,test",
-      "directory": "./dev-runners"
+      "labels": "test"
     }
   },
-  "defaultProfile": "default"
+  "defaultProfile": "production"
 }
 ```
 
-#### Example: `hydra.toml`
-
-```toml
-defaultProfile = "default"
+Then use with `-p`:
 
-[profiles.default]
-name = "runner"
-numberOfMachines = 1
-directory = "./gh-runners"
-os = "linux"
-
-[profiles.production]
-url = "https://github.com/org/repo"
-name = "prod-runner"
-numberOfMachines = 3
-labels = "production,linux,docker"
-directory = "/opt/runners/prod"
-os = "linux"
+```bash
+hydra create -p production -t $TOKEN
+hydra status -p dev -t $TOKEN
 ```
 
 ### Environment Variables
 
-- `GITHUB_PERSONAL_ACCESS_TOKEN` - Default token if not provided via CLI
-- `HYDRA_CONFIG` - Default configuration file path
-
-## 📂 Directory Structure
-
-```
-./gh-runners/              # Default runner directory
-├── machines/
-│   ├── 1/                # Runner instance 1
-│   │   ├── _diag/        # Diagnostics logs
-│   │   ├── _work/        # Job working directory
-│   │   ├── config.sh     # Runner configuration
-│   │   └── run.sh        # Runner execution script
-│   ├── 2/                # Runner instance 2
-│   └── .../
-└── actions-runner-*.tar.gz  # Downloaded runner package
-```
-
-## 🔐 Security
-
-### Token Requirements
-
-- **Repository runners**: Token needs `repo` scope
-- **Organization runners**: Token needs `admin:org` scope
-- Tokens are never stored in configuration files
-- Use environment variables for automation
+- `GITHUB_PERSONAL_ACCESS_TOKEN` — Default token
+- `HYDRA_CONFIG` — Config file path
 
-### Best Practices
+## Token Permissions
 
-1. Never commit tokens to version control
-2. Use read-only tokens when possible
-3. Rotate tokens regularly
+- **Repository runners:** `repo` scope
+- **Organization runners:** `admin:org` scope
 
-## 📊 Examples
+Never commit tokens. Use environment variables or pass via `-t`.
 
-### CI/CD Pipeline Setup
+## Examples
 
 ```bash
-# Development environment
-hydra create -p development -t $GITHUB_TOKEN -m 2
+# Development setup
+hydra create -p dev -t $TOKEN -m 2
 
 # Production with specific labels
-hydra create -p production -t $GITHUB_TOKEN -l "deploy,production"
+hydra create -p prod -t $TOKEN -l "deploy,production"
 
-# Temporary test runners
-hydra create -t $GITHUB_TOKEN -u $REPO_URL -n "test" -m 5
-hydra remove -t $GITHUB_TOKEN -u $REPO_URL -n "test" -m 5
-```
-
-### Monitoring Script
-
-```bash
-#!/bin/bash
-# Check runner status and alert if offline
+# Monitor all runners
+hydra status -p prod -t $TOKEN --json | jq '.[] | select(.status == "offline")'
 
-STATUS=$(hydra status -p production -t $GITHUB_TOKEN --json)
-OFFLINE=$(echo $STATUS | jq '[.[] | select(.status == "offline")] | length')
-
-if [ $OFFLINE -gt 0 ]; then
-  echo "Alert: $OFFLINE runners are offline!"
-fi
+# Cleanup
+hydra remove -p dev -t $TOKEN
 ```
 
-## 🐛 Troubleshooting
-
-### Common Issues
-
-1. **"Invalid GitHub token"**
-   - Verify token permissions (repo/admin:org scope)
-   - Check token expiration
-
-2. **"Runner configuration failed"**
-   - Check network connectivity
-   - Verify GitHub URL format
-   - Ensure write permissions in runner directory
+## Troubleshooting
 
-3. **"No runners found"**
-   - Verify runner directory path
-   - Check if runners were created successfully
-   - Ensure profile name is correct
+**Invalid token error:**
+- Check token has `repo` or `admin:org` scope
+- Verify token isn't expired
 
-### Debug Mode
+**Runner config failed:**
+- Check network connectivity
+- Verify GitHub URL format
+- Ensure write permissions in runner directory
 
+**Debug mode:**
 ```bash
-# Run with debug logging
 DEBUG=* hydra create -t TOKEN -u URL
-
-# Check runner diagnostics (if needed)
-cat ./gh-runners/machines/1/_diag/*.log
 ```
 
-## 🤝 Contributing
-
-Contributions are welcome! Please see the [main repository](https://github.com/r5n-labs/clis) for contribution guidelines.
-
-## 📄 License
-
-Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
+## License
 
----
+Apache 2.0 — see [LICENSE](./LICENSE)