@artik0din/turbogha 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +67 -214
  2. package/dist/cli/index.js +14883 -48194
  3. package/dist/cli/licenses.txt +2680 -1085
  4. package/package.json +1 -61
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # TurboGHA
2
2
 
3
- > Supercharge your Turborepo builds with free, self-hosted remote caching on GitHub Actions
3
+ > Free, self-hosted Turborepo remote caching for GitHub Actions
4
4
 
5
5
  [![CI](https://github.com/globodai-group/caching-for-turbo/actions/workflows/ci.yml/badge.svg)](https://github.com/globodai-group/caching-for-turbo/actions/workflows/ci.yml)
6
6
  [![npm](https://img.shields.io/npm/v/@artik0din/turbogha)](https://www.npmjs.com/package/@artik0din/turbogha)
@@ -9,204 +9,93 @@
9
9
 
10
10
  ## Why TurboGHA?
11
11
 
12
- [Turborepo](https://turbo.build/repo/) is amazing for monorepo builds, but remote caching typically requires a Vercel account. **TurboGHA** provides a free, self-hosted alternative that runs entirely within GitHub's ecosystem.
12
+ [Turborepo](https://turbo.build/repo/) remote caching typically requires a Vercel account. **TurboGHA** provides a free alternative using GitHub's built-in cache.
13
13
 
14
- | | TurboGHA | Vercel Remote Cache |
14
+ | | TurboGHA | Vercel |
15
15
  |---|:---:|:---:|
16
- | **Cost** | Free | Paid (large teams) |
16
+ | **Cost** | Free | Paid |
17
17
  | **Setup** | 1 line | Account + tokens |
18
- | **Storage** | GitHub Cache / S3 | Vercel only |
19
- | **Control** | Full | Limited |
20
18
  | **Dependencies** | None | Vercel account |
21
19
 
22
20
  ## Quick Start
23
21
 
24
- Add this step **before** your `turbo` commands:
25
-
26
22
  ```yaml
27
- - name: Setup Turbo Cache
28
- uses: globodai-group/caching-for-turbo@v1
23
+ - uses: globodai-group/caching-for-turbo@v1
29
24
 
30
- - name: Build
31
- run: turbo build
25
+ - run: turbo build
32
26
  ```
33
27
 
34
- That's it! Your builds now use GitHub's built-in cache system.
28
+ That's it.
35
29
 
36
30
  ## How It Works
37
31
 
38
32
  ```
39
- ┌─────────────────────────────────────────────────────────────┐
40
- │ GitHub Actions Runner │
41
- ├─────────────────────────────────────────────────────────────┤
42
- │ │
43
- │ ┌─────────┐ HTTP ┌──────────────┐ │
44
- │ │ Turbo │ ──────────► │ TurboGHA │ │
45
- │ │ Build │ ◄────────── │ Server │ │
46
- │ └─────────┘ │ :41230 │ │
47
- │ └──────┬───────┘ │
48
- │ │ │
49
- │ ▼ │
50
- │ ┌────────────────────────┐ │
51
- │ │ Storage Backend │ │
52
- │ │ ┌─────────┐ ┌─────┐ │ │
53
- │ │ │ GitHub │ │ S3 │ │ │
54
- │ │ │ Cache │ │ │ │ │
55
- │ │ └─────────┘ └─────┘ │ │
56
- │ └────────────────────────┘ │
57
- └─────────────────────────────────────────────────────────────┘
33
+ ┌──────────────────────────────────────────────────┐
34
+ │ GitHub Actions Runner │
35
+ ├──────────────────────────────────────────────────┤
36
+ │ │
37
+ │ ┌─────────┐ ┌──────────────┐ │
38
+ │ │ Turbo │ ◄─────► │ TurboGHA │ │
39
+ │ │ Build │ HTTP │ :41230 │ │
40
+ │ └─────────┘ └──────┬───────┘ │
41
+ │ │ │
42
+ │ ▼ │
43
+ │ ┌──────────────────┐ │
44
+ │ │ GitHub Cache │ │
45
+ │ │ (10GB free) │ │
46
+ │ └──────────────────┘ │
47
+ └──────────────────────────────────────────────────┘
58
48
  ```
59
49
 
60
- 1. **Setup Phase**: Starts a local Fastify server on `localhost:41230`
61
- 2. **Environment**: Configures `TURBO_API`, `TURBO_TOKEN`, `TURBO_TEAM`
62
- 3. **Caching**: Intercepts Turbo cache requests and stores in GitHub Cache or S3
63
- 4. **Cleanup**: Gracefully shuts down and displays statistics
50
+ 1. Starts a local Fastify server on `localhost:41230`
51
+ 2. Configures `TURBO_API`, `TURBO_TOKEN`, `TURBO_TEAM`
52
+ 3. Intercepts Turbo cache requests → GitHub Cache API
53
+ 4. Displays statistics on shutdown
64
54
 
65
55
  ## Configuration
66
56
 
67
- ### Basic Usage
68
-
69
- ```yaml
70
- - uses: globodai-group/caching-for-turbo@v1
71
- ```
72
-
73
- ### With Options
74
-
75
57
  ```yaml
76
58
  - uses: globodai-group/caching-for-turbo@v1
77
59
  with:
78
- # Storage backend: 'github' (default) or 's3'
79
- provider: github
80
-
81
- # Cache key prefix (useful for cache isolation)
60
+ # Cache key prefix (useful for isolation)
82
61
  cache-prefix: my-project_
83
62
 
84
- # Server port
63
+ # Server port (default: 41230)
85
64
  server-port: 41230
86
65
  ```
87
66
 
88
- ### Cache Management
89
-
90
- Prevent unbounded cache growth:
91
-
92
- ```yaml
93
- - uses: globodai-group/caching-for-turbo@v1
94
- with:
95
- # Remove entries older than duration
96
- max-age: 2w # Supports: 1d, 1w, 1mo
97
-
98
- # Keep only N most recent entries
99
- max-files: 300
100
-
101
- # Remove oldest when size exceeds limit
102
- max-size: 5gb # Supports: 100mb, 1gb, 10gb
103
- ```
104
-
105
- ### S3 Storage
67
+ ### Inputs
106
68
 
107
- For teams needing dedicated infrastructure:
108
-
109
- ```yaml
110
- - uses: globodai-group/caching-for-turbo@v1
111
- with:
112
- provider: s3
113
- s3-bucket: my-turbo-cache
114
- s3-region: us-east-1
115
- s3-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
116
- s3-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
117
-
118
- # Optional
119
- s3-endpoint: https://s3.amazonaws.com
120
- s3-prefix: cache/
121
- s3-session-token: ${{ secrets.AWS_SESSION_TOKEN }}
122
- ```
123
-
124
- **Compatible with**: AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, Backblaze B2
125
-
126
- ## CLI for Local Development
127
-
128
- Use the same caching infrastructure locally:
69
+ | Input | Description | Default |
70
+ |-------|-------------|---------|
71
+ | `cache-prefix` | Cache key prefix | `turbogha_` |
72
+ | `server-port` | Server port | `41230` |
129
73
 
130
- ### Installation
74
+ ## CLI (Local Development)
131
75
 
132
76
  ```bash
133
77
  npm install -g @artik0din/turbogha
134
- # or
135
- npx @artik0din/turbogha
136
- ```
137
-
138
- ### Commands
139
-
140
- ```bash
141
- # Start cache server (background)
142
- turbogha start
143
-
144
- # Start in foreground (for debugging)
145
- turbogha start --foreground
146
-
147
- # Check server status
148
- turbogha ping
149
-
150
- # Stop server
151
- turbogha kill
152
78
  ```
153
79
 
154
- ### Local Configuration
155
-
156
- Create `.env` in your project root:
157
-
158
- ```env
159
- # Storage provider
160
- PROVIDER=s3
161
-
162
- # S3 credentials
163
- AWS_ACCESS_KEY_ID=your-key
164
- AWS_SECRET_ACCESS_KEY=your-secret
165
- AWS_REGION=us-east-1
166
- S3_BUCKET=my-bucket
167
- S3_PREFIX=turbogha/
168
-
169
- # Optional
170
- SERVER_PORT=41230
171
- CACHE_PREFIX=local_
172
- ```
173
-
174
- ### Using with Turbo
175
-
176
80
  ```bash
177
- # Start the server
81
+ # Start server
178
82
  turbogha start
179
83
 
180
- # Configure Turbo (add to .bashrc/.zshrc for persistence)
84
+ # Configure Turbo
181
85
  export TURBO_API=http://localhost:41230
182
86
  export TURBO_TOKEN=turbogha
183
87
  export TURBO_TEAM=turbogha
184
88
 
185
- # Run builds with remote caching
89
+ # Build
186
90
  turbo build
187
- ```
188
-
189
- ## Inputs Reference
190
91
 
191
- | Input | Description | Default |
192
- |-------|-------------|---------|
193
- | `provider` | Storage backend (`github` or `s3`) | `github` |
194
- | `cache-prefix` | Cache key prefix | `turbogha_` |
195
- | `server-port` | Local server port | `41230` |
196
- | `max-age` | Max cache age (e.g., `1w`, `1mo`) | - |
197
- | `max-files` | Max number of cached files | - |
198
- | `max-size` | Max total cache size (e.g., `5gb`) | - |
199
- | `s3-access-key-id` | AWS access key ID | - |
200
- | `s3-secret-access-key` | AWS secret access key | - |
201
- | `s3-session-token` | AWS session token (for OIDC) | - |
202
- | `s3-bucket` | S3 bucket name | - |
203
- | `s3-region` | S3 region | - |
204
- | `s3-endpoint` | S3 endpoint URL | `https://s3.amazonaws.com` |
205
- | `s3-prefix` | S3 object prefix | `turbogha/` |
92
+ # Stop server
93
+ turbogha kill
94
+ ```
206
95
 
207
96
  ## Examples
208
97
 
209
- ### Monorepo with Multiple Apps
98
+ ### Monorepo
210
99
 
211
100
  ```yaml
212
101
  jobs:
@@ -214,17 +103,12 @@ jobs:
214
103
  runs-on: ubuntu-latest
215
104
  steps:
216
105
  - uses: actions/checkout@v4
217
-
218
106
  - uses: globodai-group/caching-for-turbo@v1
219
- with:
220
- cache-prefix: ${{ github.repository }}_
221
-
222
107
  - run: npm ci
223
- - run: turbo build --filter=@myorg/web
224
- - run: turbo build --filter=@myorg/api
108
+ - run: turbo build
225
109
  ```
226
110
 
227
- ### Matrix Build with Isolated Caches
111
+ ### Matrix Build
228
112
 
229
113
  ```yaml
230
114
  jobs:
@@ -235,88 +119,57 @@ jobs:
235
119
  runs-on: ${{ matrix.os }}
236
120
  steps:
237
121
  - uses: actions/checkout@v4
238
-
239
122
  - uses: globodai-group/caching-for-turbo@v1
240
123
  with:
241
124
  cache-prefix: ${{ matrix.os }}_
242
-
243
125
  - run: npm ci
244
126
  - run: turbo build test lint
245
127
  ```
246
128
 
247
- ### S3 with Automatic Cleanup
248
-
249
- ```yaml
250
- - uses: globodai-group/caching-for-turbo@v1
251
- with:
252
- provider: s3
253
- s3-bucket: ${{ vars.CACHE_BUCKET }}
254
- s3-region: eu-west-1
255
- s3-access-key-id: ${{ secrets.AWS_KEY }}
256
- s3-secret-access-key: ${{ secrets.AWS_SECRET }}
257
- max-age: 1w
258
- max-size: 10gb
259
- ```
129
+ ## Metrics
260
130
 
261
- ## Performance Tips
131
+ TurboGHA displays statistics on shutdown:
262
132
 
263
- 1. **Use cache prefixes** to isolate caches between branches/PRs
264
- 2. **Set cleanup policies** to prevent cache bloat (especially with S3)
265
- 3. **Use S3** for very large caches or cross-workflow sharing
266
- 4. **Run cache server early** in your workflow for maximum benefit
133
+ ```
134
+ ╔══════════════════════════════════════════╗
135
+ ║ TurboGHA Statistics ║
136
+ ╠══════════════════════════════════════════╣
137
+ ║ Cache Hit Rate: 85.7% ║
138
+ ║ Hits: 12 | Misses: 2 ║
139
+ ╠══════════════════════════════════════════╣
140
+ ║ Uploads: 2 ( 12.4MB) ║
141
+ ║ Downloads: 12 ( 89.2MB) ║
142
+ ╠══════════════════════════════════════════╣
143
+ ║ Avg Save: 245ms ║
144
+ ║ Avg Get: 89ms ║
145
+ ╚══════════════════════════════════════════╝
146
+ ```
267
147
 
268
148
  ## Troubleshooting
269
149
 
270
- ### Cache not being used
271
-
272
- - Ensure the action runs **before** any `turbo` commands
273
- - Check that `TURBO_API`, `TURBO_TOKEN`, `TURBO_TEAM` are set
274
- - Verify no conflicting Turbo remote cache configuration
275
-
276
- ### Server fails to start
150
+ **Cache not being used?**
151
+ - Run action **before** `turbo` commands
152
+ - Check `TURBO_API`, `TURBO_TOKEN`, `TURBO_TEAM` are set
277
153
 
278
- - Check if port 41230 is available
279
- - Try a different port with `server-port` input
280
- - Check workflow logs for detailed error messages
281
-
282
- ### S3 connection issues
283
-
284
- - Verify credentials have `s3:GetObject`, `s3:PutObject`, `s3:ListBucket` permissions
285
- - Check bucket region matches `s3-region` input
286
- - For custom endpoints, ensure `s3-endpoint` is correctly formatted
154
+ **Server fails to start?**
155
+ - Check port 41230 is available
156
+ - Try different port with `server-port`
287
157
 
288
158
  ## Contributing
289
159
 
290
160
  ```bash
291
- # Clone the repository
292
161
  git clone https://github.com/globodai-group/caching-for-turbo.git
293
- cd caching-for-turbo
294
-
295
- # Install dependencies
296
162
  npm install
297
-
298
- # Run development server
299
163
  npm run dev-run
300
-
301
- # Build
302
164
  npm run bundle
303
-
304
- # Lint
305
- npm run lint
306
165
  ```
307
166
 
308
167
  ## License
309
168
 
310
- MIT License - see [LICENSE](LICENSE) for details.
311
-
312
- ## Credits
313
-
314
- Built with inspiration from:
315
- - [rharkor/caching-for-turbo](https://github.com/rharkor/caching-for-turbo) - Original implementation
316
- - [dtinth/setup-github-actions-caching-for-turbo](https://github.com/dtinth/setup-github-actions-caching-for-turbo) - Original concept
169
+ MIT
317
170
 
318
171
  ---
319
172
 
320
173
  <p align="center">
321
- Made with care by <a href="https://github.com/globodai-group">Globodai Group</a>
174
+ <a href="https://github.com/globodai-group">Globodai Group</a>
322
175
  </p>