@effected/github-actions 0.34.0 → 0.36.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 (46) hide show
  1. package/Action.js +10 -10
  2. package/ActionCache.js +17 -40
  3. package/ActionEnvironment.js +1 -1
  4. package/ActionInput.js +1 -1
  5. package/ActionLogger.js +197 -64
  6. package/ActionManifest.js +2 -2
  7. package/ActionOutputs.js +2 -2
  8. package/ActionState.js +1 -1
  9. package/ActionsIdentityToken.js +2 -2
  10. package/ActionsProvenance.js +2 -2
  11. package/ActionsRegistryCredential.js +2 -2
  12. package/Artifact.js +16 -39
  13. package/BlobStore.githubCache.js +16 -42
  14. package/BlobStore.js +4 -4
  15. package/CacheKey.js +2 -2
  16. package/CheckDocument.js +1 -1
  17. package/Checkout.js +361 -0
  18. package/DetachedProcess.js +4 -4
  19. package/DryRun.js +1 -1
  20. package/GitHubMarkdown.js +1 -1
  21. package/GitHubToken.js +2 -2
  22. package/ManagedDocument.js +1 -1
  23. package/OidcTokenIssuer.js +7 -7
  24. package/PackageManagerInstaller.js +3 -3
  25. package/README.md +4 -3
  26. package/Secret.js +1 -1
  27. package/ToolInstaller.js +4 -4
  28. package/index.d.ts +602 -119
  29. package/index.js +3 -2
  30. package/internal/actionsResults.js +1 -1
  31. package/internal/blobCause.js +2 -80
  32. package/internal/blobTransport.js +172 -0
  33. package/internal/cacheService.js +1 -1
  34. package/internal/checkout/asciiTrim.js +18 -0
  35. package/internal/checkout/credentials.js +563 -0
  36. package/internal/checkout/directory.js +119 -0
  37. package/internal/checkout/inputs.js +130 -0
  38. package/internal/checkout/refs.js +143 -0
  39. package/internal/checkout/settings.js +144 -0
  40. package/internal/checkout/source.js +418 -0
  41. package/internal/checkout/unsafePullRequest.js +62 -0
  42. package/internal/digest.js +1 -1
  43. package/internal/pnpmExe.js +1 -1
  44. package/internal/stepLog.js +225 -0
  45. package/internal/twirp.js +1 -1
  46. package/package.json +6 -6
@@ -1,15 +1,13 @@
1
+ import { Effect, Layer, Option } from "effect";
2
+ import { HttpClient } from "effect/http";
1
3
  import { ActionEnvironment } from "./ActionEnvironment.js";
2
4
  import { BlobEnvelope } from "./BlobEnvelope.js";
3
5
  import { BlobStore, BlobStoreError } from "./BlobStore.js";
4
- import { BlobTransferError } from "./BlobTransfer.js";
5
6
  import { misconfiguredDetail, resultsBackend } from "./internal/actionsResults.js";
6
- import { blobCause } from "./internal/blobCause.js";
7
+ import { httpDataTransfer } from "./internal/blobTransport.js";
7
8
  import { CACHE_SERVICE, finalizeUpload, lookupDownload, reserveUpload } from "./internal/cacheService.js";
8
9
  import { sha256Hex } from "./internal/digest.js";
9
10
  import { twirpCall, twirpFailureFields } from "./internal/twirp.js";
10
- import { Effect, Layer, Option } from "effect";
11
- import { HttpClient } from "effect/http";
12
- import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
13
11
 
14
12
  // src/BlobStore.githubCache.ts
15
13
  /**
@@ -26,34 +24,9 @@ import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
26
24
  * that strands every existing entry.
27
25
  */
28
26
  const VERSION = sha256Hex("blobstore|1.0");
29
- /**
30
- * The Azure half, ~15 lines and duplicated on purpose.
31
- *
32
- * @remarks
33
- * `@azure/storage-blob` may be imported by this module, `ActionCache` and
34
- * `Artifact` and by nothing else. Hoisting these two calls into a shared
35
- * `internal/` helper is exactly how the import would leak into the graph of a
36
- * module that only sets an output — so the three modules each carry their own,
37
- * and `__test__/reachability.test.ts` measures that they are the only three.
38
- */
39
- const azure = {
40
- uploadData: (url, data) => Effect.tryPromise({
41
- try: () => new BlockBlobClient(url).uploadData(data),
42
- catch: (cause) => new BlobTransferError({
43
- reason: "uploadFailed",
44
- cause: blobCause(cause)
45
- })
46
- }).pipe(Effect.asVoid),
47
- downloadToBuffer: (url) => Effect.tryPromise({
48
- try: () => new BlobClient(url).downloadToBuffer(),
49
- catch: (cause) => new BlobTransferError({
50
- reason: "downloadFailed",
51
- cause: blobCause(cause)
52
- })
53
- }).pipe(Effect.map((buffer) => new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)))
54
- };
55
- const make = (transfer) => Effect.gen(function* () {
27
+ const make = (custom) => Effect.gen(function* () {
56
28
  const http = yield* HttpClient.HttpClient;
29
+ const transfer = custom ?? httpDataTransfer(http);
57
30
  const env = yield* ActionEnvironment;
58
31
  const backend = resultsBackend(env).pipe(Effect.mapError((name) => new BlobStoreError({
59
32
  reason: "misconfigured",
@@ -114,9 +87,8 @@ const make = (transfer) => Effect.gen(function* () {
114
87
  * The Actions cache is reachable over a Twirp v2 protocol at
115
88
  * `ACTIONS_RESULTS_URL`, which answers a `CreateCacheEntry` /
116
89
  * `GetCacheEntryDownloadURL` RPC with a **pre-signed Azure blob url** — which is
117
- * why this backend lives in its own module rather than beside the S3 one: it,
118
- * `ActionCache` and `Artifact` are the only three modules that import the
119
- * Azure client.
90
+ * why this backend lives in its own module rather than beside the S3 one. The
91
+ * bytes move over the package's own `HttpClient` blob transport.
120
92
  *
121
93
  * **Only reachable from a `uses:` step.** The runner injects
122
94
  * `ACTIONS_RESULTS_URL` and `ACTIONS_RUNTIME_TOKEN` into action execution
@@ -126,9 +98,9 @@ const make = (transfer) => Effect.gen(function* () {
126
98
  * for exactly that reason.
127
99
  *
128
100
  * The layer statics live here rather than on {@link BlobStore} because a static
129
- * belongs to the module that owns the dependency it needs: putting
130
- * `BlobStore.layerGitHubCache` on the service class would make `@azure/storage-blob`
131
- * reachable from every module that reads a blob.
101
+ * belongs to the module that owns the protocol it needs: putting
102
+ * `BlobStore.layerGitHubCache` on the service class would make the Twirp cache
103
+ * protocol reachable from every module that reads a blob.
132
104
  *
133
105
  * @example
134
106
  * ```ts
@@ -142,21 +114,23 @@ const make = (transfer) => Effect.gen(function* () {
142
114
  var GitHubCacheBlobStore = class {
143
115
  constructor() {}
144
116
  /**
145
- * The backend, over the real Azure client.
117
+ * The backend, over the `HttpClient` blob transport.
146
118
  *
147
119
  * @remarks
148
- * Requires `ActionEnvironment` for `ACTIONS_RESULTS_URL` and
120
+ * Requires `HttpClient` in `R`: the signed-url upload and download go through
121
+ * the caller's client, not a bundled SDK or a platform client of this
122
+ * package's own. Requires `ActionEnvironment` for `ACTIONS_RESULTS_URL` and
149
123
  * `ACTIONS_RUNTIME_TOKEN`; fails with `BlobStoreError` (`misconfigured`) when
150
124
  * either is absent.
151
125
  */
152
- static layer = Layer.effect(BlobStore, make(azure));
126
+ static layer = Layer.effect(BlobStore, make());
153
127
  /**
154
128
  * The backend, over a supplied transport.
155
129
  *
156
130
  * @remarks
157
131
  * The Twirp protocol — the RPC sequence, the conflict handling, the retry
158
132
  * policy, the framing — is what this package owns and what a test needs to
159
- * exercise; the Azure client is a pre-signed `PUT` that owns none of it. This
133
+ * exercise; the blob transfer is a pre-signed `PUT` that owns none of it. This
160
134
  * is also the seam an integration test uses to point the same protocol at a
161
135
  * local blob endpoint.
162
136
  *
package/BlobStore.js CHANGED
@@ -1,10 +1,10 @@
1
+ import { HttpRedaction, SigV4 } from "@effected/crypto";
2
+ import { Context, DateTime, Effect, Layer, Option, Schema } from "effect";
3
+ import { Digest, Mac } from "effect/crypto";
4
+ import { HttpClient, HttpClientRequest } from "effect/http";
1
5
  import { BlobEnvelope } from "./BlobEnvelope.js";
2
6
  import { unstubbed } from "./internal/unstubbed.js";
3
7
  import { Secret } from "./Secret.js";
4
- import { Context, DateTime, Effect, Layer, Option, Schema } from "effect";
5
- import { HttpClient, HttpClientRequest } from "effect/http";
6
- import { HttpRedaction, SigV4 } from "@effected/crypto";
7
- import { Digest, Mac } from "effect/crypto";
8
8
 
9
9
  // src/BlobStore.ts
10
10
  /**
package/CacheKey.js CHANGED
@@ -1,7 +1,7 @@
1
- import { sha256, sha256Hex } from "./internal/digest.js";
2
- import { Effect, FileSystem, Option, Path, Schema } from "effect";
3
1
  import { GlobSet } from "@effected/glob";
4
2
  import { descend } from "@effected/walker";
3
+ import { Effect, FileSystem, Option, Path, Schema } from "effect";
4
+ import { sha256, sha256Hex } from "./internal/digest.js";
5
5
 
6
6
  // src/CacheKey.ts
7
7
  /**
package/CheckDocument.js CHANGED
@@ -1,7 +1,7 @@
1
+ import { Clock, Context, Duration, Effect, Latch, Layer, Ref, Schema, Semaphore } from "effect";
1
2
  import { CheckState } from "./CheckState.js";
2
3
  import { unstubbed } from "./internal/unstubbed.js";
3
4
  import { ManagedDocument } from "./ManagedDocument.js";
4
- import { Clock, Context, Duration, Effect, Latch, Layer, Ref, Schema, Semaphore } from "effect";
5
5
 
6
6
  // src/CheckDocument.ts
7
7
  /**
package/Checkout.js ADDED
@@ -0,0 +1,361 @@
1
+ import { Git } from "@effected/git";
2
+ import { Effect, Option, Schema } from "effect";
3
+ import { ActionOutputs } from "./ActionOutputs.js";
4
+ import { ActionState } from "./ActionState.js";
5
+ import { CredentialRecord, remove } from "./internal/checkout/credentials.js";
6
+ import { declarations, readInputs } from "./internal/checkout/inputs.js";
7
+ import { getSource } from "./internal/checkout/source.js";
8
+
9
+ // src/Checkout.ts
10
+ const Sha = Schema.String;
11
+ /**
12
+ * What to check out: a tagged union naming the ref the working tree lands on.
13
+ *
14
+ * @remarks
15
+ * `Event` is the workflow's own `GITHUB_REF` at `GITHUB_SHA`; `Default` is the
16
+ * repository's default branch. `Ref` takes a raw ref exactly as the `ref` input
17
+ * of the stock checkout action does. Every member that names something movable
18
+ * may pin it with `commit`.
19
+ *
20
+ * @public
21
+ */
22
+ const CheckoutRef = Schema.TaggedUnion({
23
+ Event: {},
24
+ Default: {},
25
+ Branch: {
26
+ name: Schema.String,
27
+ commit: Schema.optionalKey(Sha)
28
+ },
29
+ Tag: {
30
+ name: Schema.String,
31
+ commit: Schema.optionalKey(Sha)
32
+ },
33
+ Commit: { sha: Sha },
34
+ PullRequest: {
35
+ number: Schema.Number,
36
+ kind: Schema.Literals(["merge", "head"]),
37
+ commit: Schema.optionalKey(Sha)
38
+ },
39
+ Ref: {
40
+ ref: Schema.String,
41
+ commit: Schema.optionalKey(Sha)
42
+ }
43
+ });
44
+ /**
45
+ * How a checkout authenticates: a token, or an SSH key.
46
+ *
47
+ * @remarks
48
+ * `Ssh` defaults `strict` to `true` and `user` to `"git"`. Its optional `token`
49
+ * still serves the API calls, as the stock checkout's does. Every secret is a
50
+ * `Redacted<string>`.
51
+ *
52
+ * @public
53
+ */
54
+ const CheckoutAuth = Schema.TaggedUnion({
55
+ Token: { token: Schema.Redacted(Schema.String) },
56
+ Ssh: {
57
+ key: Schema.Redacted(Schema.String),
58
+ knownHosts: Schema.optionalKey(Schema.String),
59
+ strict: Schema.optionalKey(Schema.Boolean),
60
+ user: Schema.optionalKey(Schema.String),
61
+ token: Schema.optionalKey(Schema.Redacted(Schema.String))
62
+ }
63
+ });
64
+ /**
65
+ * What a checkout resolved to.
66
+ *
67
+ * @remarks
68
+ * `ref` is the resolved ref, as the `ref` output of the stock checkout action
69
+ * is: `""` for a bare commit.
70
+ *
71
+ * @public
72
+ */
73
+ var CheckoutResult = class extends Schema.Class("CheckoutResult")({
74
+ /** The resolved ref, or `""` for a bare commit. */
75
+ ref: Schema.String,
76
+ /** The commit now checked out. */
77
+ commit: Schema.String,
78
+ /** The directory checked out into. */
79
+ path: Schema.String,
80
+ /** The repository checked out. */
81
+ repository: Schema.Struct({
82
+ owner: Schema.String,
83
+ name: Schema.String
84
+ })
85
+ }) {};
86
+ /**
87
+ * Raised when the runner's git is older than the floor.
88
+ *
89
+ * @public
90
+ */
91
+ var CheckoutGitTooOldError = class extends Schema.TaggedError()("CheckoutGitTooOldError", {
92
+ /** The git version found. */
93
+ found: Schema.String,
94
+ /** The oldest git version supported. */
95
+ required: Schema.String
96
+ }) {
97
+ get message() {
98
+ return `git ${this.found} is older than the ${this.required} a checkout requires`;
99
+ }
100
+ };
101
+ /**
102
+ * Raised when a privileged event would check out fork pull request code.
103
+ *
104
+ * @public
105
+ */
106
+ var CheckoutUnsafePullRequestError = class extends Schema.TaggedError()("CheckoutUnsafePullRequestError", {
107
+ /** The triggering event, such as `pull_request_target`. */
108
+ event: Schema.String,
109
+ /** The repository being checked out. */
110
+ repository: Schema.String,
111
+ /** The ref being checked out. */
112
+ ref: Schema.String
113
+ }) {
114
+ get message() {
115
+ return `Refusing to check out fork pull request code from a '${this.event}' workflow. This workflow runs with the base repository's GITHUB_TOKEN, secrets, default-branch cache scope, and runner access. Fetching and executing a fork's code in that trusted context commonly leads to "pwn request" vulnerabilities. To opt in, review the risks at https://gh.io/securely-using-pull_request_target and set 'allow-unsafe-pr-checkout: true' on the checkout.`;
116
+ }
117
+ };
118
+ /**
119
+ * Raised when the requested ref does not exist on the remote.
120
+ *
121
+ * @remarks
122
+ * For a `Default` checkout `ref` is the default branch it resolved to, such as
123
+ * `refs/heads/main`, never `""`.
124
+ *
125
+ * @public
126
+ */
127
+ var CheckoutRefNotFoundError = class extends Schema.TaggedError()("CheckoutRefNotFoundError", {
128
+ /** The ref that was not found, after default-branch resolution. */
129
+ ref: Schema.String }) {
130
+ get message() {
131
+ return `The ref "${this.ref}" was not found on the remote`;
132
+ }
133
+ };
134
+ /**
135
+ * Raised when a ref resolved to a different commit than the one pinned.
136
+ *
137
+ * @public
138
+ */
139
+ var CheckoutCommitMismatchError = class extends Schema.TaggedError()("CheckoutCommitMismatchError", {
140
+ /** The ref that was fetched, after default-branch resolution. */
141
+ ref: Schema.String,
142
+ /** The commit the caller pinned. */
143
+ expected: Schema.String
144
+ }) {
145
+ get message() {
146
+ return `The ref "${this.ref}" did not resolve to the pinned commit ${this.expected}`;
147
+ }
148
+ };
149
+ /**
150
+ * Raised when the credentials were refused.
151
+ *
152
+ * @public
153
+ */
154
+ var CheckoutAuthError = class extends Schema.TaggedError()("CheckoutAuthError", {
155
+ /** The repository being accessed. */
156
+ repository: Schema.String,
157
+ /** What went wrong, with no secret in it. */
158
+ detail: Schema.String
159
+ }) {
160
+ get message() {
161
+ return `Authentication to ${this.repository} failed: ${this.detail}`;
162
+ }
163
+ };
164
+ /**
165
+ * Raised when the target path escapes the workspace.
166
+ *
167
+ * @public
168
+ */
169
+ var CheckoutPathError = class extends Schema.TaggedError()("CheckoutPathError", {
170
+ /** The path requested. */
171
+ path: Schema.String,
172
+ /** The workspace it must stay within. */
173
+ workspace: Schema.String
174
+ }) {
175
+ get message() {
176
+ return `The checkout path "${this.path}" is outside the workspace "${this.workspace}"`;
177
+ }
178
+ };
179
+ /**
180
+ * Raised when the repository's default branch could not be determined.
181
+ *
182
+ * @public
183
+ */
184
+ var CheckoutDefaultBranchError = class extends Schema.TaggedError()("CheckoutDefaultBranchError", {
185
+ /** The repository whose default branch is unknown. */
186
+ repository: Schema.String,
187
+ /** Why: the API's or `ls-remote`'s failure, with no secret in it. */
188
+ detail: Schema.String
189
+ }) {
190
+ get message() {
191
+ return `Could not determine the default branch of ${this.repository}: ${this.detail}`;
192
+ }
193
+ };
194
+ /**
195
+ * Raised when a `Ref` that is not fully qualified is pinned with `commit`.
196
+ *
197
+ * @remarks
198
+ * An unqualified ref pinned to a commit fetches only the commit, and nothing
199
+ * then names the branch or tag to land on. Pin a branch or tag with `Branch`
200
+ * or `Tag`, or give `Ref` a full `refs/...` name.
201
+ *
202
+ * @public
203
+ */
204
+ var CheckoutUnqualifiedRefPinError = class extends Schema.TaggedError()("CheckoutUnqualifiedRefPinError", {
205
+ /** The unqualified ref that was pinned. */
206
+ ref: Schema.String }) {
207
+ get message() {
208
+ return `The ref "${this.ref}" is pinned to a commit but is not fully qualified: pin a branch or tag with Branch or Tag, or name it as refs/...`;
209
+ }
210
+ };
211
+ /**
212
+ * Raised when a second `"job"` checkout in one action saves its credentials
213
+ * under a state key another checkout of a different path already used.
214
+ *
215
+ * @remarks
216
+ * The runner keeps one value per state key, so the post entry's
217
+ * {@link Checkout.cleanup} would find only the later record and leave the
218
+ * earlier checkout's credentials behind. Give each `"job"` checkout its own
219
+ * `stateKey` and call `Checkout.cleanup({ stateKey })` for each.
220
+ *
221
+ * @public
222
+ */
223
+ var CheckoutStateKeyInUseError = class extends Schema.TaggedError()("CheckoutStateKeyInUseError", {
224
+ /** The state key already in use. */
225
+ stateKey: Schema.String,
226
+ /** The path whose credentials it already records. */
227
+ path: Schema.String
228
+ }) {
229
+ get message() {
230
+ return `The state key "${this.stateKey}" already records the credentials of the checkout at "${this.path}": give each "job" checkout its own stateKey`;
231
+ }
232
+ };
233
+ /**
234
+ * Raised when the GitHub server URL is not an absolute `http` or `https` URL.
235
+ *
236
+ * @remarks
237
+ * Checked once, before any git runs, for `serverUrl`, the `github-server-url`
238
+ * input {@link Checkout.fromInputs} reads, and the runner's `GITHUB_SERVER_URL`.
239
+ * A host with no scheme, such as `ghe.example.com`, is refused rather than
240
+ * given `https://`, as the stock checkout action refuses it.
241
+ *
242
+ * @public
243
+ */
244
+ var CheckoutServerUrlError = class extends Schema.TaggedError()("CheckoutServerUrlError", {
245
+ /** The server URL as given. */
246
+ serverUrl: Schema.String,
247
+ /** Why it was refused. */
248
+ detail: Schema.String
249
+ }) {
250
+ get message() {
251
+ return `The GitHub server URL "${this.serverUrl}" is not valid: ${this.detail}`;
252
+ }
253
+ };
254
+ /**
255
+ * Checks a repository out the way the stock checkout action does, on `@effected/git`.
256
+ *
257
+ * @public
258
+ */
259
+ var Checkout = class {
260
+ /**
261
+ * Checks a repository out, in the stock checkout action's order: version
262
+ * check, unsafe pull request guard, directory preparation, `init`, auth,
263
+ * default branch, one fetch, ref verification, LFS, sparse set, checkout,
264
+ * submodules.
265
+ *
266
+ * @remarks
267
+ * Requires git 2.39.0 or later and fails {@link CheckoutGitTooOldError}
268
+ * before any other git runs. Every secret is masked first.
269
+ *
270
+ * An existing repository of the same remote is reused (lock files removed,
271
+ * `HEAD` detached, local and conflicting remote-tracking branches deleted,
272
+ * and with `clean` a `clean -ffdx` and `reset --hard HEAD`); any other
273
+ * directory has its contents deleted. The fetch, the default branch lookup
274
+ * and the LFS fetch are retried, as the stock action retries them. Every git
275
+ * step runs under a 30 minute ceiling: a checkout after a partial-clone
276
+ * fetch, an LFS smudge or a clean of a big tree can take as long as a fetch.
277
+ *
278
+ * The credentials' lifetime is `options.credentials`: `"job"` saves what
279
+ * was written under `stateKey` before any fetch, for {@link Checkout.cleanup}
280
+ * in the post step, refusing a second `"job"` checkout of another path
281
+ * under a key already in use; `"action"` removes it when the enclosing `Scope`
282
+ * closes, on success, failure or interruption; `"none"` removes it before
283
+ * this returns. The temporary global config holding `safe.directory` is
284
+ * discarded when this returns, whatever the lifetime.
285
+ *
286
+ * The log is one phase, `Checkout <owner>/<name> @ <ref>`, with one step
287
+ * per phase of work; each step's detail is the git transcript. The
288
+ * repository's object format and default branch come from the GitHub API
289
+ * (the default branch from the remote's `HEAD` instead for an SSH key or a
290
+ * `remoteUrl`), as the stock action asks it: through a client built from the checkout's
291
+ * own token against its own server's API base (`<origin>/api/v3` for a GitHub
292
+ * Enterprise Server `serverUrl`). An ambient `GitHubClient` is used only when
293
+ * the checkout has no token, an `Ssh` auth without one. A failed default
294
+ * branch lookup is {@link CheckoutDefaultBranchError}, its `detail` the reason.
295
+ */
296
+ static checkout = (options) => getSource(options);
297
+ /**
298
+ * Runs the post-step cleanup of a `"job"` checkout: reads the record saved
299
+ * under `stateKey` and removes everything the checkout wrote.
300
+ *
301
+ * @remarks
302
+ * No saved record is a no-op. Removal covers the credentials file, the SSH
303
+ * files, `includeIf`, the extraheader, `core.sshCommand` and the submodules'
304
+ * `insteadOf`, with `safe.directory` handled for the repository as the stock
305
+ * post step does. It never fails: every failure, an unreadable record
306
+ * included, becomes a warning, so a post step cannot turn a green job red.
307
+ * It is uninterruptible, so a cancelled job cannot leave credentials behind.
308
+ */
309
+ static cleanup = (options) => Effect.uninterruptible(Effect.gen(function* () {
310
+ const state = yield* ActionState;
311
+ const git = yield* Git;
312
+ const record = yield* state.getOptional(options?.stateKey ?? "effected-checkout", CredentialRecord);
313
+ if (Option.isSome(record)) yield* remove(record.value, git);
314
+ })).pipe(Effect.catch((error) => Effect.logWarning(`Checkout cleanup failed: ${error.message}`)), Effect.catchDefect((defect) => Effect.logWarning(`Checkout cleanup failed: ${String(defect)}`)));
315
+ /**
316
+ * Reads {@link CheckoutOptions} from the action's inputs, on the stock
317
+ * checkout action's input surface, so an action can expose a
318
+ * checkout-compatible interface unchanged.
319
+ *
320
+ * @remarks
321
+ * Reads `repository`, `ref`, `token`, `ssh-key`, `ssh-known-hosts`,
322
+ * `ssh-strict`, `ssh-user`, `persist-credentials`, `path`, `clean`, `filter`,
323
+ * `sparse-checkout`, `sparse-checkout-cone-mode`, `fetch-depth`,
324
+ * `fetch-tags`, `show-progress` (read and ignored), `lfs`, `submodules`,
325
+ * `set-safe-directory`, `github-server-url` and `allow-unsafe-pr-checkout`,
326
+ * each as `<prefix><name>` when a prefix is given. `token` is required; a
327
+ * present `ssh-key` makes the auth `Ssh`, carrying the token for the API
328
+ * calls.
329
+ *
330
+ * `persist-credentials` true is `"job"` and false `"none"`; `fetch-depth` at
331
+ * or below zero, or not a number, is `"full"`; `submodules` is `recursive`,
332
+ * `true` or else false. Every boolean reads as the stock action reads it:
333
+ * true only for a case-insensitive `true`, false for any other value, and
334
+ * an absent or empty input takes the stock action's in-code default, which
335
+ * for `persist-credentials` is false, not the manifest's `true` (on a
336
+ * runner an unsupplied input arrives as the manifest default, so only an
337
+ * explicit empty value meets the in-code one). `ref` is trimmed of ASCII
338
+ * whitespace only, so a leading BOM or NBSP survives as part of a `Ref`:
339
+ * empty is `Event` for the workflow's own repository and `Default`
340
+ * otherwise, a bare 40 or 64 hex value is a `Commit`, anything else a `Ref`.
341
+ *
342
+ * The `path` is not validated here; {@link Checkout.checkout} refuses one
343
+ * that leaves the workspace.
344
+ */
345
+ static fromInputs = (options) => readInputs(options?.prefix ?? "");
346
+ /**
347
+ * Declares the action inputs {@link Checkout.fromInputs} reads, with the
348
+ * stock checkout action's descriptions and defaults, for an author to merge
349
+ * into `action.yml`.
350
+ */
351
+ static inputs = (options) => Object.fromEntries(declarations.map(([name, input]) => [`${options?.prefix ?? ""}${name}`, input]));
352
+ /** Publishes a {@link CheckoutResult}'s `ref` and `commit` as step outputs. */
353
+ static writeOutputs = (result, options) => Effect.gen(function* () {
354
+ const outputs = yield* ActionOutputs;
355
+ const prefix = options?.prefix ?? "";
356
+ yield* outputs.set(`${prefix}ref`, result.ref);
357
+ yield* outputs.set(`${prefix}commit`, result.commit);
358
+ });
359
+ };
360
+
361
+ export { Checkout, CheckoutAuth, CheckoutAuthError, CheckoutCommitMismatchError, CheckoutDefaultBranchError, CheckoutGitTooOldError, CheckoutPathError, CheckoutRef, CheckoutRefNotFoundError, CheckoutResult, CheckoutServerUrlError, CheckoutStateKeyInUseError, CheckoutUnqualifiedRefPinError, CheckoutUnsafePullRequestError };
@@ -1,10 +1,10 @@
1
- import { isErrno } from "./internal/fsProbe.js";
2
- import { unstubbed } from "./internal/unstubbed.js";
1
+ import { spawn } from "node:child_process";
2
+ import { closeSync, openSync } from "node:fs";
3
3
  import { Effect, Schedule, Schema } from "effect";
4
4
  import { HttpClient } from "effect/http";
5
5
  import { ChildProcessSpawner } from "effect/process";
6
- import { spawn } from "node:child_process";
7
- import { closeSync, openSync } from "node:fs";
6
+ import { isErrno } from "./internal/fsProbe.js";
7
+ import { unstubbed } from "./internal/unstubbed.js";
8
8
 
9
9
  // src/DetachedProcess.ts
10
10
  /**
package/DryRun.js CHANGED
@@ -1,5 +1,5 @@
1
- import { ActionInput } from "./ActionInput.js";
2
1
  import { Config, Context, Effect, Layer } from "effect";
2
+ import { ActionInput } from "./ActionInput.js";
3
3
 
4
4
  // src/DryRun.ts
5
5
  /** The input a workflow author sets to rehearse a run. */
package/GitHubMarkdown.js CHANGED
@@ -1,5 +1,5 @@
1
- import { Result, Schema, SchemaAST } from "effect";
2
1
  import { Code, Html, InlineCode, Link, List, ListItem, Markdown, Paragraph, Root, Table, TableCell, TableRow } from "@effected/markdown";
2
+ import { Result, Schema, SchemaAST } from "effect";
3
3
 
4
4
  // src/GitHubMarkdown.ts
5
5
  /**
package/GitHubToken.js CHANGED
@@ -1,7 +1,7 @@
1
+ import { GitHubApp, GitHubClient, InstallationToken, TokenPermissions } from "@effected/github";
2
+ import { DateTime, Duration, Effect, Exit, Layer, Option, Result, Schema } from "effect";
1
3
  import { ActionState } from "./ActionState.js";
2
4
  import { Secret } from "./Secret.js";
3
- import { DateTime, Duration, Effect, Exit, Layer, Option, Result, Schema } from "effect";
4
- import { GitHubApp, GitHubClient, InstallationToken, TokenPermissions } from "@effected/github";
5
5
 
6
6
  // src/GitHubToken.ts
7
7
  /**
@@ -1,5 +1,5 @@
1
- import { Effect, Option, Result, Schema } from "effect";
2
1
  import { CommentStyle, SectionDialect, SectionDocument, SectionId } from "@effected/templates";
2
+ import { Effect, Option, Result, Schema } from "effect";
3
3
 
4
4
  // src/ManagedDocument.ts
5
5
  /**
@@ -1,14 +1,14 @@
1
- import { ActionEnvironment } from "./ActionEnvironment.js";
2
- import { ActionOutputs } from "./ActionOutputs.js";
3
- import { unstubbed } from "./internal/unstubbed.js";
4
- import { Secret } from "./Secret.js";
5
- import { Context, Effect, Layer, Redacted, Schema } from "effect";
6
- import { HttpClient, HttpClientRequest } from "effect/http";
7
1
  import { HttpRedaction } from "@effected/crypto";
8
- import { Oidc } from "@effected/oidc";
9
2
  import { ActionsOidcClaimsFromWire } from "@effected/github";
3
+ import { Oidc } from "@effected/oidc";
4
+ import { Context, Effect, Layer, Redacted, Schema } from "effect";
10
5
  import * as Base64Url from "effect/encoding/Base64Url";
6
+ import { HttpClient, HttpClientRequest } from "effect/http";
11
7
  import * as HttpClientResponse from "effect/http/HttpClientResponse";
8
+ import { ActionEnvironment } from "./ActionEnvironment.js";
9
+ import { ActionOutputs } from "./ActionOutputs.js";
10
+ import { unstubbed } from "./internal/unstubbed.js";
11
+ import { Secret } from "./Secret.js";
12
12
 
13
13
  // src/OidcTokenIssuer.ts
14
14
  /**
@@ -1,3 +1,6 @@
1
+ import { CorepackIntegrityHash, DEFAULT_REGISTRY, PackageManagerPin, PackageManagerPinName } from "@effected/npm";
2
+ import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
3
+ import { ChildProcess, ChildProcessSpawner } from "effect/process";
1
4
  import { ActionEnvironment } from "./ActionEnvironment.js";
2
5
  import { digestFileHex } from "./internal/digest.js";
3
6
  import { typeAt } from "./internal/fsProbe.js";
@@ -6,9 +9,6 @@ import { isWindowsRunner, runnerArch } from "./internal/runner.js";
6
9
  import { cmdShim, gitBashShim, posixShim } from "./internal/shim.js";
7
10
  import { unstubbed } from "./internal/unstubbed.js";
8
11
  import { ToolInstaller } from "./ToolInstaller.js";
9
- import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
10
- import { ChildProcess, ChildProcessSpawner } from "effect/process";
11
- import { CorepackIntegrityHash, DEFAULT_REGISTRY, PackageManagerPin, PackageManagerPinName } from "@effected/npm";
12
12
 
13
13
  // src/PackageManagerInstaller.ts
14
14
  /**
package/README.md CHANGED
@@ -123,7 +123,7 @@ const program = Effect.gen(function* () {
123
123
 
124
124
  ## The runner's cache, artifacts and OIDC
125
125
 
126
- `ActionCache` and `Artifact` speak the Actions Twirp v2 protocol directly — no `@actions/cache` or `@actions/artifact` dependency, and both are excluded from `ActionRuntime.layer` on purpose, so a consumer that only sets an output never links `@azure/storage-blob`:
126
+ `ActionCache` and `Artifact` speak the Actions Twirp v2 protocol directly — no `@actions/cache` or `@actions/artifact` dependency, and both are excluded from `ActionRuntime.layer` on purpose, so a consumer that only sets an output never links the blob transport:
127
127
 
128
128
  ```ts
129
129
  import { ActionCache, CacheKey } from "@effected/github-actions";
@@ -297,11 +297,12 @@ const TestOutputs = ActionOutputs.layerTest({
297
297
  - `ActionManifest` — `action.yml` decoded (`read`, `decode`, `decodeResult`): inputs with defaults, outputs, branding and the node, composite or docker `runs` block. `runnerInputs` builds the input environment a real runner builds for a node or docker action (every declared input under its `INPUT_` variable, with the supplied value, its manifest default or `""`, plus any undeclared supplied name passed through as the runner does) as the baseline for input tests, and `diff` reports inputs and outputs the code and the manifest disagree on.
298
298
  - `ActionOutputs` — step outputs, JSON outputs, the job summary, exported variables, `PATH` additions, failure annotations and log masking.
299
299
  - `ActionState` / `ActionEnvironment` — persisted `pre`/`main`/`post` state, and the fiber-local `GITHUB_*`/`RUNNER_*` context read once from `process.env`.
300
- - `ActionLogger` — collapsible groups (nesting-aware: the runner cannot nest groups, so a group opened inside another writes a `▸ <name>` header line instead of a second group command), buffered step transcripts (`withBuffer({ onSuccess: "discard" })` drops a green step's transcript entirely, while a failure, defect or interruption still flushes it), `withStep(name, effect, options?)` for the same buffering plus one summary line on success and a `❌ <name>` header above the transcript on failure, `::notice::` annotations, and the `Logger` that renders every `Effect.log*` as a workflow command.
300
+ - `ActionLogger` — the step log: `phase` writes a bold heading, `step` holds its detail behind a quiet window and writes one result line (folded when it finishes in time, live past the window, never folded on failure), `ActionLogger.command` runs a child process into the step's detail, `recording()` records the log's structure for a test, plus raw collapsible `group`s (nesting-aware: the runner cannot nest groups, so a group opened inside another writes a `▸ <name>` header line), `::notice::` annotations, and the `Logger` that renders every `Effect.log*` as a workflow command.
301
+ - `Checkout` — `actions/checkout` on `@effected/git`: `checkout`, `cleanup` (the post entry's call for a job-lifetime credential), `fromInputs`, `inputs` and `writeOutputs`, with per-reason errors.
301
302
  - `DryRun` — the rehearsal guard every mutation goes through, driven by the `dry-run` input by default.
302
303
  - `Secret` — the one declassification seam between a `Redacted` value and a plain string, masking before it returns plaintext.
303
304
  - `GitHubToken` — the App-token lifecycle shaped like the `pre`/`main`/`post` workflow: mint, verify scopes, persist, read, revoke.
304
- - `ActionCache` / `Artifact` — the runner's cache and artifact protocols over Twirp v2, excluded from the default runtime so a consumer that skips them never links Azure.
305
+ - `ActionCache` / `Artifact` — the runner's cache and artifact protocols over Twirp v2, excluded from the default runtime so a consumer that skips them never links the blob transport.
305
306
  - `CacheKey` — cache keys and their restore-key ladder, `withNamespace(segment)` for a bust token or a shared-runner prefix, plus `hashFiles`/`matchingFiles`/`hashMatching` byte-compatible with `@actions/glob`.
306
307
  - `OidcTokenIssuer` — the runner's OIDC token service, with unverified claim decoding for provenance predicates, and a `recording(claims)` double that journals the audiences asked for.
307
308
  - `ActionsRegistryCredential` — `workload({ audience, prefix })` mints an identity token for a registry, masks the bare and the prefixed value, and returns `@effected/npm`'s publish-only `WorkloadCredential` for `PackagePublish.setupAuth`.
package/Secret.js CHANGED
@@ -1,5 +1,5 @@
1
- import { ActionOutputs } from "./ActionOutputs.js";
2
1
  import { Config, Effect, Redacted } from "effect";
2
+ import { ActionOutputs } from "./ActionOutputs.js";
3
3
 
4
4
  // src/Secret.ts
5
5
  /**
package/ToolInstaller.js CHANGED
@@ -1,13 +1,13 @@
1
+ import { HttpRedaction } from "@effected/crypto";
2
+ import { Context, Effect, FileSystem, Layer, Option, Path, Schedule, Schema, Stream } from "effect";
3
+ import { HttpClient } from "effect/http";
4
+ import { ChildProcessSpawner } from "effect/process";
1
5
  import { ActionEnvironment } from "./ActionEnvironment.js";
2
6
  import { tarExtractCommand, unzipCommand } from "./internal/archiveCommands.js";
3
7
  import { isErrno, typeAt } from "./internal/fsProbe.js";
4
8
  import { isWindowsRunner, runnerArch, toolCacheRoot } from "./internal/runner.js";
5
9
  import { spawnOnce } from "./internal/spawn.js";
6
10
  import { unstubbed } from "./internal/unstubbed.js";
7
- import { Context, Effect, FileSystem, Layer, Option, Path, Schedule, Schema, Stream } from "effect";
8
- import { HttpClient } from "effect/http";
9
- import { ChildProcessSpawner } from "effect/process";
10
- import { HttpRedaction } from "@effected/crypto";
11
11
 
12
12
  // src/ToolInstaller.ts
13
13
  /**