@effected/github-actions 0.26.0 → 0.28.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.
- package/ActionInput.js +68 -0
- package/ActionLogger.js +13 -4
- package/ActionManifest.js +450 -0
- package/ActionsRegistryCredential.js +1 -1
- package/OidcTokenIssuer.js +20 -3
- package/README.md +2 -1
- package/index.d.ts +498 -10
- package/index.js +3 -2
- package/package.json +10 -9
package/ActionInput.js
CHANGED
|
@@ -18,6 +18,8 @@ import { Config, ConfigProvider, Context, Effect, Schema, SchemaIssue } from "ef
|
|
|
18
18
|
* @internal
|
|
19
19
|
*/
|
|
20
20
|
const inputVariable = (name) => `INPUT_${name.replaceAll(" ", "_").toUpperCase()}`;
|
|
21
|
+
/** The prefix every runner input variable carries. */
|
|
22
|
+
const INPUT_PREFIX = "INPUT_";
|
|
21
23
|
/**
|
|
22
24
|
* A validation failure for an input that is present but unusable.
|
|
23
25
|
*
|
|
@@ -428,6 +430,72 @@ var ActionInput = class ActionInput {
|
|
|
428
430
|
return ConfigProvider.layer(ActionInput.provider(env));
|
|
429
431
|
}
|
|
430
432
|
/**
|
|
433
|
+
* {@link ActionInput.provider} over `env`, journaling every input the
|
|
434
|
+
* program reads.
|
|
435
|
+
*
|
|
436
|
+
* @remarks
|
|
437
|
+
* The test-side half of the manifest sync check: run the code under
|
|
438
|
+
* `layer`, read `names`, and hand them to `ActionManifest.diff` as the
|
|
439
|
+
* inputs the code actually reads. Values resolve exactly as under
|
|
440
|
+
* `ActionInput.provider(env)` — the recorder wraps that provider's lookup
|
|
441
|
+
* and changes nothing about what it answers — so the recording run can use
|
|
442
|
+
* the runner-shaped environment `ActionManifest.runnerInputs` builds.
|
|
443
|
+
*
|
|
444
|
+
* A read is journaled when its lookup runs, not when a `Config` is merely
|
|
445
|
+
* described, and whether or not the input has a value: an unsupplied input
|
|
446
|
+
* the code falls back from is still an input the code reads.
|
|
447
|
+
*
|
|
448
|
+
* What counts as an input read is a lookup of an `INPUT_` variable, which
|
|
449
|
+
* is what every accessor on this class performs. A **bare**
|
|
450
|
+
* `Config.String("dry-run")` is not journaled: from inside the provider it
|
|
451
|
+
* is indistinguishable from an ordinary environment read, and journaling
|
|
452
|
+
* every flat name would report `GITHUB_REPOSITORY` as an undeclared input.
|
|
453
|
+
* Reading inputs through the accessors is the rule anyway.
|
|
454
|
+
*
|
|
455
|
+
* Names come back in the runner-variable form, lowercased, so a declared
|
|
456
|
+
* `My Input` reads as `my_input`. `ActionManifest.diff` matches inputs by
|
|
457
|
+
* runner variable, under which the two are the same input.
|
|
458
|
+
*
|
|
459
|
+
* Each call journals into its own fresh set; bind the result once per test.
|
|
460
|
+
*
|
|
461
|
+
* @example
|
|
462
|
+
* ```ts
|
|
463
|
+
* import { assert, it } from "@effect/vitest";
|
|
464
|
+
* import { ActionInput, ActionManifest } from "@effected/github-actions";
|
|
465
|
+
* import { Effect } from "effect";
|
|
466
|
+
*
|
|
467
|
+
* declare const manifest: ActionManifest;
|
|
468
|
+
* declare const readInputs: Effect.Effect<unknown, unknown>;
|
|
469
|
+
*
|
|
470
|
+
* it.effect("the code reads exactly what action.yml declares", () =>
|
|
471
|
+
* Effect.gen(function* () {
|
|
472
|
+
* const recording = ActionInput.recording(ActionManifest.runnerInputs(manifest));
|
|
473
|
+
* yield* readInputs.pipe(Effect.provide(recording.layer));
|
|
474
|
+
* const diff = ActionManifest.diff(manifest, { inputs: yield* recording.names });
|
|
475
|
+
* assert.isTrue(diff.inSync, JSON.stringify(diff));
|
|
476
|
+
* }),
|
|
477
|
+
* );
|
|
478
|
+
* ```
|
|
479
|
+
*
|
|
480
|
+
* @param env - The environment the provider serves, as for
|
|
481
|
+
* {@link ActionInput.provider}. Defaults to an empty record, never
|
|
482
|
+
* `process.env`: a recorder is a test instrument.
|
|
483
|
+
*/
|
|
484
|
+
static recording(env = {}) {
|
|
485
|
+
const inner = ActionInput.provider(env);
|
|
486
|
+
const seen = /* @__PURE__ */ new Set();
|
|
487
|
+
const provider = ConfigProvider.make((path) => Effect.suspend(() => {
|
|
488
|
+
const variable = path.join("_").replaceAll(" ", "_").toUpperCase();
|
|
489
|
+
if (variable.startsWith(INPUT_PREFIX) && variable.length > 6) seen.add(variable.slice(6).toLowerCase());
|
|
490
|
+
return inner.load(path);
|
|
491
|
+
}));
|
|
492
|
+
return {
|
|
493
|
+
provider,
|
|
494
|
+
layer: ConfigProvider.layer(provider),
|
|
495
|
+
names: Effect.sync(() => [...seen])
|
|
496
|
+
};
|
|
497
|
+
}
|
|
498
|
+
/**
|
|
431
499
|
* Inputs-first resolution layered over an existing provider.
|
|
432
500
|
*
|
|
433
501
|
* @remarks
|
package/ActionLogger.js
CHANGED
|
@@ -98,7 +98,7 @@ const commandLogger = Logger.withConsoleLog(renderLogger);
|
|
|
98
98
|
*/
|
|
99
99
|
const ActiveBuffer = Context.Reference("@effected/github-actions/ActiveBuffer", { defaultValue: () => null });
|
|
100
100
|
/**
|
|
101
|
-
* How many
|
|
101
|
+
* How many log groups are open around the current fiber.
|
|
102
102
|
*
|
|
103
103
|
* @remarks
|
|
104
104
|
* The runner does not nest groups: a second `::group::` implicitly ends the
|
|
@@ -108,11 +108,18 @@ const ActiveBuffer = Context.Reference("@effected/github-actions/ActiveBuffer",
|
|
|
108
108
|
* `Context.Reference` is provided around the body, so it unwinds on every
|
|
109
109
|
* exit path with nothing to restore.
|
|
110
110
|
*
|
|
111
|
+
* Keyed by `WorkflowCommand.groupDepthKey`, the kit-wide key for this count,
|
|
112
|
+
* rather than a key of this package's own: Effect looks a reference up by its
|
|
113
|
+
* key, so `@effected/cli`'s `Render.context`, which builds its own reference
|
|
114
|
+
* from the same key, sees the depth this member provides, and a document it
|
|
115
|
+
* renders inside a group opens no second one.
|
|
116
|
+
*
|
|
111
117
|
* @internal
|
|
112
118
|
*/
|
|
113
|
-
const GroupDepth = Context.Reference(
|
|
119
|
+
const GroupDepth = Context.Reference(WorkflowCommand.groupDepthKey, { defaultValue: () => 0 });
|
|
114
120
|
/**
|
|
115
|
-
* The line a nested group writes in place of a second `::group
|
|
121
|
+
* The `▸ <name>` line a nested group writes in place of a second `::group::`,
|
|
122
|
+
* and the line {@link ActionLoggerShape.heading} writes.
|
|
116
123
|
*
|
|
117
124
|
* @remarks
|
|
118
125
|
* Line breaks collapse to spaces so the header stays one line — the
|
|
@@ -160,6 +167,7 @@ const make = Effect.gen(function* () {
|
|
|
160
167
|
const body = Effect.tapCause(Effect.provideService(effect, GroupDepth, depth + 1), () => flushActive);
|
|
161
168
|
return depth === 0 ? Effect.acquireUseRelease(Console.log(WorkflowCommand.group(name)), () => body, () => Console.log(WorkflowCommand.endGroup())) : Effect.andThen(Console.log(nestedHeader(name)), body);
|
|
162
169
|
}),
|
|
170
|
+
heading: (name, effect) => Effect.andThen(Console.log(nestedHeader(name)), effect),
|
|
163
171
|
withBuffer,
|
|
164
172
|
withStep: (name, effect, options) => withBuffer(name, Effect.tapCause(effect, () => Console.log(CommandNeutralizer.text(`❌ ${name}`))), { onSuccess: "discard" }).pipe(Effect.tap(() => Effect.logInfo(options?.summary ?? `✅ ${name}`))),
|
|
165
173
|
notice: (message, properties = {}) => Console.log(WorkflowCommand.notice(message, properties)),
|
|
@@ -226,12 +234,13 @@ var ActionLogger = class ActionLogger extends Context.Service()("@effected/githu
|
|
|
226
234
|
* **A recorded exception to the die-on-unstubbed rule**, alongside
|
|
227
235
|
* {@link ActionEnvironment.makeTest}. A logger that dies when a suite logs
|
|
228
236
|
* would make every double unusable, and silence is the honest default for a
|
|
229
|
-
* service whose whole job is output. Group and buffer wrappers pass their
|
|
237
|
+
* service whose whole job is output. Group, heading and buffer wrappers pass their
|
|
230
238
|
* effect through unchanged, so the double does not model group nesting:
|
|
231
239
|
* a test of nested-group output needs the live {@link ActionLogger.layer}.
|
|
232
240
|
*/
|
|
233
241
|
static makeTest = (overrides = {}) => ({
|
|
234
242
|
group: (_name, effect) => effect,
|
|
243
|
+
heading: (_name, effect) => effect,
|
|
235
244
|
withBuffer: (_label, effect) => effect,
|
|
236
245
|
withStep: (_name, effect) => effect,
|
|
237
246
|
notice: () => Effect.void,
|
|
@@ -0,0 +1,450 @@
|
|
|
1
|
+
import { inputVariable } from "./ActionInput.js";
|
|
2
|
+
import { Effect, FileSystem, Result, Schema, SchemaTransformation } from "effect";
|
|
3
|
+
import { Yaml } from "@effected/yaml";
|
|
4
|
+
|
|
5
|
+
// src/ActionManifest.ts
|
|
6
|
+
/**
|
|
7
|
+
* A resolved YAML scalar as text: `null` (a bare `key:`, `~`) is `""`, a
|
|
8
|
+
* non-finite number takes YAML's own spelling, and anything else is
|
|
9
|
+
* `String(value)`.
|
|
10
|
+
*/
|
|
11
|
+
const scalarText = (value) => {
|
|
12
|
+
if (value === null) return "";
|
|
13
|
+
if (typeof value === "number" && !Number.isFinite(value)) return Number.isNaN(value) ? ".nan" : value > 0 ? ".inf" : "-.inf";
|
|
14
|
+
return String(value);
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* A YAML scalar read as the text the runner publishes.
|
|
18
|
+
*
|
|
19
|
+
* @remarks
|
|
20
|
+
* YAML types an unquoted `default: false` as a boolean, `default: 3` as a
|
|
21
|
+
* number and a bare `default:` as null, but the runner hands every value to
|
|
22
|
+
* the action as text. Accepting every scalar and stringifying keeps a
|
|
23
|
+
* manifest author's quoting choice from changing what a test believes the
|
|
24
|
+
* runner sends, and keeps a manifest that published actions really carry
|
|
25
|
+
* from failing to decode.
|
|
26
|
+
*
|
|
27
|
+
* A bare value or `~` reads as `""`, which is what the runner publishes for
|
|
28
|
+
* it. `.inf`, `-.inf` and `.nan` read as those spellings. Any other number is
|
|
29
|
+
* stringified by JavaScript (`String(value)`), so one whose YAML spelling is
|
|
30
|
+
* not its canonical form (`1.0`, `0x10`, `.Inf`) reads as `"1"`, `"16"` or
|
|
31
|
+
* `".inf"` here — quote such a value in `action.yml` to pin its exact text.
|
|
32
|
+
*/
|
|
33
|
+
const ScalarText = Schema.Union([
|
|
34
|
+
Schema.String,
|
|
35
|
+
Schema.Number,
|
|
36
|
+
Schema.BigInt,
|
|
37
|
+
Schema.Boolean,
|
|
38
|
+
Schema.Null
|
|
39
|
+
]).pipe(Schema.decodeTo(Schema.String, SchemaTransformation.transform({
|
|
40
|
+
decode: scalarText,
|
|
41
|
+
encode: (text) => text
|
|
42
|
+
})));
|
|
43
|
+
/**
|
|
44
|
+
* A YAML boolean, or the strings `"true"` and `"false"`, which published
|
|
45
|
+
* manifests quote as often as not.
|
|
46
|
+
*/
|
|
47
|
+
const LenientBoolean = Schema.Union([Schema.Boolean, Schema.Literals(["true", "false"])]).pipe(Schema.decodeTo(Schema.Boolean, SchemaTransformation.transform({
|
|
48
|
+
decode: (value) => value === true || value === "true",
|
|
49
|
+
encode: (value) => value
|
|
50
|
+
})));
|
|
51
|
+
/**
|
|
52
|
+
* One input an `action.yml` declares under `inputs:`.
|
|
53
|
+
*
|
|
54
|
+
* @remarks
|
|
55
|
+
* `default` is the text the runner publishes when a workflow omits the input;
|
|
56
|
+
* when the manifest declares none, the runner publishes `""` instead — see
|
|
57
|
+
* {@link ActionManifest.runnerInputs}. A `default` written as a workflow
|
|
58
|
+
* expression (`${{ github.token }}`) is evaluated by the runner, so here it is
|
|
59
|
+
* the unevaluated text: supply the evaluated value explicitly in a test.
|
|
60
|
+
*
|
|
61
|
+
* `required` is documentation only — the runner does not enforce it — and
|
|
62
|
+
* `description` is optional here because the runner does not require it
|
|
63
|
+
* either, even though the metadata reference lists it.
|
|
64
|
+
*
|
|
65
|
+
* @public
|
|
66
|
+
*/
|
|
67
|
+
var ActionManifestInput = class extends Schema.Class("ActionManifestInput")({
|
|
68
|
+
/** What the input is for. */
|
|
69
|
+
description: Schema.optionalKey(Schema.String),
|
|
70
|
+
/**
|
|
71
|
+
* Whether the manifest marks the input required (not enforced by the
|
|
72
|
+
* runner); the quoted strings `"true"` and `"false"` decode as booleans.
|
|
73
|
+
*/
|
|
74
|
+
required: Schema.optionalKey(LenientBoolean),
|
|
75
|
+
/**
|
|
76
|
+
* The text published when a workflow omits the input, stringified from any
|
|
77
|
+
* YAML scalar; a bare `default:` reads as `""`.
|
|
78
|
+
*/
|
|
79
|
+
default: Schema.optionalKey(ScalarText),
|
|
80
|
+
/** Set when the input is deprecated; the runner warns with this text when a workflow supplies it. */
|
|
81
|
+
deprecationMessage: Schema.optionalKey(Schema.String)
|
|
82
|
+
}) {};
|
|
83
|
+
/**
|
|
84
|
+
* One output an `action.yml` declares under `outputs:`.
|
|
85
|
+
*
|
|
86
|
+
* @remarks
|
|
87
|
+
* `value` is the expression a composite action maps the output from; a
|
|
88
|
+
* JavaScript or Docker action writes its outputs at runtime and declares none.
|
|
89
|
+
*
|
|
90
|
+
* @public
|
|
91
|
+
*/
|
|
92
|
+
var ActionManifestOutput = class extends Schema.Class("ActionManifestOutput")({
|
|
93
|
+
/** What the output carries. */
|
|
94
|
+
description: Schema.optionalKey(Schema.String),
|
|
95
|
+
/** The expression a composite action maps the output from. */
|
|
96
|
+
value: Schema.optionalKey(Schema.String)
|
|
97
|
+
}) {};
|
|
98
|
+
/**
|
|
99
|
+
* The `runs:` block of a JavaScript action — `using: node24` and its kin.
|
|
100
|
+
*
|
|
101
|
+
* @remarks
|
|
102
|
+
* `using` is any `node<major>` string rather than a closed list, so a manifest
|
|
103
|
+
* written for a runtime newer than this package still decodes. The YAML keys
|
|
104
|
+
* `pre-if` and `post-if` decode to `preIf` and `postIf`.
|
|
105
|
+
*
|
|
106
|
+
* @public
|
|
107
|
+
*/
|
|
108
|
+
var ActionManifestNodeRuns = class extends Schema.Class("ActionManifestNodeRuns")({
|
|
109
|
+
/** The Node runtime, such as `node24`. */
|
|
110
|
+
using: Schema.String.check(Schema.isPattern(/^node\d+$/)),
|
|
111
|
+
/** The entry point the `main` phase runs. */
|
|
112
|
+
main: Schema.String,
|
|
113
|
+
/** The entry point the `pre` phase runs, before any step of the job. */
|
|
114
|
+
pre: Schema.optionalKey(Schema.String),
|
|
115
|
+
/** The entry point the `post` phase runs, after every step of the job. */
|
|
116
|
+
post: Schema.optionalKey(Schema.String),
|
|
117
|
+
/** The condition gating the `pre` phase (`pre-if` in YAML). */
|
|
118
|
+
preIf: Schema.optionalKey(Schema.String),
|
|
119
|
+
/** The condition gating the `post` phase (`post-if` in YAML). */
|
|
120
|
+
postIf: Schema.optionalKey(Schema.String)
|
|
121
|
+
}) {};
|
|
122
|
+
/**
|
|
123
|
+
* The `runs:` block of a composite action.
|
|
124
|
+
*
|
|
125
|
+
* @remarks
|
|
126
|
+
* `steps` stays loosely typed — each step is a mapping — because describing
|
|
127
|
+
* the workflow-step grammar is out of this construct's scope.
|
|
128
|
+
*
|
|
129
|
+
* @public
|
|
130
|
+
*/
|
|
131
|
+
var ActionManifestCompositeRuns = class extends Schema.Class("ActionManifestCompositeRuns")({
|
|
132
|
+
/** Always `composite`. */
|
|
133
|
+
using: Schema.Literal("composite"),
|
|
134
|
+
/** The steps the action runs, each an unvalidated mapping. */
|
|
135
|
+
steps: Schema.Array(Schema.Record(Schema.String, Schema.Unknown))
|
|
136
|
+
}) {};
|
|
137
|
+
/**
|
|
138
|
+
* The `runs:` block of a Docker container action.
|
|
139
|
+
*
|
|
140
|
+
* @remarks
|
|
141
|
+
* The YAML keys `pre-entrypoint`, `post-entrypoint`, `pre-if` and `post-if`
|
|
142
|
+
* decode to camelCase. `args` entries and `env` values are stringified from
|
|
143
|
+
* any YAML scalar, as the runner passes them to the container as text.
|
|
144
|
+
*
|
|
145
|
+
* @public
|
|
146
|
+
*/
|
|
147
|
+
var ActionManifestDockerRuns = class extends Schema.Class("ActionManifestDockerRuns")({
|
|
148
|
+
/** Always `docker`. */
|
|
149
|
+
using: Schema.Literal("docker"),
|
|
150
|
+
/** A `Dockerfile` path or a `docker://` image reference. */
|
|
151
|
+
image: Schema.String,
|
|
152
|
+
/** Arguments passed to the container, each stringified from any YAML scalar. */
|
|
153
|
+
args: Schema.optionalKey(Schema.Array(ScalarText)),
|
|
154
|
+
/** Environment variables set in the container. */
|
|
155
|
+
env: Schema.optionalKey(Schema.Record(Schema.String, ScalarText)),
|
|
156
|
+
/** Overrides the image's `ENTRYPOINT`. */
|
|
157
|
+
entrypoint: Schema.optionalKey(Schema.String),
|
|
158
|
+
/** The entry point run before the `main` phase (`pre-entrypoint` in YAML). */
|
|
159
|
+
preEntrypoint: Schema.optionalKey(Schema.String),
|
|
160
|
+
/** The entry point run after the job's steps (`post-entrypoint` in YAML). */
|
|
161
|
+
postEntrypoint: Schema.optionalKey(Schema.String),
|
|
162
|
+
/** The condition gating the `pre` phase (`pre-if` in YAML). */
|
|
163
|
+
preIf: Schema.optionalKey(Schema.String),
|
|
164
|
+
/** The condition gating the `post` phase (`post-if` in YAML). */
|
|
165
|
+
postIf: Schema.optionalKey(Schema.String)
|
|
166
|
+
}) {};
|
|
167
|
+
/** The `runs:` union, with each shape's hyphenated YAML keys renamed. */
|
|
168
|
+
const Runs = Schema.Union([
|
|
169
|
+
ActionManifestNodeRuns.pipe(Schema.encodeKeys({
|
|
170
|
+
preIf: "pre-if",
|
|
171
|
+
postIf: "post-if"
|
|
172
|
+
})),
|
|
173
|
+
ActionManifestCompositeRuns,
|
|
174
|
+
ActionManifestDockerRuns.pipe(Schema.encodeKeys({
|
|
175
|
+
preEntrypoint: "pre-entrypoint",
|
|
176
|
+
postEntrypoint: "post-entrypoint",
|
|
177
|
+
preIf: "pre-if",
|
|
178
|
+
postIf: "post-if"
|
|
179
|
+
}))
|
|
180
|
+
]);
|
|
181
|
+
/**
|
|
182
|
+
* The `branding:` block a Marketplace listing reads.
|
|
183
|
+
*
|
|
184
|
+
* @public
|
|
185
|
+
*/
|
|
186
|
+
var ActionManifestBranding = class extends Schema.Class("ActionManifestBranding")({
|
|
187
|
+
/** A Feather icon name. */
|
|
188
|
+
icon: Schema.optionalKey(Schema.String),
|
|
189
|
+
/** The badge background colour. */
|
|
190
|
+
color: Schema.optionalKey(Schema.String)
|
|
191
|
+
}) {};
|
|
192
|
+
/**
|
|
193
|
+
* Raised when an `action.yml` cannot be read from the filesystem.
|
|
194
|
+
*
|
|
195
|
+
* @public
|
|
196
|
+
*/
|
|
197
|
+
var ActionManifestReadError = class extends Schema.TaggedError()("ActionManifestReadError", {
|
|
198
|
+
/** The path that was being read. */
|
|
199
|
+
path: Schema.String,
|
|
200
|
+
/** The underlying failure, preserved structurally. */
|
|
201
|
+
cause: Schema.Defect()
|
|
202
|
+
}) {
|
|
203
|
+
get message() {
|
|
204
|
+
return `Could not read the action manifest at "${this.path}"`;
|
|
205
|
+
}
|
|
206
|
+
};
|
|
207
|
+
/**
|
|
208
|
+
* Raised when an `action.yml` is not valid YAML, or is YAML that does not
|
|
209
|
+
* have the shape of an action manifest.
|
|
210
|
+
*
|
|
211
|
+
* @remarks
|
|
212
|
+
* One class for both, because the two share every field and no caller
|
|
213
|
+
* recovers from one but not the other: either way the manifest is broken.
|
|
214
|
+
* `detail` is the rendered parse or schema failure and `cause` the structured
|
|
215
|
+
* original.
|
|
216
|
+
*
|
|
217
|
+
* @public
|
|
218
|
+
*/
|
|
219
|
+
var ActionManifestDecodeError = class extends Schema.TaggedError()("ActionManifestDecodeError", {
|
|
220
|
+
/** The rendered parse or schema failure. */
|
|
221
|
+
detail: Schema.String,
|
|
222
|
+
/** The `YamlParseError` or `SchemaError` behind it. */
|
|
223
|
+
cause: Schema.Defect()
|
|
224
|
+
}) {
|
|
225
|
+
get message() {
|
|
226
|
+
return `Not a valid action manifest: ${this.detail}`;
|
|
227
|
+
}
|
|
228
|
+
};
|
|
229
|
+
/**
|
|
230
|
+
* Where an action's code and its `action.yml` disagree.
|
|
231
|
+
*
|
|
232
|
+
* @remarks
|
|
233
|
+
* Every list is in declaration or usage order, with duplicates removed. An
|
|
234
|
+
* empty diff — {@link ActionManifestDiff.inSync} — means the code reads every
|
|
235
|
+
* declared input, declares every input it reads, and the same for outputs.
|
|
236
|
+
*
|
|
237
|
+
* @public
|
|
238
|
+
*/
|
|
239
|
+
var ActionManifestDiff = class extends Schema.Class("ActionManifestDiff")({
|
|
240
|
+
/** Declared in `action.yml`, never read by the code. */
|
|
241
|
+
unreadInputs: Schema.Array(Schema.String),
|
|
242
|
+
/** Read by the code, not declared in `action.yml` — on a runner it arrives absent. */
|
|
243
|
+
undeclaredInputs: Schema.Array(Schema.String),
|
|
244
|
+
/** Declared in `action.yml`, never written by the code. */
|
|
245
|
+
unwrittenOutputs: Schema.Array(Schema.String),
|
|
246
|
+
/** Written by the code, not declared in `action.yml`. */
|
|
247
|
+
undeclaredOutputs: Schema.Array(Schema.String)
|
|
248
|
+
}) {
|
|
249
|
+
/** True when the code and the manifest agree on every name. */
|
|
250
|
+
get inSync() {
|
|
251
|
+
return this.unreadInputs.length === 0 && this.undeclaredInputs.length === 0 && this.unwrittenOutputs.length === 0 && this.undeclaredOutputs.length === 0;
|
|
252
|
+
}
|
|
253
|
+
};
|
|
254
|
+
/** The names in `names` whose key is absent from `keys`, deduplicated, in order. */
|
|
255
|
+
const missingFrom = (names, keys, key) => {
|
|
256
|
+
const seen = /* @__PURE__ */ new Set();
|
|
257
|
+
const missing = [];
|
|
258
|
+
for (const name of names) {
|
|
259
|
+
const k = key(name);
|
|
260
|
+
if (!seen.has(k) && !keys.has(k)) missing.push(name);
|
|
261
|
+
seen.add(k);
|
|
262
|
+
}
|
|
263
|
+
return missing;
|
|
264
|
+
};
|
|
265
|
+
/** The identity key, for outputs. */
|
|
266
|
+
const verbatim = (name) => name;
|
|
267
|
+
/**
|
|
268
|
+
* A decoded `action.yml`: the action's metadata, its declared inputs and
|
|
269
|
+
* outputs, and the `runs:` block naming how it executes.
|
|
270
|
+
*
|
|
271
|
+
* @remarks
|
|
272
|
+
* `action.yml` is the single source of truth for an action's input names and
|
|
273
|
+
* defaults, and the code mirrors both. This construct makes the mirror
|
|
274
|
+
* testable: {@link ActionManifest.runnerInputs} builds the input environment a
|
|
275
|
+
* real runner builds from the manifest, and {@link ActionManifest.diff} reports
|
|
276
|
+
* where the code's reads and writes disagree with what the manifest declares.
|
|
277
|
+
*
|
|
278
|
+
* `inputs` and `outputs` are keyed by name, in declaration order. Keys this
|
|
279
|
+
* construct does not describe are ignored, so a manifest carrying a newer
|
|
280
|
+
* metadata key still decodes.
|
|
281
|
+
*
|
|
282
|
+
* @example
|
|
283
|
+
* ```ts
|
|
284
|
+
* import { ActionInput, ActionManifest } from "@effected/github-actions";
|
|
285
|
+
* import { Effect } from "effect";
|
|
286
|
+
*
|
|
287
|
+
* const program = Effect.gen(function* () {
|
|
288
|
+
* const manifest = yield* ActionManifest.read("action.yml");
|
|
289
|
+
* // Every declared input present, with its manifest default or "".
|
|
290
|
+
* const layer = ActionInput.layer(ActionManifest.runnerInputs(manifest, { "dry-run": "true" }));
|
|
291
|
+
* return layer;
|
|
292
|
+
* });
|
|
293
|
+
* ```
|
|
294
|
+
*
|
|
295
|
+
* @public
|
|
296
|
+
*/
|
|
297
|
+
var ActionManifest = class ActionManifest extends Schema.Class("ActionManifest")({
|
|
298
|
+
/** The action's display name. */
|
|
299
|
+
name: Schema.String,
|
|
300
|
+
/** What the action does. */
|
|
301
|
+
description: Schema.optionalKey(Schema.String),
|
|
302
|
+
/** Who wrote the action. */
|
|
303
|
+
author: Schema.optionalKey(Schema.String),
|
|
304
|
+
/** The declared inputs, keyed by name. */
|
|
305
|
+
inputs: Schema.optionalKey(Schema.Record(Schema.String, ActionManifestInput)),
|
|
306
|
+
/** The declared outputs, keyed by name. */
|
|
307
|
+
outputs: Schema.optionalKey(Schema.Record(Schema.String, ActionManifestOutput)),
|
|
308
|
+
/** How the action executes. */
|
|
309
|
+
runs: Runs,
|
|
310
|
+
/** The Marketplace badge. */
|
|
311
|
+
branding: Schema.optionalKey(ActionManifestBranding)
|
|
312
|
+
}) {
|
|
313
|
+
/**
|
|
314
|
+
* Decode `action.yml` text, synchronously.
|
|
315
|
+
*
|
|
316
|
+
* @remarks
|
|
317
|
+
* Fails with {@link ActionManifestDecodeError} when the text is not YAML or
|
|
318
|
+
* not an action manifest. This is the form for a test that wants the
|
|
319
|
+
* manifest without an effect; {@link ActionManifest.decode} is the same
|
|
320
|
+
* decode as an `Effect`.
|
|
321
|
+
*/
|
|
322
|
+
static decodeResult(source) {
|
|
323
|
+
return Result.flatMap(Result.mapError(Yaml.parseResult(source), (cause) => new ActionManifestDecodeError({
|
|
324
|
+
detail: cause.message,
|
|
325
|
+
cause
|
|
326
|
+
})), (value) => Result.mapError(decodeManifest(value), (cause) => new ActionManifestDecodeError({
|
|
327
|
+
detail: cause.message,
|
|
328
|
+
cause
|
|
329
|
+
})));
|
|
330
|
+
}
|
|
331
|
+
/**
|
|
332
|
+
* Decode `action.yml` text.
|
|
333
|
+
*
|
|
334
|
+
* @remarks
|
|
335
|
+
* Fails with {@link ActionManifestDecodeError} when the text is not YAML or
|
|
336
|
+
* not an action manifest.
|
|
337
|
+
*/
|
|
338
|
+
static decode = (source) => Effect.fromResult(ActionManifest.decodeResult(source));
|
|
339
|
+
/**
|
|
340
|
+
* Read and decode the `action.yml` at `path`.
|
|
341
|
+
*
|
|
342
|
+
* @remarks
|
|
343
|
+
* Reads through `FileSystem` in `R`, so a test provides `@effected/memfs`
|
|
344
|
+
* and production the platform filesystem. A read failure is
|
|
345
|
+
* {@link ActionManifestReadError}, carrying the path; a malformed manifest is
|
|
346
|
+
* {@link ActionManifestDecodeError}.
|
|
347
|
+
*/
|
|
348
|
+
static read = Effect.fn("ActionManifest.read")(function* (path) {
|
|
349
|
+
const source = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new ActionManifestReadError({
|
|
350
|
+
path,
|
|
351
|
+
cause
|
|
352
|
+
})));
|
|
353
|
+
return yield* ActionManifest.decode(source);
|
|
354
|
+
});
|
|
355
|
+
/**
|
|
356
|
+
* The input environment a real runner builds for this manifest.
|
|
357
|
+
*
|
|
358
|
+
* @remarks
|
|
359
|
+
* The runner publishes a variable for **every** declared input: the value
|
|
360
|
+
* the workflow supplied under `with:`, else the manifest `default`, else
|
|
361
|
+
* `""`. So "absent" is a state production never produces, and a test built
|
|
362
|
+
* on an empty `ActionInput.layer({})` exercises the code's
|
|
363
|
+
* `Config.withDefault` fallbacks rather than the manifest defaults a real
|
|
364
|
+
* run decodes. This record is the runner-shaped baseline instead.
|
|
365
|
+
*
|
|
366
|
+
* Keys are runner variables — `INPUT_` plus the name uppercased with spaces
|
|
367
|
+
* turned to underscores and every other character, dashes included, kept
|
|
368
|
+
* (`write-summary` → `INPUT_WRITE-SUMMARY`) — derived through
|
|
369
|
+
* `ActionInput.variable`, the same function every accessor reads through.
|
|
370
|
+
* So the record feeds `ActionInput.layer`, spreads into
|
|
371
|
+
* `ActionEnvironment.layerTest`'s overrides, or becomes a spawned
|
|
372
|
+
* process's environment unchanged.
|
|
373
|
+
*
|
|
374
|
+
* `supplied` is the workflow's `with:` block, keyed by input name, and is
|
|
375
|
+
* matched to the declared inputs **by runner variable**, the way
|
|
376
|
+
* {@link ActionManifest.diff} matches: `write summary`, `write_summary` and
|
|
377
|
+
* `WRITE_SUMMARY` all supply the input declared as `write_summary`. A
|
|
378
|
+
* supplied value wins even when it is `""`, as on a runner.
|
|
379
|
+
*
|
|
380
|
+
* A supplied name the manifest does not declare is **passed through** as
|
|
381
|
+
* one more `INPUT_` variable, because the runner publishes it too — it only
|
|
382
|
+
* warns. This never throws. To catch a typo in a test, compare the names
|
|
383
|
+
* with {@link ActionManifest.diff}, which reports an undeclared read; a
|
|
384
|
+
* typoed supplied name otherwise leaves the declared input on its default.
|
|
385
|
+
*
|
|
386
|
+
* **Composite actions receive no `INPUT_` environment.** The runner
|
|
387
|
+
* publishes these variables to node and docker actions only; a composite
|
|
388
|
+
* action reads its inputs through `inputs.<name>` expressions in its steps.
|
|
389
|
+
* This builder is for node and docker actions, and for a composite test
|
|
390
|
+
* that drives the inputs into its steps explicitly.
|
|
391
|
+
*
|
|
392
|
+
* @param manifest - The decoded manifest.
|
|
393
|
+
* @param supplied - The workflow's `with:` values, keyed by input name.
|
|
394
|
+
* @returns The runner's `INPUT_*` variables: one per declared input, then
|
|
395
|
+
* one per supplied name the manifest does not declare.
|
|
396
|
+
*/
|
|
397
|
+
static runnerInputs(manifest, supplied = {}) {
|
|
398
|
+
const byVariable = /* @__PURE__ */ new Map();
|
|
399
|
+
for (const [name, value] of Object.entries(supplied)) byVariable.set(inputVariable(name), value);
|
|
400
|
+
const env = {};
|
|
401
|
+
for (const [name, input] of Object.entries(manifest.inputs ?? {})) {
|
|
402
|
+
const variable = inputVariable(name);
|
|
403
|
+
env[variable] = byVariable.get(variable) ?? input.default ?? "";
|
|
404
|
+
byVariable.delete(variable);
|
|
405
|
+
}
|
|
406
|
+
for (const [variable, value] of byVariable) env[variable] = value;
|
|
407
|
+
return env;
|
|
408
|
+
}
|
|
409
|
+
/**
|
|
410
|
+
* Compare the names an action's code reads and writes against the names
|
|
411
|
+
* its manifest declares.
|
|
412
|
+
*
|
|
413
|
+
* @remarks
|
|
414
|
+
* Inputs are matched the way the runner connects them — by runner
|
|
415
|
+
* variable — so `write summary` in code and `write_summary` in the
|
|
416
|
+
* manifest are the same input, and so are names differing only in case.
|
|
417
|
+
* Outputs are matched verbatim. Omitting `usage.outputs` skips the output
|
|
418
|
+
* comparison, leaving both output lists empty; omitting `usage.inputs`
|
|
419
|
+
* compares against no reads, so every declared input reports unread.
|
|
420
|
+
*
|
|
421
|
+
* @example
|
|
422
|
+
* ```ts
|
|
423
|
+
* import { assert, it } from "@effect/vitest";
|
|
424
|
+
* import { ActionManifest } from "@effected/github-actions";
|
|
425
|
+
*
|
|
426
|
+
* declare const manifest: ActionManifest;
|
|
427
|
+
*
|
|
428
|
+
* it("action.yml and the code agree", () => {
|
|
429
|
+
* const diff = ActionManifest.diff(manifest, { inputs: ["name", "dry-run"], outputs: ["greeting"] });
|
|
430
|
+
* assert.isTrue(diff.inSync, JSON.stringify(diff));
|
|
431
|
+
* });
|
|
432
|
+
* ```
|
|
433
|
+
*/
|
|
434
|
+
static diff(manifest, usage) {
|
|
435
|
+
const declaredInputs = Object.keys(manifest.inputs ?? {});
|
|
436
|
+
const readInputs = [...usage.inputs ?? []];
|
|
437
|
+
const declaredOutputs = usage.outputs !== void 0 ? Object.keys(manifest.outputs ?? {}) : [];
|
|
438
|
+
const writtenOutputs = [...usage.outputs ?? []];
|
|
439
|
+
return new ActionManifestDiff({
|
|
440
|
+
unreadInputs: missingFrom(declaredInputs, new Set(readInputs.map(inputVariable)), inputVariable),
|
|
441
|
+
undeclaredInputs: missingFrom(readInputs, new Set(declaredInputs.map(inputVariable)), inputVariable),
|
|
442
|
+
unwrittenOutputs: missingFrom(declaredOutputs, new Set(writtenOutputs), verbatim),
|
|
443
|
+
undeclaredOutputs: missingFrom(writtenOutputs, new Set(declaredOutputs), verbatim)
|
|
444
|
+
});
|
|
445
|
+
}
|
|
446
|
+
};
|
|
447
|
+
/** The manifest decoder, derived once. */
|
|
448
|
+
const decodeManifest = Schema.decodeUnknownResult(ActionManifest);
|
|
449
|
+
|
|
450
|
+
export { ActionManifest, ActionManifestBranding, ActionManifestCompositeRuns, ActionManifestDecodeError, ActionManifestDiff, ActionManifestDockerRuns, ActionManifestInput, ActionManifestNodeRuns, ActionManifestOutput, ActionManifestReadError };
|
package/OidcTokenIssuer.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { ActionEnvironment } from "./ActionEnvironment.js";
|
|
2
2
|
import { unstubbed } from "./internal/unstubbed.js";
|
|
3
|
+
import { ActionOutputs } from "./ActionOutputs.js";
|
|
4
|
+
import { Secret } from "./Secret.js";
|
|
3
5
|
import { Context, Effect, Layer, Redacted, Schema } from "effect";
|
|
4
6
|
import { HttpClient, HttpClientRequest } from "effect/http";
|
|
5
7
|
import { Oidc } from "@effected/oidc";
|
|
@@ -81,12 +83,13 @@ const unsignedJwt = (header, payload) => {
|
|
|
81
83
|
const make = Effect.gen(function* () {
|
|
82
84
|
const env = yield* ActionEnvironment;
|
|
83
85
|
const http = yield* HttpClient.HttpClient;
|
|
86
|
+
const outputs = yield* ActionOutputs;
|
|
84
87
|
const required = (name) => env.get(name).pipe(Effect.mapError(() => new OidcTokenError({
|
|
85
88
|
reason: "unavailable",
|
|
86
89
|
detail: name
|
|
87
90
|
})));
|
|
88
91
|
/**
|
|
89
|
-
* The raw JWT, before it is wrapped.
|
|
92
|
+
* The raw JWT, masked, before it is wrapped.
|
|
90
93
|
*
|
|
91
94
|
* @remarks
|
|
92
95
|
* `claims` reads this rather than unwrapping what `token` returns, so
|
|
@@ -94,6 +97,11 @@ const make = Effect.gen(function* () {
|
|
|
94
97
|
* declassification invariant is that `Secret.ts` is the only place a secret
|
|
95
98
|
* becomes a string, and a wrap-then-immediately-unwrap here would be a
|
|
96
99
|
* genuine exception to it rather than a cosmetic one.
|
|
100
|
+
*
|
|
101
|
+
* This is the one place every issued token passes, so it is where the token
|
|
102
|
+
* is registered with the runner's log filter: `token` and `claims` both get
|
|
103
|
+
* it, once per token, before anything downstream can decode, fail on or
|
|
104
|
+
* declassify it. The `ActionOutputs` is the one the layer was built with.
|
|
97
105
|
*/
|
|
98
106
|
const issue = Effect.fn("OidcTokenIssuer.token")(function* (audience) {
|
|
99
107
|
const bearer = yield* required(REQUEST_TOKEN);
|
|
@@ -107,10 +115,12 @@ const make = Effect.gen(function* () {
|
|
|
107
115
|
reason: "requestFailed",
|
|
108
116
|
status: response.status
|
|
109
117
|
}));
|
|
110
|
-
|
|
118
|
+
const envelope = yield* HttpClientResponse.schemaBodyJson(TokenEnvelope)(response).pipe(Effect.mapError((cause) => new OidcTokenError({
|
|
111
119
|
reason: "malformedResponse",
|
|
112
120
|
cause
|
|
113
|
-
})))
|
|
121
|
+
})));
|
|
122
|
+
yield* Secret.mask(Redacted.make(envelope.value)).pipe(Effect.provideService(ActionOutputs, outputs));
|
|
123
|
+
return envelope.value;
|
|
114
124
|
});
|
|
115
125
|
return {
|
|
116
126
|
token: (audience) => Effect.map(issue(audience), Redacted.make),
|
|
@@ -150,6 +160,13 @@ var OidcTokenIssuer = class OidcTokenIssuer extends Context.Service()("@effected
|
|
|
150
160
|
* @remarks
|
|
151
161
|
* Fails with {@link OidcTokenError} (`unavailable`) at use when the workflow
|
|
152
162
|
* lacks `permissions: id-token: write`.
|
|
163
|
+
*
|
|
164
|
+
* Requires {@link ActionOutputs} because every token it issues is masked
|
|
165
|
+
* through it at issuance (see {@link OidcTokenIssuerShape.token}). Under
|
|
166
|
+
* `ActionRuntime.layer` that is already at hand; a worker that composes
|
|
167
|
+
* `ActionOutputs.layerDetached` gets an issuer whose mask is the documented
|
|
168
|
+
* no-op, which is the right thing there and no substitute for minting in
|
|
169
|
+
* the parent.
|
|
153
170
|
*/
|
|
154
171
|
static layer = Layer.effect(this, make);
|
|
155
172
|
/**
|
package/README.md
CHANGED
|
@@ -293,7 +293,8 @@ const TestOutputs = ActionOutputs.layerTest({
|
|
|
293
293
|
## Features
|
|
294
294
|
|
|
295
295
|
- `Action.run` / `ActionRuntime.layer` — the entry point and default runtime: environment, logger, outputs, state, the Node platform and an `HttpClient`.
|
|
296
|
-
- `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default. `pairs` always rejects an empty key (`=value`, whose damage lands far from the typo) and takes `requireValue` to reject an empty value too.
|
|
296
|
+
- `ActionInput` — typed input accessors (`string`, `boolean`, `integer`, `redacted`, `lines`, `list`, `pairs`, `schema`) sharing one absence rule, plus the `INPUT_`-aware `ConfigProvider` `Action.run` installs by default. `pairs` always rejects an empty key (`=value`, whose damage lands far from the typo) and takes `requireValue` to reject an empty value too. `ActionInput.recording(env)` journals which inputs a program reads, for `ActionManifest.diff`.
|
|
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.
|
|
297
298
|
- `ActionOutputs` — step outputs, JSON outputs, the job summary, exported variables, `PATH` additions, failure annotations and log masking.
|
|
298
299
|
- `ActionState` / `ActionEnvironment` — persisted `pre`/`main`/`post` state, and the fiber-local `GITHUB_*`/`RUNNER_*` context read once from `process.env`.
|
|
299
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.
|
package/index.d.ts
CHANGED
|
@@ -293,8 +293,8 @@ interface WithStepOptions {
|
|
|
293
293
|
readonly summary?: string;
|
|
294
294
|
}
|
|
295
295
|
/**
|
|
296
|
-
* The members of the {@link ActionLogger} service: log groups
|
|
297
|
-
* notices and source annotations.
|
|
296
|
+
* The members of the {@link ActionLogger} service: log groups and headings,
|
|
297
|
+
* buffered steps, notices and source annotations.
|
|
298
298
|
*
|
|
299
299
|
* @public
|
|
300
300
|
*/
|
|
@@ -323,15 +323,40 @@ interface ActionLoggerShape {
|
|
|
323
323
|
* 2. **A fiber forked inside a group keeps the depth it was forked at.** A
|
|
324
324
|
* `forkChild` joined inside the group nests correctly; a detached fiber
|
|
325
325
|
* that outlives the group still writes headers rather than a group.
|
|
326
|
-
* 3. **Only
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
326
|
+
* 3. **Only a writer that reads the shared depth is counted.** The depth
|
|
327
|
+
* lives in the fiber-local keyed by `WorkflowCommand.groupDepthKey`
|
|
328
|
+
* (from `@effected/github-commands`), which `@effected/cli` reads too:
|
|
329
|
+
* `Render.context` built inside a group carries it as
|
|
330
|
+
* `RenderContext.groupDepth`, so `Doc.print` and `Render.githubLog`
|
|
331
|
+
* render a top-level collapsible as plain text there rather than as a
|
|
332
|
+
* second group. A raw `WorkflowCommand.group(...)`, or a consumer's
|
|
333
|
+
* own wrapper that does not read the key, opens a group this member
|
|
334
|
+
* cannot see, and a group opened inside one still nests at the runner.
|
|
331
335
|
* 4. **The test doubles do not model nesting.** `makeTest`, `layerTest` and
|
|
332
336
|
* `layerSilent` pass the effect through unchanged.
|
|
333
337
|
*/
|
|
334
338
|
readonly group: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
|
|
339
|
+
/**
|
|
340
|
+
* Run an effect under a `▸ <name>` header line, without opening a group.
|
|
341
|
+
*
|
|
342
|
+
* @remarks
|
|
343
|
+
* The phase-level banner: the same one-line, neutralized header a nested
|
|
344
|
+
* {@link ActionLoggerShape.group} writes, then the body, with no
|
|
345
|
+
* `::group::` and no change to the depth. So the groups inside it stay
|
|
346
|
+
* top level and each renders as its own collapsible section in the runner
|
|
347
|
+
* log, which a `group` wrapper cannot give them: the runner does not nest
|
|
348
|
+
* groups, and a wrapper that opened one would swallow every inner group
|
|
349
|
+
* into a header line. Reach for this when a phase encloses groups, and for
|
|
350
|
+
* `group` when it encloses only lines.
|
|
351
|
+
*
|
|
352
|
+
* The header goes out through `Console`, like a group command, so it is
|
|
353
|
+
* never captured into, or discarded with, an enclosing `withBuffer` or
|
|
354
|
+
* `withStep` transcript. Nothing is written when the body ends, and a
|
|
355
|
+
* failure flushes no buffer here: the groups inside do that for their own
|
|
356
|
+
* sections. Called inside an open group it is simply a header line in that
|
|
357
|
+
* group. The test doubles pass the body through unchanged.
|
|
358
|
+
*/
|
|
359
|
+
readonly heading: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
|
|
335
360
|
/**
|
|
336
361
|
* Run an effect with its verbose output captured and replayed on exit.
|
|
337
362
|
*
|
|
@@ -466,7 +491,7 @@ export declare class ActionLogger extends ActionLogger_base {
|
|
|
466
491
|
* **A recorded exception to the die-on-unstubbed rule**, alongside
|
|
467
492
|
* {@link ActionEnvironment.makeTest}. A logger that dies when a suite logs
|
|
468
493
|
* would make every double unusable, and silence is the honest default for a
|
|
469
|
-
* service whose whole job is output. Group and buffer wrappers pass their
|
|
494
|
+
* service whose whole job is output. Group, heading and buffer wrappers pass their
|
|
470
495
|
* effect through unchanged, so the double does not model group nesting:
|
|
471
496
|
* a test of nested-group output needs the live {@link ActionLogger.layer}.
|
|
472
497
|
*/
|
|
@@ -1568,6 +1593,24 @@ export declare class ActionCache extends ActionCache_base {
|
|
|
1568
1593
|
/** {@link ActionCache.makeTest} behind `Layer.succeed`. */
|
|
1569
1594
|
static readonly layerTest: (overrides?: Partial<ActionCacheShape>) => Layer.Layer<ActionCache>;
|
|
1570
1595
|
}
|
|
1596
|
+
/**
|
|
1597
|
+
* A provider that journals which inputs a program reads — see
|
|
1598
|
+
* {@link ActionInput.recording}.
|
|
1599
|
+
*
|
|
1600
|
+
* @public
|
|
1601
|
+
*/
|
|
1602
|
+
interface ActionInputRecording {
|
|
1603
|
+
/** The recording provider, for composing by hand. */
|
|
1604
|
+
readonly provider: ConfigProvider.ConfigProvider;
|
|
1605
|
+
/** {@link ActionInputRecording.provider} installed as a layer. */
|
|
1606
|
+
readonly layer: Layer.Layer<never>;
|
|
1607
|
+
/**
|
|
1608
|
+
* The input names read so far, in first-read order, without duplicates —
|
|
1609
|
+
* each the runner variable with its `INPUT_` prefix dropped and lowercased
|
|
1610
|
+
* (`INPUT_WRITE-SUMMARY` reads as `write-summary`).
|
|
1611
|
+
*/
|
|
1612
|
+
readonly names: Effect.Effect<ReadonlyArray<string>>;
|
|
1613
|
+
}
|
|
1571
1614
|
/**
|
|
1572
1615
|
* Options for {@link ActionInput.pairs}.
|
|
1573
1616
|
*
|
|
@@ -1884,6 +1927,59 @@ export declare class ActionInput {
|
|
|
1884
1927
|
* a `const` rather than calling it at each composition site.
|
|
1885
1928
|
*/
|
|
1886
1929
|
static layer(env?: Readonly<Record<string, string | undefined>>): Layer.Layer<never>;
|
|
1930
|
+
/**
|
|
1931
|
+
* {@link ActionInput.provider} over `env`, journaling every input the
|
|
1932
|
+
* program reads.
|
|
1933
|
+
*
|
|
1934
|
+
* @remarks
|
|
1935
|
+
* The test-side half of the manifest sync check: run the code under
|
|
1936
|
+
* `layer`, read `names`, and hand them to `ActionManifest.diff` as the
|
|
1937
|
+
* inputs the code actually reads. Values resolve exactly as under
|
|
1938
|
+
* `ActionInput.provider(env)` — the recorder wraps that provider's lookup
|
|
1939
|
+
* and changes nothing about what it answers — so the recording run can use
|
|
1940
|
+
* the runner-shaped environment `ActionManifest.runnerInputs` builds.
|
|
1941
|
+
*
|
|
1942
|
+
* A read is journaled when its lookup runs, not when a `Config` is merely
|
|
1943
|
+
* described, and whether or not the input has a value: an unsupplied input
|
|
1944
|
+
* the code falls back from is still an input the code reads.
|
|
1945
|
+
*
|
|
1946
|
+
* What counts as an input read is a lookup of an `INPUT_` variable, which
|
|
1947
|
+
* is what every accessor on this class performs. A **bare**
|
|
1948
|
+
* `Config.String("dry-run")` is not journaled: from inside the provider it
|
|
1949
|
+
* is indistinguishable from an ordinary environment read, and journaling
|
|
1950
|
+
* every flat name would report `GITHUB_REPOSITORY` as an undeclared input.
|
|
1951
|
+
* Reading inputs through the accessors is the rule anyway.
|
|
1952
|
+
*
|
|
1953
|
+
* Names come back in the runner-variable form, lowercased, so a declared
|
|
1954
|
+
* `My Input` reads as `my_input`. `ActionManifest.diff` matches inputs by
|
|
1955
|
+
* runner variable, under which the two are the same input.
|
|
1956
|
+
*
|
|
1957
|
+
* Each call journals into its own fresh set; bind the result once per test.
|
|
1958
|
+
*
|
|
1959
|
+
* @example
|
|
1960
|
+
* ```ts
|
|
1961
|
+
* import { assert, it } from "@effect/vitest";
|
|
1962
|
+
* import { ActionInput, ActionManifest } from "@effected/github-actions";
|
|
1963
|
+
* import { Effect } from "effect";
|
|
1964
|
+
*
|
|
1965
|
+
* declare const manifest: ActionManifest;
|
|
1966
|
+
* declare const readInputs: Effect.Effect<unknown, unknown>;
|
|
1967
|
+
*
|
|
1968
|
+
* it.effect("the code reads exactly what action.yml declares", () =>
|
|
1969
|
+
* Effect.gen(function* () {
|
|
1970
|
+
* const recording = ActionInput.recording(ActionManifest.runnerInputs(manifest));
|
|
1971
|
+
* yield* readInputs.pipe(Effect.provide(recording.layer));
|
|
1972
|
+
* const diff = ActionManifest.diff(manifest, { inputs: yield* recording.names });
|
|
1973
|
+
* assert.isTrue(diff.inSync, JSON.stringify(diff));
|
|
1974
|
+
* }),
|
|
1975
|
+
* );
|
|
1976
|
+
* ```
|
|
1977
|
+
*
|
|
1978
|
+
* @param env - The environment the provider serves, as for
|
|
1979
|
+
* {@link ActionInput.provider}. Defaults to an empty record, never
|
|
1980
|
+
* `process.env`: a recorder is a test instrument.
|
|
1981
|
+
*/
|
|
1982
|
+
static recording(env?: Readonly<Record<string, string | undefined>>): ActionInputRecording;
|
|
1887
1983
|
/**
|
|
1888
1984
|
* Inputs-first resolution layered over an existing provider.
|
|
1889
1985
|
*
|
|
@@ -1960,6 +2056,374 @@ export declare class ActionInput {
|
|
|
1960
2056
|
*/
|
|
1961
2057
|
static readonly layerDefault: Layer.Layer<never>;
|
|
1962
2058
|
}
|
|
2059
|
+
declare const ActionManifestInput_base: Schema.Class<ActionManifestInput, Schema.Struct<{
|
|
2060
|
+
/** What the input is for. */
|
|
2061
|
+
readonly description: Schema.optionalKey<Schema.String>;
|
|
2062
|
+
/**
|
|
2063
|
+
* Whether the manifest marks the input required (not enforced by the
|
|
2064
|
+
* runner); the quoted strings `"true"` and `"false"` decode as booleans.
|
|
2065
|
+
*/
|
|
2066
|
+
readonly required: Schema.optionalKey<Schema.decodeTo<Schema.Boolean, Schema.Union<readonly [Schema.Boolean, Schema.Literals<readonly ["true", "false"]>]>, never, never>>;
|
|
2067
|
+
/**
|
|
2068
|
+
* The text published when a workflow omits the input, stringified from any
|
|
2069
|
+
* YAML scalar; a bare `default:` reads as `""`.
|
|
2070
|
+
*/
|
|
2071
|
+
readonly default: Schema.optionalKey<Schema.decodeTo<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>, never, never>>;
|
|
2072
|
+
/** Set when the input is deprecated; the runner warns with this text when a workflow supplies it. */
|
|
2073
|
+
readonly deprecationMessage: Schema.optionalKey<Schema.String>;
|
|
2074
|
+
}>, {}>;
|
|
2075
|
+
/**
|
|
2076
|
+
* One input an `action.yml` declares under `inputs:`.
|
|
2077
|
+
*
|
|
2078
|
+
* @remarks
|
|
2079
|
+
* `default` is the text the runner publishes when a workflow omits the input;
|
|
2080
|
+
* when the manifest declares none, the runner publishes `""` instead — see
|
|
2081
|
+
* {@link ActionManifest.runnerInputs}. A `default` written as a workflow
|
|
2082
|
+
* expression (`${{ github.token }}`) is evaluated by the runner, so here it is
|
|
2083
|
+
* the unevaluated text: supply the evaluated value explicitly in a test.
|
|
2084
|
+
*
|
|
2085
|
+
* `required` is documentation only — the runner does not enforce it — and
|
|
2086
|
+
* `description` is optional here because the runner does not require it
|
|
2087
|
+
* either, even though the metadata reference lists it.
|
|
2088
|
+
*
|
|
2089
|
+
* @public
|
|
2090
|
+
*/
|
|
2091
|
+
export declare class ActionManifestInput extends ActionManifestInput_base {}
|
|
2092
|
+
declare const ActionManifestOutput_base: Schema.Class<ActionManifestOutput, Schema.Struct<{
|
|
2093
|
+
/** What the output carries. */
|
|
2094
|
+
readonly description: Schema.optionalKey<Schema.String>;
|
|
2095
|
+
/** The expression a composite action maps the output from. */
|
|
2096
|
+
readonly value: Schema.optionalKey<Schema.String>;
|
|
2097
|
+
}>, {}>;
|
|
2098
|
+
/**
|
|
2099
|
+
* One output an `action.yml` declares under `outputs:`.
|
|
2100
|
+
*
|
|
2101
|
+
* @remarks
|
|
2102
|
+
* `value` is the expression a composite action maps the output from; a
|
|
2103
|
+
* JavaScript or Docker action writes its outputs at runtime and declares none.
|
|
2104
|
+
*
|
|
2105
|
+
* @public
|
|
2106
|
+
*/
|
|
2107
|
+
export declare class ActionManifestOutput extends ActionManifestOutput_base {}
|
|
2108
|
+
declare const ActionManifestNodeRuns_base: Schema.Class<ActionManifestNodeRuns, Schema.Struct<{
|
|
2109
|
+
/** The Node runtime, such as `node24`. */
|
|
2110
|
+
readonly using: Schema.String;
|
|
2111
|
+
/** The entry point the `main` phase runs. */
|
|
2112
|
+
readonly main: Schema.String;
|
|
2113
|
+
/** The entry point the `pre` phase runs, before any step of the job. */
|
|
2114
|
+
readonly pre: Schema.optionalKey<Schema.String>;
|
|
2115
|
+
/** The entry point the `post` phase runs, after every step of the job. */
|
|
2116
|
+
readonly post: Schema.optionalKey<Schema.String>;
|
|
2117
|
+
/** The condition gating the `pre` phase (`pre-if` in YAML). */
|
|
2118
|
+
readonly preIf: Schema.optionalKey<Schema.String>;
|
|
2119
|
+
/** The condition gating the `post` phase (`post-if` in YAML). */
|
|
2120
|
+
readonly postIf: Schema.optionalKey<Schema.String>;
|
|
2121
|
+
}>, {}>;
|
|
2122
|
+
/**
|
|
2123
|
+
* The `runs:` block of a JavaScript action — `using: node24` and its kin.
|
|
2124
|
+
*
|
|
2125
|
+
* @remarks
|
|
2126
|
+
* `using` is any `node<major>` string rather than a closed list, so a manifest
|
|
2127
|
+
* written for a runtime newer than this package still decodes. The YAML keys
|
|
2128
|
+
* `pre-if` and `post-if` decode to `preIf` and `postIf`.
|
|
2129
|
+
*
|
|
2130
|
+
* @public
|
|
2131
|
+
*/
|
|
2132
|
+
export declare class ActionManifestNodeRuns extends ActionManifestNodeRuns_base {}
|
|
2133
|
+
declare const ActionManifestCompositeRuns_base: Schema.Class<ActionManifestCompositeRuns, Schema.Struct<{
|
|
2134
|
+
/** Always `composite`. */
|
|
2135
|
+
readonly using: Schema.Literal<"composite">;
|
|
2136
|
+
/** The steps the action runs, each an unvalidated mapping. */
|
|
2137
|
+
readonly steps: Schema.$Array<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
2138
|
+
}>, {}>;
|
|
2139
|
+
/**
|
|
2140
|
+
* The `runs:` block of a composite action.
|
|
2141
|
+
*
|
|
2142
|
+
* @remarks
|
|
2143
|
+
* `steps` stays loosely typed — each step is a mapping — because describing
|
|
2144
|
+
* the workflow-step grammar is out of this construct's scope.
|
|
2145
|
+
*
|
|
2146
|
+
* @public
|
|
2147
|
+
*/
|
|
2148
|
+
export declare class ActionManifestCompositeRuns extends ActionManifestCompositeRuns_base {}
|
|
2149
|
+
declare const ActionManifestDockerRuns_base: Schema.Class<ActionManifestDockerRuns, Schema.Struct<{
|
|
2150
|
+
/** Always `docker`. */
|
|
2151
|
+
readonly using: Schema.Literal<"docker">;
|
|
2152
|
+
/** A `Dockerfile` path or a `docker://` image reference. */
|
|
2153
|
+
readonly image: Schema.String;
|
|
2154
|
+
/** Arguments passed to the container, each stringified from any YAML scalar. */
|
|
2155
|
+
readonly args: Schema.optionalKey<Schema.$Array<Schema.decodeTo<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>, never, never>>>;
|
|
2156
|
+
/** Environment variables set in the container. */
|
|
2157
|
+
readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.decodeTo<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.BigInt, Schema.Boolean, Schema.Null]>, never, never>>>;
|
|
2158
|
+
/** Overrides the image's `ENTRYPOINT`. */
|
|
2159
|
+
readonly entrypoint: Schema.optionalKey<Schema.String>;
|
|
2160
|
+
/** The entry point run before the `main` phase (`pre-entrypoint` in YAML). */
|
|
2161
|
+
readonly preEntrypoint: Schema.optionalKey<Schema.String>;
|
|
2162
|
+
/** The entry point run after the job's steps (`post-entrypoint` in YAML). */
|
|
2163
|
+
readonly postEntrypoint: Schema.optionalKey<Schema.String>;
|
|
2164
|
+
/** The condition gating the `pre` phase (`pre-if` in YAML). */
|
|
2165
|
+
readonly preIf: Schema.optionalKey<Schema.String>;
|
|
2166
|
+
/** The condition gating the `post` phase (`post-if` in YAML). */
|
|
2167
|
+
readonly postIf: Schema.optionalKey<Schema.String>;
|
|
2168
|
+
}>, {}>;
|
|
2169
|
+
/**
|
|
2170
|
+
* The `runs:` block of a Docker container action.
|
|
2171
|
+
*
|
|
2172
|
+
* @remarks
|
|
2173
|
+
* The YAML keys `pre-entrypoint`, `post-entrypoint`, `pre-if` and `post-if`
|
|
2174
|
+
* decode to camelCase. `args` entries and `env` values are stringified from
|
|
2175
|
+
* any YAML scalar, as the runner passes them to the container as text.
|
|
2176
|
+
*
|
|
2177
|
+
* @public
|
|
2178
|
+
*/
|
|
2179
|
+
export declare class ActionManifestDockerRuns extends ActionManifestDockerRuns_base {}
|
|
2180
|
+
/**
|
|
2181
|
+
* The three `runs:` shapes an `action.yml` can declare.
|
|
2182
|
+
*
|
|
2183
|
+
* @public
|
|
2184
|
+
*/
|
|
2185
|
+
type ActionManifestRuns = ActionManifestNodeRuns | ActionManifestCompositeRuns | ActionManifestDockerRuns;
|
|
2186
|
+
declare const ActionManifestBranding_base: Schema.Class<ActionManifestBranding, Schema.Struct<{
|
|
2187
|
+
/** A Feather icon name. */
|
|
2188
|
+
readonly icon: Schema.optionalKey<Schema.String>;
|
|
2189
|
+
/** The badge background colour. */
|
|
2190
|
+
readonly color: Schema.optionalKey<Schema.String>;
|
|
2191
|
+
}>, {}>;
|
|
2192
|
+
/**
|
|
2193
|
+
* The `branding:` block a Marketplace listing reads.
|
|
2194
|
+
*
|
|
2195
|
+
* @public
|
|
2196
|
+
*/
|
|
2197
|
+
export declare class ActionManifestBranding extends ActionManifestBranding_base {}
|
|
2198
|
+
declare const ActionManifestReadError_base: Schema.Class<ActionManifestReadError, Schema.TaggedStruct<"ActionManifestReadError", {
|
|
2199
|
+
/** The path that was being read. */
|
|
2200
|
+
readonly path: Schema.String;
|
|
2201
|
+
/** The underlying failure, preserved structurally. */
|
|
2202
|
+
readonly cause: Schema.Defect;
|
|
2203
|
+
}>, import("effect/Cause").YieldableError>;
|
|
2204
|
+
/**
|
|
2205
|
+
* Raised when an `action.yml` cannot be read from the filesystem.
|
|
2206
|
+
*
|
|
2207
|
+
* @public
|
|
2208
|
+
*/
|
|
2209
|
+
export declare class ActionManifestReadError extends ActionManifestReadError_base {
|
|
2210
|
+
get message(): string;
|
|
2211
|
+
}
|
|
2212
|
+
declare const ActionManifestDecodeError_base: Schema.Class<ActionManifestDecodeError, Schema.TaggedStruct<"ActionManifestDecodeError", {
|
|
2213
|
+
/** The rendered parse or schema failure. */
|
|
2214
|
+
readonly detail: Schema.String;
|
|
2215
|
+
/** The `YamlParseError` or `SchemaError` behind it. */
|
|
2216
|
+
readonly cause: Schema.Defect;
|
|
2217
|
+
}>, import("effect/Cause").YieldableError>;
|
|
2218
|
+
/**
|
|
2219
|
+
* Raised when an `action.yml` is not valid YAML, or is YAML that does not
|
|
2220
|
+
* have the shape of an action manifest.
|
|
2221
|
+
*
|
|
2222
|
+
* @remarks
|
|
2223
|
+
* One class for both, because the two share every field and no caller
|
|
2224
|
+
* recovers from one but not the other: either way the manifest is broken.
|
|
2225
|
+
* `detail` is the rendered parse or schema failure and `cause` the structured
|
|
2226
|
+
* original.
|
|
2227
|
+
*
|
|
2228
|
+
* @public
|
|
2229
|
+
*/
|
|
2230
|
+
export declare class ActionManifestDecodeError extends ActionManifestDecodeError_base {
|
|
2231
|
+
get message(): string;
|
|
2232
|
+
}
|
|
2233
|
+
/**
|
|
2234
|
+
* Anything that can go wrong loading an `action.yml`.
|
|
2235
|
+
*
|
|
2236
|
+
* @public
|
|
2237
|
+
*/
|
|
2238
|
+
type ActionManifestError = ActionManifestReadError | ActionManifestDecodeError;
|
|
2239
|
+
/**
|
|
2240
|
+
* The names an action's code reads and writes, for {@link ActionManifest.diff}.
|
|
2241
|
+
*
|
|
2242
|
+
* @public
|
|
2243
|
+
*/
|
|
2244
|
+
interface ActionManifestUsage {
|
|
2245
|
+
/** The input names the code reads, spelled as in `action.yml`. */
|
|
2246
|
+
readonly inputs?: Iterable<string>;
|
|
2247
|
+
/** The output names the code writes. Omit to skip the output comparison. */
|
|
2248
|
+
readonly outputs?: Iterable<string>;
|
|
2249
|
+
}
|
|
2250
|
+
declare const ActionManifestDiff_base: Schema.Class<ActionManifestDiff, Schema.Struct<{
|
|
2251
|
+
/** Declared in `action.yml`, never read by the code. */
|
|
2252
|
+
readonly unreadInputs: Schema.$Array<Schema.String>;
|
|
2253
|
+
/** Read by the code, not declared in `action.yml` — on a runner it arrives absent. */
|
|
2254
|
+
readonly undeclaredInputs: Schema.$Array<Schema.String>;
|
|
2255
|
+
/** Declared in `action.yml`, never written by the code. */
|
|
2256
|
+
readonly unwrittenOutputs: Schema.$Array<Schema.String>;
|
|
2257
|
+
/** Written by the code, not declared in `action.yml`. */
|
|
2258
|
+
readonly undeclaredOutputs: Schema.$Array<Schema.String>;
|
|
2259
|
+
}>, {}>;
|
|
2260
|
+
/**
|
|
2261
|
+
* Where an action's code and its `action.yml` disagree.
|
|
2262
|
+
*
|
|
2263
|
+
* @remarks
|
|
2264
|
+
* Every list is in declaration or usage order, with duplicates removed. An
|
|
2265
|
+
* empty diff — {@link ActionManifestDiff.inSync} — means the code reads every
|
|
2266
|
+
* declared input, declares every input it reads, and the same for outputs.
|
|
2267
|
+
*
|
|
2268
|
+
* @public
|
|
2269
|
+
*/
|
|
2270
|
+
export declare class ActionManifestDiff extends ActionManifestDiff_base {
|
|
2271
|
+
/** True when the code and the manifest agree on every name. */
|
|
2272
|
+
get inSync(): boolean;
|
|
2273
|
+
}
|
|
2274
|
+
declare const ActionManifest_base: Schema.Class<ActionManifest, Schema.Struct<{
|
|
2275
|
+
/** The action's display name. */
|
|
2276
|
+
readonly name: Schema.String;
|
|
2277
|
+
/** What the action does. */
|
|
2278
|
+
readonly description: Schema.optionalKey<Schema.String>;
|
|
2279
|
+
/** Who wrote the action. */
|
|
2280
|
+
readonly author: Schema.optionalKey<Schema.String>;
|
|
2281
|
+
/** The declared inputs, keyed by name. */
|
|
2282
|
+
readonly inputs: Schema.optionalKey<Schema.$Record<Schema.String, typeof ActionManifestInput>>;
|
|
2283
|
+
/** The declared outputs, keyed by name. */
|
|
2284
|
+
readonly outputs: Schema.optionalKey<Schema.$Record<Schema.String, typeof ActionManifestOutput>>;
|
|
2285
|
+
/** How the action executes. */
|
|
2286
|
+
readonly runs: Schema.Union<readonly [Schema.encodeKeys<typeof ActionManifestNodeRuns, {
|
|
2287
|
+
readonly preIf: "pre-if";
|
|
2288
|
+
readonly postIf: "post-if";
|
|
2289
|
+
}>, typeof ActionManifestCompositeRuns, Schema.encodeKeys<typeof ActionManifestDockerRuns, {
|
|
2290
|
+
readonly preEntrypoint: "pre-entrypoint";
|
|
2291
|
+
readonly postEntrypoint: "post-entrypoint";
|
|
2292
|
+
readonly preIf: "pre-if";
|
|
2293
|
+
readonly postIf: "post-if";
|
|
2294
|
+
}>]>;
|
|
2295
|
+
/** The Marketplace badge. */
|
|
2296
|
+
readonly branding: Schema.optionalKey<typeof ActionManifestBranding>;
|
|
2297
|
+
}>, {}>;
|
|
2298
|
+
/**
|
|
2299
|
+
* A decoded `action.yml`: the action's metadata, its declared inputs and
|
|
2300
|
+
* outputs, and the `runs:` block naming how it executes.
|
|
2301
|
+
*
|
|
2302
|
+
* @remarks
|
|
2303
|
+
* `action.yml` is the single source of truth for an action's input names and
|
|
2304
|
+
* defaults, and the code mirrors both. This construct makes the mirror
|
|
2305
|
+
* testable: {@link ActionManifest.runnerInputs} builds the input environment a
|
|
2306
|
+
* real runner builds from the manifest, and {@link ActionManifest.diff} reports
|
|
2307
|
+
* where the code's reads and writes disagree with what the manifest declares.
|
|
2308
|
+
*
|
|
2309
|
+
* `inputs` and `outputs` are keyed by name, in declaration order. Keys this
|
|
2310
|
+
* construct does not describe are ignored, so a manifest carrying a newer
|
|
2311
|
+
* metadata key still decodes.
|
|
2312
|
+
*
|
|
2313
|
+
* @example
|
|
2314
|
+
* ```ts
|
|
2315
|
+
* import { ActionInput, ActionManifest } from "@effected/github-actions";
|
|
2316
|
+
* import { Effect } from "effect";
|
|
2317
|
+
*
|
|
2318
|
+
* const program = Effect.gen(function* () {
|
|
2319
|
+
* const manifest = yield* ActionManifest.read("action.yml");
|
|
2320
|
+
* // Every declared input present, with its manifest default or "".
|
|
2321
|
+
* const layer = ActionInput.layer(ActionManifest.runnerInputs(manifest, { "dry-run": "true" }));
|
|
2322
|
+
* return layer;
|
|
2323
|
+
* });
|
|
2324
|
+
* ```
|
|
2325
|
+
*
|
|
2326
|
+
* @public
|
|
2327
|
+
*/
|
|
2328
|
+
export declare class ActionManifest extends ActionManifest_base {
|
|
2329
|
+
/**
|
|
2330
|
+
* Decode `action.yml` text, synchronously.
|
|
2331
|
+
*
|
|
2332
|
+
* @remarks
|
|
2333
|
+
* Fails with {@link ActionManifestDecodeError} when the text is not YAML or
|
|
2334
|
+
* not an action manifest. This is the form for a test that wants the
|
|
2335
|
+
* manifest without an effect; {@link ActionManifest.decode} is the same
|
|
2336
|
+
* decode as an `Effect`.
|
|
2337
|
+
*/
|
|
2338
|
+
static decodeResult(source: string): Result.Result<ActionManifest, ActionManifestDecodeError>;
|
|
2339
|
+
/**
|
|
2340
|
+
* Decode `action.yml` text.
|
|
2341
|
+
*
|
|
2342
|
+
* @remarks
|
|
2343
|
+
* Fails with {@link ActionManifestDecodeError} when the text is not YAML or
|
|
2344
|
+
* not an action manifest.
|
|
2345
|
+
*/
|
|
2346
|
+
static readonly decode: (source: string) => Effect.Effect<ActionManifest, ActionManifestDecodeError>;
|
|
2347
|
+
/**
|
|
2348
|
+
* Read and decode the `action.yml` at `path`.
|
|
2349
|
+
*
|
|
2350
|
+
* @remarks
|
|
2351
|
+
* Reads through `FileSystem` in `R`, so a test provides `@effected/memfs`
|
|
2352
|
+
* and production the platform filesystem. A read failure is
|
|
2353
|
+
* {@link ActionManifestReadError}, carrying the path; a malformed manifest is
|
|
2354
|
+
* {@link ActionManifestDecodeError}.
|
|
2355
|
+
*/
|
|
2356
|
+
static readonly read: (path: string) => Effect.Effect<ActionManifest, ActionManifestDecodeError | ActionManifestReadError, FileSystem.FileSystem>;
|
|
2357
|
+
/**
|
|
2358
|
+
* The input environment a real runner builds for this manifest.
|
|
2359
|
+
*
|
|
2360
|
+
* @remarks
|
|
2361
|
+
* The runner publishes a variable for **every** declared input: the value
|
|
2362
|
+
* the workflow supplied under `with:`, else the manifest `default`, else
|
|
2363
|
+
* `""`. So "absent" is a state production never produces, and a test built
|
|
2364
|
+
* on an empty `ActionInput.layer({})` exercises the code's
|
|
2365
|
+
* `Config.withDefault` fallbacks rather than the manifest defaults a real
|
|
2366
|
+
* run decodes. This record is the runner-shaped baseline instead.
|
|
2367
|
+
*
|
|
2368
|
+
* Keys are runner variables — `INPUT_` plus the name uppercased with spaces
|
|
2369
|
+
* turned to underscores and every other character, dashes included, kept
|
|
2370
|
+
* (`write-summary` → `INPUT_WRITE-SUMMARY`) — derived through
|
|
2371
|
+
* `ActionInput.variable`, the same function every accessor reads through.
|
|
2372
|
+
* So the record feeds `ActionInput.layer`, spreads into
|
|
2373
|
+
* `ActionEnvironment.layerTest`'s overrides, or becomes a spawned
|
|
2374
|
+
* process's environment unchanged.
|
|
2375
|
+
*
|
|
2376
|
+
* `supplied` is the workflow's `with:` block, keyed by input name, and is
|
|
2377
|
+
* matched to the declared inputs **by runner variable**, the way
|
|
2378
|
+
* {@link ActionManifest.diff} matches: `write summary`, `write_summary` and
|
|
2379
|
+
* `WRITE_SUMMARY` all supply the input declared as `write_summary`. A
|
|
2380
|
+
* supplied value wins even when it is `""`, as on a runner.
|
|
2381
|
+
*
|
|
2382
|
+
* A supplied name the manifest does not declare is **passed through** as
|
|
2383
|
+
* one more `INPUT_` variable, because the runner publishes it too — it only
|
|
2384
|
+
* warns. This never throws. To catch a typo in a test, compare the names
|
|
2385
|
+
* with {@link ActionManifest.diff}, which reports an undeclared read; a
|
|
2386
|
+
* typoed supplied name otherwise leaves the declared input on its default.
|
|
2387
|
+
*
|
|
2388
|
+
* **Composite actions receive no `INPUT_` environment.** The runner
|
|
2389
|
+
* publishes these variables to node and docker actions only; a composite
|
|
2390
|
+
* action reads its inputs through `inputs.<name>` expressions in its steps.
|
|
2391
|
+
* This builder is for node and docker actions, and for a composite test
|
|
2392
|
+
* that drives the inputs into its steps explicitly.
|
|
2393
|
+
*
|
|
2394
|
+
* @param manifest - The decoded manifest.
|
|
2395
|
+
* @param supplied - The workflow's `with:` values, keyed by input name.
|
|
2396
|
+
* @returns The runner's `INPUT_*` variables: one per declared input, then
|
|
2397
|
+
* one per supplied name the manifest does not declare.
|
|
2398
|
+
*/
|
|
2399
|
+
static runnerInputs(manifest: ActionManifest, supplied?: Readonly<Record<string, string>>): Record<string, string>;
|
|
2400
|
+
/**
|
|
2401
|
+
* Compare the names an action's code reads and writes against the names
|
|
2402
|
+
* its manifest declares.
|
|
2403
|
+
*
|
|
2404
|
+
* @remarks
|
|
2405
|
+
* Inputs are matched the way the runner connects them — by runner
|
|
2406
|
+
* variable — so `write summary` in code and `write_summary` in the
|
|
2407
|
+
* manifest are the same input, and so are names differing only in case.
|
|
2408
|
+
* Outputs are matched verbatim. Omitting `usage.outputs` skips the output
|
|
2409
|
+
* comparison, leaving both output lists empty; omitting `usage.inputs`
|
|
2410
|
+
* compares against no reads, so every declared input reports unread.
|
|
2411
|
+
*
|
|
2412
|
+
* @example
|
|
2413
|
+
* ```ts
|
|
2414
|
+
* import { assert, it } from "@effect/vitest";
|
|
2415
|
+
* import { ActionManifest } from "@effected/github-actions";
|
|
2416
|
+
*
|
|
2417
|
+
* declare const manifest: ActionManifest;
|
|
2418
|
+
*
|
|
2419
|
+
* it("action.yml and the code agree", () => {
|
|
2420
|
+
* const diff = ActionManifest.diff(manifest, { inputs: ["name", "dry-run"], outputs: ["greeting"] });
|
|
2421
|
+
* assert.isTrue(diff.inSync, JSON.stringify(diff));
|
|
2422
|
+
* });
|
|
2423
|
+
* ```
|
|
2424
|
+
*/
|
|
2425
|
+
static diff(manifest: ActionManifest, usage: ActionManifestUsage): ActionManifestDiff;
|
|
2426
|
+
}
|
|
1963
2427
|
declare const OidcTokenError_base: Schema.Class<OidcTokenError, Schema.TaggedStruct<"OidcTokenError", {
|
|
1964
2428
|
/**
|
|
1965
2429
|
* `unavailable` — the runner did not publish the token-service variables,
|
|
@@ -2000,6 +2464,17 @@ interface OidcTokenIssuerShape {
|
|
|
2000
2464
|
* Omitting the audience sends no `audience` parameter at all, matching
|
|
2001
2465
|
* `@actions/core.getIDToken` — the runner's default audience is not the empty
|
|
2002
2466
|
* string.
|
|
2467
|
+
*
|
|
2468
|
+
* **The live issuer masks the token at issuance.** Every token it fetches is
|
|
2469
|
+
* registered with the runner's log filter (`Secret.mask`, one `::add-mask::`)
|
|
2470
|
+
* before it is returned, so a consumer that declassifies and logs it, or
|
|
2471
|
+
* serializes an error carrying it, prints a redaction rather than the JWT.
|
|
2472
|
+
* Masking is the issuer's job because it is the one place every token
|
|
2473
|
+
* passes; a consumer masking again is harmless. The caveat `Secret.mask`
|
|
2474
|
+
* documents applies: in a **detached worker** the mask line itself is the
|
|
2475
|
+
* leak, since no runner parses that process's stdout, so mint in the parent
|
|
2476
|
+
* and compose `ActionOutputs.layerDetached` in the worker, under which the
|
|
2477
|
+
* mask is a no-op. The doubles mask nothing: they issue no real token.
|
|
2003
2478
|
*/
|
|
2004
2479
|
readonly token: (audience?: string) => Effect.Effect<Redacted.Redacted<string>, OidcTokenError>;
|
|
2005
2480
|
/**
|
|
@@ -2028,6 +2503,12 @@ interface OidcTokenIssuerShape {
|
|
|
2028
2503
|
* {@link OidcTokenIssuer.layerFor} answers with real, decodable claims, so
|
|
2029
2504
|
* a test cannot silently skip the path under test because the double
|
|
2030
2505
|
* returned a token that is not a JWT.
|
|
2506
|
+
*
|
|
2507
|
+
* The token this fetches to decode is masked too, exactly as
|
|
2508
|
+
* {@link OidcTokenIssuerShape.token}'s is, though it never leaves: the raw
|
|
2509
|
+
* JWT exists in this process for the decode, and a decode failure's cause can
|
|
2510
|
+
* carry what it failed on, so the mask costs one command and closes that
|
|
2511
|
+
* path. There is one mask site, where the token is issued, for both members.
|
|
2031
2512
|
*/
|
|
2032
2513
|
readonly claims: (audience?: string) => Effect.Effect<ActionsOidcClaims, OidcTokenError>;
|
|
2033
2514
|
}
|
|
@@ -2077,8 +2558,15 @@ export declare class OidcTokenIssuer extends OidcTokenIssuer_base {
|
|
|
2077
2558
|
* @remarks
|
|
2078
2559
|
* Fails with {@link OidcTokenError} (`unavailable`) at use when the workflow
|
|
2079
2560
|
* lacks `permissions: id-token: write`.
|
|
2561
|
+
*
|
|
2562
|
+
* Requires {@link ActionOutputs} because every token it issues is masked
|
|
2563
|
+
* through it at issuance (see {@link OidcTokenIssuerShape.token}). Under
|
|
2564
|
+
* `ActionRuntime.layer` that is already at hand; a worker that composes
|
|
2565
|
+
* `ActionOutputs.layerDetached` gets an issuer whose mask is the documented
|
|
2566
|
+
* no-op, which is the right thing there and no substitute for minting in
|
|
2567
|
+
* the parent.
|
|
2080
2568
|
*/
|
|
2081
|
-
static readonly layer: Layer.Layer<OidcTokenIssuer, never, ActionEnvironment | HttpClient.HttpClient>;
|
|
2569
|
+
static readonly layer: Layer.Layer<OidcTokenIssuer, never, ActionEnvironment | HttpClient.HttpClient | ActionOutputs>;
|
|
2082
2570
|
/**
|
|
2083
2571
|
* An **unsigned** JWT carrying these claims.
|
|
2084
2572
|
*
|
|
@@ -5216,5 +5704,5 @@ export declare class Secret {
|
|
|
5216
5704
|
*/
|
|
5217
5705
|
static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
|
|
5218
5706
|
}
|
|
5219
|
-
export { type ActionCacheShape, type ActionEnvironmentShape, type ActionLoggerShape, type ActionOutputError, type ActionOutputsShape, type ActionRunOptions, type ActionServices, type ActionStateShape, type AnnotationProperties, type ArtifactItem, type ArtifactRef, type ArtifactShape, type BlobEnvelopeError, type BlobStoreShape, type CacheKeyError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, type CheckFlushOutcome, type CheckRunConclusion, type CheckRunProjection, type ClientLayerOptions, type DataBlobTransfer, type DetachedProcessError, type DetachedProcessOps, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, type DryRunShape, type ExtractOptions, type FileBlobTransfer, type GitHubHeadingDepth, type GitHubListOptions, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, type ManagedDocumentSource, type OidcTokenIssuerShape, type PackageManagerInstallOptions, type PackageManagerInstallerShape, type PairsOptions, type PathPrependEnv, type PathPrependOptions, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, type RecordedOutputMember, type RecordingOidcTokenIssuer, type RecordingOutputs, type S3Config, type StoredBlob, type ToolDownloadOptions, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand };
|
|
5707
|
+
export { type ActionCacheShape, type ActionEnvironmentShape, type ActionInputRecording, type ActionLoggerShape, type ActionManifestError, type ActionManifestRuns, type ActionManifestUsage, type ActionOutputError, type ActionOutputsShape, type ActionRunOptions, type ActionServices, type ActionStateShape, type AnnotationProperties, type ArtifactItem, type ArtifactRef, type ArtifactShape, type BlobEnvelopeError, type BlobStoreShape, type CacheKeyError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, type CheckFlushOutcome, type CheckRunConclusion, type CheckRunProjection, type ClientLayerOptions, type DataBlobTransfer, type DetachedProcessError, type DetachedProcessOps, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, type DryRunShape, type ExtractOptions, type FileBlobTransfer, type GitHubHeadingDepth, type GitHubListOptions, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, type ManagedDocumentSource, type OidcTokenIssuerShape, type PackageManagerInstallOptions, type PackageManagerInstallerShape, type PairsOptions, type PathPrependEnv, type PathPrependOptions, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, type RecordedOutputMember, type RecordingOidcTokenIssuer, type RecordingOutputs, type S3Config, type StoredBlob, type ToolDownloadOptions, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, type WithStepOptions, WorkflowCommand };
|
|
5220
5708
|
//# sourceMappingURL=index.d.ts.map
|
package/index.js
CHANGED
|
@@ -6,10 +6,11 @@ import { ActionState, ActionStateError } from "./ActionState.js";
|
|
|
6
6
|
import { Action, ActionRuntime, describeCause } from "./Action.js";
|
|
7
7
|
import { BlobTransferError } from "./BlobTransfer.js";
|
|
8
8
|
import { ActionCache, ActionCacheError } from "./ActionCache.js";
|
|
9
|
+
import { ActionManifest, ActionManifestBranding, ActionManifestCompositeRuns, ActionManifestDecodeError, ActionManifestDiff, ActionManifestDockerRuns, ActionManifestInput, ActionManifestNodeRuns, ActionManifestOutput, ActionManifestReadError } from "./ActionManifest.js";
|
|
10
|
+
import { Secret } from "./Secret.js";
|
|
9
11
|
import { OidcTokenError, OidcTokenIssuer } from "./OidcTokenIssuer.js";
|
|
10
12
|
import { ActionsIdentityToken } from "./ActionsIdentityToken.js";
|
|
11
13
|
import { ActionsProvenance } from "./ActionsProvenance.js";
|
|
12
|
-
import { Secret } from "./Secret.js";
|
|
13
14
|
import { ActionsRegistryCredential } from "./ActionsRegistryCredential.js";
|
|
14
15
|
import { Artifact, ArtifactError } from "./Artifact.js";
|
|
15
16
|
import { BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, NotABlobEnvelopeError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError } from "./BlobEnvelope.js";
|
|
@@ -28,4 +29,4 @@ import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
|
|
|
28
29
|
import { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError } from "./PackageManagerInstaller.js";
|
|
29
30
|
import { WorkflowCommand } from "@effected/github-commands";
|
|
30
31
|
|
|
31
|
-
export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, ActionsRegistryCredential, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };
|
|
32
|
+
export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionManifest, ActionManifestBranding, ActionManifestCompositeRuns, ActionManifestDecodeError, ActionManifestDiff, ActionManifestDockerRuns, ActionManifestInput, ActionManifestNodeRuns, ActionManifestOutput, ActionManifestReadError, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, ActionsRegistryCredential, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@effected/github-actions",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.28.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
|
|
6
6
|
"keywords": [
|
|
@@ -39,18 +39,19 @@
|
|
|
39
39
|
},
|
|
40
40
|
"dependencies": {
|
|
41
41
|
"@azure/storage-blob": "^12.33.0",
|
|
42
|
-
"@effected/crypto": "^0.
|
|
43
|
-
"@effected/github": "^0.
|
|
44
|
-
"@effected/github-commands": "^0.6.
|
|
42
|
+
"@effected/crypto": "^0.2.0",
|
|
43
|
+
"@effected/github": "^0.25.0",
|
|
44
|
+
"@effected/github-commands": "^0.6.2",
|
|
45
45
|
"@effected/glob": "^0.14.0",
|
|
46
46
|
"@effected/jwt": "^0.6.0",
|
|
47
|
-
"@effected/markdown": "^0.
|
|
48
|
-
"@effected/npm": "^0.26.
|
|
47
|
+
"@effected/markdown": "^0.23.0",
|
|
48
|
+
"@effected/npm": "^0.26.2",
|
|
49
49
|
"@effected/oidc": "^0.1.2",
|
|
50
|
-
"@effected/sbom": "^0.
|
|
51
|
-
"@effected/semver": "^0.
|
|
50
|
+
"@effected/sbom": "^0.16.0",
|
|
51
|
+
"@effected/semver": "^0.18.0",
|
|
52
52
|
"@effected/templates": "^0.14.1",
|
|
53
|
-
"@effected/walker": "^0.
|
|
53
|
+
"@effected/walker": "^0.20.0",
|
|
54
|
+
"@effected/yaml": "^0.25.1"
|
|
54
55
|
},
|
|
55
56
|
"peerDependencies": {
|
|
56
57
|
"@effect/platform-node": "^4.0.0",
|