@theholocron/holocron-plugin-turbo 0.0.0-stage → 5.0.0-alpha.453

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Newton Koumantzelis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,38 @@
1
- # Temporary Holding Version
1
+ # `@theholocron/holocron-plugin-turbo`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Turbo plugin for [Holocron](../cli). Implements the `cache` capability for
4
+ [Turborepo's Remote Cache](https://turborepo.com/docs/core-concepts/remote-caching), which Vercel serves.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ pnpm add -D @theholocron/holocron-plugin-turbo@alpha
10
+ ```
11
+
12
+ ## Auth
13
+
14
+ The token is a Vercel token. Resolution order:
15
+
16
+ 1. `--token <TOKEN>` flag on the holocron invocation
17
+ 2. `HOLOCRON_TURBO_TOKEN` env var
18
+ 3. `TURBO_TOKEN` env var (the one Turborepo reads)
19
+ 4. Keyring `turbo`, set via `holocron new token turbo <token>`
20
+
21
+ The team is `HOLOCRON_TURBO_TEAM`, then `TURBO_TEAM` (a team slug, or a `team_...` id). It is not a secret.
22
+
23
+ ## Config
24
+
25
+ ```ts
26
+ providers: {
27
+ cache: "turbo",
28
+ }
29
+ ```
30
+
31
+ The organization's `holocron_capabilities` property must allow `cache` (`holocron apply properties`) before a repo
32
+ declares it.
33
+
34
+ ## What it checks
35
+
36
+ `cache.checkToken()` and `holocron probe turbo token` ask Vercel's `GET /v8/artifacts/status` for the team and report
37
+ whether the token is accepted and the cache answers. Vercel does not report a token's scope, so permissions are not
38
+ checked. See the [docs page](https://docs.theholocron.dev/holocron/plugins/turbo/).
@@ -0,0 +1,67 @@
1
+ /**
2
+ * `@theholocron/holocron-plugin-turbo` — entrypoint.
3
+ *
4
+ * Implements the `cache` capability for Turborepo's remote cache, which Vercel serves. See README for auth + config
5
+ * docs.
6
+ */
7
+ import { AuthError, Cache, CacheTokenCheck, PluginToken, ResolveTokenInput } from "@theholocron/cli";
8
+ import { TurboClient, TurboClientOptions, createTurboClient } from "@theholocron/turbo-client";
9
+ /**
10
+ * Resolves the Turbo remote-cache token from `--token`, `HOLOCRON_TURBO_TOKEN`, `TURBO_TOKEN` or the keyring, and
11
+ * throws an `AuthError` when none is set. It is a Vercel token: Vercel serves the remote cache.
12
+ */
13
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
14
+ /** Every token this plugin takes, for `holocron doctor tokens`, with the layers that hold it. */
15
+ export declare const tokens: PluginToken[];
16
+ /** What is shown when no team is set: the variable to set, and what happens without it. */
17
+ export declare const NO_TEAM = "no team: set HOLOCRON_TURBO_TEAM (or TURBO_TEAM); without it Turborepo turns the remote cache off";
18
+ /** The `cache` capability for Turbo: checks that Vercel accepts the token and the remote cache answers for the team. */
19
+ export declare class TurboCache implements Cache {
20
+ private readonly client;
21
+ private readonly team;
22
+ /** The capability key, always `cache`. */
23
+ readonly key: "cache";
24
+ /** The provider name, `turbo`. */
25
+ readonly providerName = "turbo";
26
+ /** `client` and `team` are thunks: the token and the team are read when a method runs, not when the plugin loads. */
27
+ constructor(client: () => TurboClient, team: () => string | undefined);
28
+ checkToken(): Promise<CacheTokenCheck>;
29
+ }
30
+ /** Options for the Turbo plugin: token resolution, the team and test overrides. */
31
+ export interface TurboPluginOptions extends ResolveTokenInput {
32
+ /**
33
+ * The team whose remote cache is checked: a Vercel team slug (what Turborepo reads as `TURBO_TEAM`) or a `team_...`
34
+ * id. Defaults to `HOLOCRON_TURBO_TEAM`, then `TURBO_TEAM`, which are not secrets.
35
+ */
36
+ team?: string;
37
+ /** Override base URL for tests. */
38
+ baseUrl?: string;
39
+ /** Override `fetch` for tests. */
40
+ fetch?: typeof fetch;
41
+ }
42
+ /** What the plugin's capability and probe share: the options, the team and a lazily built client. */
43
+ export interface PluginContext {
44
+ /** The options the plugin was created with. */
45
+ options: TurboPluginOptions;
46
+ /** The configured team, read when called: the option, then `HOLOCRON_TURBO_TEAM` / `TURBO_TEAM`; `undefined` when none. */
47
+ team: () => string | undefined;
48
+ /** The resolved token; throws an `AuthError` when none is set. */
49
+ token: () => string;
50
+ /** Builds the client on first call and reuses it; the token is resolved then, not at plugin load. */
51
+ client: () => TurboClient;
52
+ }
53
+ /** Creates the shared context for the given options; no token or team is resolved until one is asked for. */
54
+ export declare function createContext(options?: TurboPluginOptions): PluginContext;
55
+ /** Builds the `cache` capability from a plugin context. */
56
+ export declare function cache(ctx: PluginContext): Cache;
57
+ /** Creates the Turbo plugin: the `token` probe and the `cache` capability. */
58
+ export declare function createPlugin(options?: TurboPluginOptions): {
59
+ name: string;
60
+ probes: {
61
+ token: import("@theholocron/cli").Probe;
62
+ };
63
+ capabilities: {
64
+ cache: () => Cache;
65
+ };
66
+ };
67
+ export { AuthError, type ResolveTokenInput, type TurboClient, type TurboClientOptions, createTurboClient };
package/dist/index.mjs ADDED
@@ -0,0 +1,258 @@
1
+ import { AuthError, ProviderApiError, createResolveToken, resolveValue, tokenExpectations } from "@theholocron/cli";
2
+ import { PREFIX } from "@theholocron/env-utils/lookup";
3
+ import { errorMessage } from "@theholocron/misc-utils";
4
+ import { createTurboClient } from "@theholocron/turbo-client";
5
+ // src/probes/token/expectations.ts
6
+ /**
7
+ * Where the Turbo remote-cache token is held: CI only. `dev` holds none today; when one is added, `dev` and `local` are
8
+ * added here (one change) and a layer that holds the token without being declared fails the check. The token is a
9
+ * Vercel token and Vercel does not report a token's scope, so no permissions are declared and the probe says so
10
+ * instead of guessing. This is the plugin's `tokens` declaration, read through `tokenExpectations()`; change it and the
11
+ * Turbo row in `docs/src/content/docs/tokens.mdx` together.
12
+ */
13
+ const EXPECTED = { layers: ["ci"] };
14
+ // src/auth.ts
15
+ /**
16
+ * Resolves the Turbo remote-cache token from `--token`, `HOLOCRON_TURBO_TOKEN`, `TURBO_TOKEN` or the keyring, and
17
+ * throws an `AuthError` when none is set. It is a Vercel token: Vercel serves the remote cache.
18
+ */
19
+ const resolveToken = createResolveToken({
20
+ envName: "HOLOCRON_TURBO_TOKEN",
21
+ vendorEnvName: "TURBO_TOKEN",
22
+ keyringService: "turbo",
23
+ errorMessage: "no Turbo token found. Pass --token <VERCEL_TOKEN>, set HOLOCRON_TURBO_TOKEN / TURBO_TOKEN, or run: holocron new token turbo <VERCEL_TOKEN>"
24
+ });
25
+ /** Every token this plugin takes, for `holocron doctor tokens`, with the layers that hold it. */
26
+ const tokens = [{
27
+ ...resolveToken.token,
28
+ expect: EXPECTED
29
+ }];
30
+ // src/capabilities/cache.ts
31
+ /** What is shown when no team is set: the variable to set, and what happens without it. */
32
+ const NO_TEAM = "no team: set HOLOCRON_TURBO_TEAM (or TURBO_TEAM); without it Turborepo turns the remote cache off";
33
+ /** The `cache` capability for Turbo: checks that Vercel accepts the token and the remote cache answers for the team. */
34
+ var TurboCache = class {
35
+ client;
36
+ team;
37
+ /** The capability key, always `cache`. */
38
+ key = "cache";
39
+ /** The provider name, `turbo`. */
40
+ providerName = "turbo";
41
+ /** `client` and `team` are thunks: the token and the team are read when a method runs, not when the plugin loads. */
42
+ constructor(client, team) {
43
+ this.client = client;
44
+ this.team = team;
45
+ }
46
+ async checkToken() {
47
+ const team = this.team();
48
+ if (!team) return {
49
+ ok: false,
50
+ problem: "team",
51
+ reason: NO_TEAM
52
+ };
53
+ try {
54
+ const { status, readOnly } = await this.client().cache.status(team);
55
+ const read = readOnly === true ? { readOnly: true } : {};
56
+ if (status === "enabled") return {
57
+ ok: true,
58
+ status,
59
+ ...read,
60
+ ...readOnly === true ? { reason: "the token can read the cache but not upload to it" } : {}
61
+ };
62
+ return {
63
+ ok: false,
64
+ problem: "cache",
65
+ status,
66
+ ...read,
67
+ reason: `Remote Caching is ${status} for ${team}`
68
+ };
69
+ } catch (err) {
70
+ if (err instanceof ProviderApiError) switch (err.status) {
71
+ case 401: return {
72
+ ok: false,
73
+ problem: "token",
74
+ reason: "Vercel refused the token (401)"
75
+ };
76
+ case 403: return {
77
+ ok: false,
78
+ problem: "team",
79
+ reason: `the token has no access to ${team} (403)`
80
+ };
81
+ case 404: return {
82
+ ok: false,
83
+ problem: "team",
84
+ reason: `${team} was not found (404)`
85
+ };
86
+ case 402: return {
87
+ ok: false,
88
+ problem: "cache",
89
+ reason: `${team} needs a payment method for Remote Caching (402)`
90
+ };
91
+ case 410: return {
92
+ ok: false,
93
+ problem: "cache",
94
+ reason: `Remote Caching is no longer available for ${team} (410)`
95
+ };
96
+ }
97
+ throw err;
98
+ }
99
+ }
100
+ };
101
+ // src/probes/token/parse-layer.ts
102
+ /** Reads `--layer <word>` (or `--layer=<word>`) from the words after the probe name, which the CLI passes when `--environment` named a layer. */
103
+ function parseLayer(args) {
104
+ for (let i = 0; i < args.length; i++) {
105
+ const arg = args[i];
106
+ if (arg === "--layer") return args[i + 1];
107
+ if (arg.startsWith("--layer=")) return arg.slice(8);
108
+ }
109
+ }
110
+ // src/probes/token/token.ts
111
+ /** The states Vercel documents for Remote Caching; anything else is described, not failed. */
112
+ const KNOWN_STATES = /* @__PURE__ */ new Set([
113
+ "enabled",
114
+ "disabled",
115
+ "over_limit",
116
+ "paused"
117
+ ]);
118
+ /**
119
+ * The `token` probe for Turbo. It asks Vercel's remote-cache status endpoint for the configured team
120
+ * (`HOLOCRON_TURBO_TEAM`), which proves the token is accepted and the cache answers for that team: reads only. Vercel
121
+ * does not report a token's scope (Full Account or a team), so the probe says it cannot judge permissions. With
122
+ * `--layer` (passed because `--environment` named a layer) it also says whether that layer is one that should hold the
123
+ * token, from the plugin's `tokens` declaration. A token with no team is a failure naming the variable. The token is
124
+ * never printed.
125
+ */
126
+ function tokenProbe(ctx) {
127
+ return {
128
+ summary: "Check a Turbo remote-cache token: that Vercel accepts it and that the remote cache answers for the configured team (HOLOCRON_TURBO_TEAM). Vercel cannot report a token's scope, so permissions are not checked. Read-only.",
129
+ writes: false,
130
+ acceptsToken: true,
131
+ async run(probe) {
132
+ probe.secret(ctx.token());
133
+ const layer = parseLayer(probe.args ?? []);
134
+ if (layer) {
135
+ const declared = tokenExpectations(tokens, { layer }).length > 0;
136
+ probe.say(declared ? {
137
+ status: "ok",
138
+ label: layer,
139
+ detail: "a layer that should hold this token"
140
+ } : {
141
+ status: "info",
142
+ label: layer,
143
+ detail: "not a layer this token is declared for, so it is only described"
144
+ });
145
+ }
146
+ const team = ctx.team();
147
+ if (!team) {
148
+ probe.say({
149
+ status: "fail",
150
+ label: "team",
151
+ detail: NO_TEAM
152
+ });
153
+ return;
154
+ }
155
+ probe.say({
156
+ status: "ok",
157
+ label: "team",
158
+ detail: team
159
+ });
160
+ let check;
161
+ try {
162
+ check = await ctx.cache().checkToken();
163
+ } catch (err) {
164
+ probe.say({
165
+ status: "fail",
166
+ label: "remote cache",
167
+ detail: errorMessage(err)
168
+ });
169
+ return;
170
+ }
171
+ if (check.problem === "token") {
172
+ probe.say({
173
+ status: "fail",
174
+ label: "token",
175
+ detail: check.reason ?? "refused"
176
+ });
177
+ return;
178
+ }
179
+ probe.say({
180
+ status: "ok",
181
+ label: "token",
182
+ detail: "accepted by Vercel"
183
+ });
184
+ if (check.problem === "team") {
185
+ probe.say({
186
+ status: "fail",
187
+ label: "team access",
188
+ detail: check.reason ?? "no access"
189
+ });
190
+ return;
191
+ }
192
+ probe.say({
193
+ status: "ok",
194
+ label: "team access",
195
+ detail: `the cache answers for ${team}`
196
+ });
197
+ if (check.status !== void 0 && !KNOWN_STATES.has(check.status)) probe.say({
198
+ status: "info",
199
+ label: "remote cache",
200
+ detail: `Vercel reported a state this probe does not know: ${check.status}`
201
+ });
202
+ else if (check.ok) probe.say({
203
+ status: "ok",
204
+ label: "remote cache",
205
+ detail: "enabled"
206
+ });
207
+ else probe.say({
208
+ status: "fail",
209
+ label: "remote cache",
210
+ detail: check.reason ?? check.status ?? "not usable"
211
+ });
212
+ if (check.readOnly) probe.say({
213
+ status: "info",
214
+ label: "upload",
215
+ detail: "the token can read the cache but not upload to it (Vercel reports it read-only)"
216
+ });
217
+ probe.say({
218
+ status: "info",
219
+ label: "permissions",
220
+ detail: "Vercel cannot report a token's scope (Full Account or a team), so it is not checked"
221
+ });
222
+ }
223
+ };
224
+ }
225
+ // src/index.ts
226
+ /** Creates the shared context for the given options; no token or team is resolved until one is asked for. */
227
+ function createContext(options = {}) {
228
+ let client;
229
+ const token = () => resolveToken(options);
230
+ return {
231
+ options,
232
+ token,
233
+ team: () => options.team ?? resolveValue(["TURBO_TEAM"], options.env, { prefix: PREFIX }),
234
+ client: () => client ??= createTurboClient({
235
+ token: token(),
236
+ baseUrl: options.baseUrl,
237
+ fetch: options.fetch
238
+ })
239
+ };
240
+ }
241
+ /** Builds the `cache` capability from a plugin context. */
242
+ function cache(ctx) {
243
+ return new TurboCache(ctx.client, ctx.team);
244
+ }
245
+ /** Creates the Turbo plugin: the `token` probe and the `cache` capability. */
246
+ function createPlugin(options = {}) {
247
+ const ctx = createContext(options);
248
+ return {
249
+ name: "@theholocron/holocron-plugin-turbo",
250
+ probes: { token: tokenProbe({
251
+ cache: () => cache(ctx),
252
+ team: ctx.team,
253
+ token: ctx.token
254
+ }) },
255
+ capabilities: { cache: () => cache(ctx) }
256
+ };
257
+ }
258
+ export { AuthError, NO_TEAM, TurboCache, cache, createContext, createPlugin, createTurboClient, resolveToken, tokens };
package/package.json CHANGED
@@ -1,6 +1,79 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-turbo",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "5.0.0-alpha.453",
4
+ "description": "Holocron plugin for Turborepo's Remote Cache. Implements the cache capability against Vercel's artifacts API.",
5
+ "keywords": [
6
+ "cache",
7
+ "holocron",
8
+ "plugin",
9
+ "remote-cache",
10
+ "turbo",
11
+ "turborepo"
12
+ ],
13
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/turbo/",
14
+ "bugs": "https://github.com/theholocron/holocron/issues",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/theholocron/holocron.git",
18
+ "directory": "plugins/holocron-plugin-turbo"
19
+ },
20
+ "license": "MIT",
21
+ "author": "Newton Koumantzelis",
22
+ "sideEffects": false,
23
+ "type": "module",
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/index.d.mts",
27
+ "import": "./dist/index.mjs",
28
+ "default": "./dist/index.mjs"
29
+ }
30
+ },
31
+ "files": [
32
+ "dist"
33
+ ],
34
+ "dependencies": {
35
+ "@theholocron/env-utils": "^1.17.0-alpha.4"
36
+ },
37
+ "devDependencies": {
38
+ "@types/node": "^26",
39
+ "@vitest/coverage-v8": "^5.1.0",
40
+ "@vitest/eslint-plugin": "^1.6.28",
41
+ "eslint": "^10.14.0",
42
+ "eslint-plugin-n": "^18.5.0",
43
+ "globals": "^17.14.0",
44
+ "tsdown": "^0.23.7",
45
+ "tsx": "4.23.15",
46
+ "typescript": "^5.9.3",
47
+ "vitest": "^5.1.0",
48
+ "@theholocron/http-client": "^1.58.0-alpha.37",
49
+ "@theholocron/eslint-config": "^8.9.0-alpha.18",
50
+ "@theholocron/misc-utils": "^1.17.0-alpha.4",
51
+ "@theholocron/tsconfig": "^8.9.0-alpha.18",
52
+ "@theholocron/cli": "5.0.0-alpha.453",
53
+ "@theholocron/turbo-client": "^1.58.0-alpha.37",
54
+ "@theholocron/tsdown-config": "^8.9.0-alpha.18",
55
+ "@theholocron/vitest-config": "^8.9.0-alpha.18"
56
+ },
57
+ "peerDependencies": {
58
+ "@theholocron/misc-utils": "^1.16.0",
59
+ "@theholocron/turbo-client": "^1.58.0",
60
+ "@theholocron/cli": "5.0.0-alpha.453"
61
+ },
62
+ "peerDependenciesMeta": {
63
+ "@theholocron/turbo-client": {}
64
+ },
65
+ "engines": {
66
+ "node": ">=22"
67
+ },
68
+ "publishConfig": {
69
+ "access": "public"
70
+ },
71
+ "scripts": {
72
+ "build": "tsdown",
73
+ "lint:code": "eslint .",
74
+ "test:unit": "vitest run --coverage",
75
+ "test:watch": "vitest",
76
+ "typecheck": "tsc --noEmit",
77
+ "validate:plugin": "tsx scripts/validate.mjs"
78
+ }
6
79
  }