@effected/github-actions 0.19.0 → 0.20.0

package/Action.js

@@ -1,9 +1,9 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
 import { ActionInput } from "./ActionInput.js";
-import { WorkflowCommand } from "./WorkflowCommand.js";
 import { ActionLogger } from "./ActionLogger.js";
 import { ActionOutputs } from "./ActionOutputs.js";
 import { ActionState } from "./ActionState.js";
+import { WorkflowCommand } from "@effected/github-commands";
 import { NodeServices } from "@effect/platform-node";
 import { Cause, Effect, Exit, Layer, LogLevel, Option, References, Result } from "effect";
 import { FetchHttpClient } from "effect/http";
@@ -52,7 +52,7 @@ const withStepDebugLogLevel = (program) => Effect.gen(function* () {
 * A readable one-line summary of why an action failed.
 *
 * @remarks
-* `[Tag] message` because a workflow log is read by a human scanning for the
+* `[Tag]: message` because a workflow log is read by a human scanning for the
 * first red line, and every error in this kit carries both. The `_tag` is what
 * makes two failures with the same wording distinguishable, and the `message`
 * getter is what makes the line worth reading.
@@ -99,11 +99,11 @@ const describeError = (error) => {
 *
 * Two things it deliberately does **not** do:
 *
-* - **It does not wrap the program in a log buffer.** The package this replaces
-*   did, and an unhandled defect inside the buffer swallowed the entire
-*   transcript — the run failed and printed nothing. `ActionLogger.withBuffer`
-*   is opt-in and flushes on every exit path including a defect, so the
-*   buffering is where the caller can see it.
+* - **It does not wrap the program in a log buffer.** A buffer that swallowed
+*   the transcript on an unhandled defect would leave a run that failed and
+*   printed nothing. `ActionLogger.withBuffer` is opt-in and flushes on every
+*   exit path including a defect, so the buffering is where the caller can
+*   see it.
 * - **It does not throw.** The returned promise always resolves; the failure is
 *   in `process.exitCode`, which is what the runner reads. An action entry
 *   point that rejected would produce an unhandled rejection *and* a failed
@@ -112,9 +112,9 @@ const describeError = (error) => {
 * The rendering depth is deliberate too: one `::error::` line carrying
 * `[Tag]: message`, and the fiddly diagnostics — the full `Cause.pretty` render
 * with its span trace and stack — behind `::debug::`, which the runner shows
-* only when someone turns step debugging on. The package this replaces spliced
-* a JS stack into the visible error, which in a bundled action points at one
-* line of `dist/main.js`.
+* only when someone turns step debugging on. No JS stack is spliced into the
+* visible error, because in a bundled action it points at one line of
+* `dist/main.js`.
 *
 * @example
 * ```ts
@@ -133,8 +133,9 @@ var Action = class {
 	* Run an action program to completion.
 	*
 	* @remarks
-	* Resolves whether the program succeeded or not; read `process.exitCode` for
-	* the verdict.
+	* Never rejects: the promise resolves whether the program succeeded or not,
+	* so read `process.exitCode` for the verdict. Requirements beyond
+	* {@link ActionServices} come from `options.layer`.
 	*/
 	static run = (program, options = {}) => {
 		const extra = options.layer;

package/ActionCache.js

@@ -169,8 +169,7 @@ const make = (transfer) => Effect.gen(function* () {
 	*
 	* Output and exit code come from the SAME `spawn` handle
 	* (`internal/spawn.ts` — the spawner's convenience members each spawn
-	* independently, and the double run failed loudly in
-	* `ToolInstaller.extractZip` on Windows).
+	* independently, so reading both from them would run `tar` twice).
 	*/
 	const tar = (args, key, tolerateWarnings) => Effect.gen(function* () {
 		const { output, code } = yield* spawnOnce(spawner, ChildProcess.make("tar", [...args])).pipe(Effect.mapError(archiveFailed(key)));

package/ActionEnvironment.js

@@ -14,6 +14,7 @@ import { Context, Effect, FileSystem, Layer, Option, Schema } from "effect";
 * @public
 */
 var ActionEnvironmentError = class extends Schema.TaggedError()("ActionEnvironmentError", {
+	/** `missing` — absent or empty; `malformed` — present but unusable. */
 	reason: Schema.Literals(["missing", "malformed"]),
 	/** The environment variable involved. */
 	name: Schema.String,
@@ -32,6 +33,7 @@ var ActionEnvironmentError = class extends Schema.TaggedError()("ActionEnvironme
 var GitHubContext = class extends Schema.Class("GitHubContext")({
 	/** `owner/repo`. */
 	repository: Schema.String,
+	/** The repository owner's login. */
 	repositoryOwner: Schema.String,
 	/** The full ref, e.g. `refs/heads/main`. */
 	ref: Schema.String,
@@ -53,16 +55,27 @@ var GitHubContext = class extends Schema.Class("GitHubContext")({
 	* an encoded context stays plain JSON.
 	*/
 	headRef: Schema.OptionFromNullOr(Schema.String),
+	/** The commit SHA that triggered the workflow. */
 	sha: Schema.String,
+	/** The workflow's name. */
 	workflow: Schema.String,
+	/** The current job's id. */
 	job: Schema.String,
+	/** The run's unique number, decoded from `GITHUB_RUN_ID`. */
 	runId: Schema.Number,
+	/** The attempt number of this run, starting at 1. */
 	runAttempt: Schema.Number,
+	/** The name of the event that triggered the workflow, e.g. `push`. */
 	eventName: Schema.String,
+	/** The login of the user that triggered the run. */
 	actor: Schema.String,
+	/** The GitHub server URL, e.g. `https://github.com`. */
 	serverUrl: Schema.String,
+	/** The REST API URL, e.g. `https://api.github.com`. */
 	apiUrl: Schema.String,
+	/** The GraphQL API URL. */
 	graphqlUrl: Schema.String,
+	/** The default working directory on the runner for steps. */
 	workspace: Schema.String
 }) {
 	/**
@@ -86,8 +99,11 @@ var GitHubContext = class extends Schema.Class("GitHubContext")({
 * @public
 */
 var RunnerContext = class extends Schema.Class("RunnerContext")({
+	/** The runner's operating system: `Linux`, `Windows` or `macOS`. */
 	os: Schema.String,
+	/** The runner's architecture, e.g. `X64` or `ARM64`. */
 	arch: Schema.String,
+	/** The runner's name. */
 	name: Schema.String,
 	/** A scratch directory emptied between jobs. */
 	temp: Schema.String,
@@ -101,8 +117,7 @@ var RunnerContext = class extends Schema.Class("RunnerContext")({
 * A `Context.Reference` rather than a mutable global: overrides are
 * **fiber-local**, so two concurrent fibers can override the same variable
 * without seeing each other, and nothing needs restoring afterwards. This is
-* what makes {@link ActionEnvironmentShape.withEnv} parallel-safe — the
-* property the hand-rolled set/restore version it replaces could not have.
+* what makes {@link ActionEnvironmentShape.withEnv} parallel-safe.
 *
 * @internal
 */
@@ -240,10 +255,10 @@ var ActionEnvironment = class ActionEnvironment extends Context.Service()("@effe
 	* @remarks
 	* **A recorded exception to the die-on-unstubbed rule.** Every other service
 	* in this package dies when a suite calls something it did not stub, because
-	* a plausible default hides a real gap. Here the opposite is true: the twelve
-	* context variables have one obviously-correct shape, and requiring each
-	* suite to restate them produced a byte-identical block duplicated six times
-	* across the consumers. Overrides merge on top.
+	* a plausible default hides a real gap. Here the opposite is true: the context
+	* variables have one obviously-correct shape, and requiring each suite to
+	* restate them would duplicate a byte-identical block in every suite.
+	* Overrides merge on top.
 	*
 	* The optional second argument serves {@link ActionEnvironmentShape.payload}
 	* **directly**, replacing the `GITHUB_EVENT_PATH` read rather than seeding a

package/ActionInput.js

@@ -9,10 +9,10 @@ import { Config, ConfigProvider, Context, Effect, Schema, SchemaIssue } from "ef
 * and leaves every other character, **dashes included**, alone. So the input
 * `sbom-config` arrives as `INPUT_SBOM-CONFIG`, not `INPUT_SBOM_CONFIG`.
 *
-* That distinction is not academic: a consumer read `process.env["INPUT_SBOM_CONFIG"]`
-* directly, silently got nothing, and shipped it. Every accessor in this module
-* goes through this function so no caller ever spells the variable name, which
-* makes that class of bug unrepresentable rather than merely documented.
+* That distinction is not academic: reading `process.env["INPUT_SBOM_CONFIG"]`
+* directly silently yields nothing. Every accessor in this module goes through
+* this function so no caller ever spells the variable name, which makes that
+* class of bug unrepresentable rather than merely documented.
 *
 * @internal
 */
@@ -24,11 +24,10 @@ const inputVariable = (name) => `INPUT_${name.replaceAll(" ", "_").toUpperCase()
 * `Config.withDefault` and `Config.option` fall back only when the config
 * resolves *absent* — no provider input at all. A failure raised from inside
 * `Config.mapEffect` is a hard evaluation failure carrying the evidence that
-* input WAS present, so a default never swallows it (`Config.ts`: the
-* `Resolved`/`Absent` resolution model and `mapEffect`). That is the guard
-* against the shipped defect where `dry-run: yes` quietly became `false` and
-* the action performed the mutations the author meant to rehearse. `actual`
-* carries the offending value so the rendered error names it.
+* input WAS present, so a default never swallows it. That is the guard against
+* `dry-run: yes` quietly becoming `false` and the action performing the
+* mutations the author meant to rehearse. `actual` carries the offending value
+* so the rendered error names it.
 */
 const configError = (message, actual) => new Config.ConfigError(new Schema.SchemaError(new SchemaIssue.InvalidValue({ message }, actual)));
 /** YAML 1.2 core-schema booleans, which is what the runner documents. */
@@ -53,19 +52,12 @@ const stripComment = (line) => {
 * @remarks
 * Inputs are **never** read from `process.env` directly. Every accessor names
 * the input the way the workflow author wrote it and lets this module derive
-* the runner's variable name — see `inputVariable` for why that matters. (A
-* `{@link}` cannot reach it: it is internal, so it is not exported from the
-* entrypoint and the reference would not resolve.)
+* the runner's variable name — see `ActionInput.variable` for why that
+* matters.
 *
-* `lines`, `list` and `pairs` exist because the `@actions/core`-faithful
-* newline split was not enough for real consumers: two of them reinvented
-* richer parsing independently, one parsing JSON arrays and bullet lists, the
-* other stripping comments and reading `key=value` pairs. Those are now one
-* implementation with one set of tests instead of two divergent ones with
-* none.
-*
-* These are grouped statics over one concept reaching nothing but `Config` —
-* not a namespace object over engines.
+* `lines` is the `@actions/core`-faithful newline split; `list` and `pairs`
+* read the richer shapes workflow authors write — JSON arrays, bullet lists,
+* comments and `key=value` pairs.
 *
 * **The absence contract, shared by every accessor:** the runner writes `""`
 * for an input the workflow left out, and the provider reads an empty string
@@ -120,10 +112,9 @@ var ActionInput = class ActionInput {
 	* **An input whose documented meaning is "set it empty to disable this"
 	* cannot be read with `Config.withDefault`.** Empty is classified as missing
 	* *before* the default is consulted, so the default substitutes and the
-	* documented behavior can never happen. A live action shipped exactly that
-	* for its whole lifetime: `action.yml` promised `release-prefix: ""` would
-	* disable retry, and it never could. `Config.option` is the shape that
-	* distinguishes the states:
+	* documented behavior can never happen: if `action.yml` promises
+	* `release-prefix: ""` disables retry, a `withDefault` read makes that
+	* impossible. `Config.option` is the shape that distinguishes the states:
 	*
 	* ```ts
 	* Config.option(ActionInput.string("release-prefix"))
@@ -139,8 +130,7 @@ var ActionInput = class ActionInput {
 	* no-default case, and it is the manifest default — when there is one — that
 	* makes the unsupplied and explicitly-empty cases distinguishable at all.
 	*
-	* Two consequences follow from how the runner actually behaves, both
-	* confirmed against `actions/runner` and on a live runner:
+	* Two consequences follow from how the runner actually behaves:
 	*
 	* - **The runner publishes a variable for every declared input**, so *absent*
 	*   is a state a runner never produces. The `Some` branch above depends on
@@ -164,8 +154,8 @@ var ActionInput = class ActionInput {
 	* Absent or `""` is **missing data** — wrap with `Config.withDefault` for
 	* an optional flag. A **present but malformed** value (`yes`, `on`, `1`) is
 	* a different class: it fails carrying its `actual`, deliberately, so a
-	* default does NOT swallow it — the shipped defect this guards against was
-	* a malformed `dry-run` quietly reading as `false`.
+	* default does NOT swallow it, so a malformed `dry-run` never quietly reads
+	* as `false`.
 	*/
 	static boolean(name) {
 		return Config.String(inputVariable(name)).pipe(Config.mapEffect((raw) => {
@@ -247,10 +237,8 @@ var ActionInput = class ActionInput {
 	* @remarks
 	* A JSON array (`["a","b"]`), a bullet list (`- a` or `* a`), or comma- and
 	* newline-separated values, with full-line `#` comments dropped — any
-	* combination of these in the same input. Each shape was reinvented
-	* independently by a consumer (one a bullet-list-and-JSON parser, the other
-	* comment-stripping); accepting the union means a workflow author's first
-	* guess works and nothing either prior consumer relied on regresses.
+	* combination of these in the same input — so a workflow author's first
+	* guess works.
 	*
 	* Parsing order, applied per newline/comma-separated item after trimming:
 	*
@@ -297,9 +285,9 @@ var ActionInput = class ActionInput {
 	* Only the **first** `=` splits, so a value may contain one.
 	*
 	* An **empty key** (`=value`, or a bare `=`) is always rejected: `{ "": v }`
-	* cannot be what a workflow meant, and the damage lands far from the typo —
-	* an empty key became a repository filter that matched nothing, and the run
-	* reported zero results with no indication why. An empty **value** (`key=`)
+	* cannot be what a workflow meant, and the damage would land far from the
+	* typo — an empty key becomes a filter that matches nothing, and the run
+	* reports zero results with no indication why. An empty **value** (`key=`)
 	* is accepted by default, because setting a property to the empty string is
 	* legitimate; pass `requireValue` to reject it. Every rejection names the
 	* offending line.
@@ -340,9 +328,8 @@ var ActionInput = class ActionInput {
 	*
 	* There is no `schemaOption`: `ActionInput.schema(name, S).pipe(Config.option)`
 	* yields `Config<Option<A>>` with missing → `None` and a malformed value
-	* still failing — core's documented `Config.option` behaviour ("validation
-	* errors ... still propagate", `Config.ts`), which is exactly the
-	* missing-versus-malformed split above.
+	* still failing — core's `Config.option` lets validation errors propagate,
+	* which is exactly the missing-versus-malformed split above.
 	*/
 	static schema(name, schema) {
 		return Config.String(inputVariable(name)).pipe(Config.mapEffect((raw) => {
@@ -362,7 +349,7 @@ var ActionInput = class ActionInput {
 	* The record dual-accepts, and the split is the `INPUT_` prefix:
 	*
 	* - A key already spelled as a runner variable (`INPUT_BIOME-VERSION`,
-	*   `PLAIN_VAR`) is read verbatim, exactly as before.
+	*   `PLAIN_VAR`) is read verbatim.
 	* - Any other key is treated as an **input name**, `with:`-block style —
 	*   `{ "biome-version": "2.3.14" }` — and serves the variable this module
 	*   derives for it (`ActionInput.variable`). This is the spelling to
@@ -379,11 +366,10 @@ var ActionInput = class ActionInput {
 	* installs ({@link ActionInput.providerOver} via `layerDefault`) — so a
 	* bare `Config.String("biome-version")` resolves under this provider
 	* exactly as it does inside `Action.run`. Nested and numeric paths pass
-	* through as the joined spelling only, as ever.
+	* through as the joined spelling only.
 	*
-	* The source package's `ActionsConfigProvider` behaviors are otherwise
-	* preserved exactly: the path is joined with `_`, spaces become underscores
-	* and the whole is uppercased; and an **empty string reads as absent**,
+	* Otherwise the path is joined with `_`, spaces become underscores and the
+	* whole is uppercased; and an **empty string reads as absent**,
 	* because the runner sets unsupplied inputs to `""` and treating that as
 	* present would make every optional input look supplied. That rule applies
 	* to input-name entries too: `{ "flag": "" }` is an unsupplied input.
@@ -401,9 +387,7 @@ var ActionInput = class ActionInput {
 	* `TARGET-BRANCH`, never matches, and the read falls through to whatever
 	* default the call site supplies. It **fails green**: nothing errors, the
 	* suite passes against the default, and the test's name claims it proved the
-	* input was read. A consuming action's integration harness did exactly this
-	* and stayed green across several commits while a supplied `target-branch`
-	* silently did nothing.
+	* input was read.
 	*
 	* Runner-variable keys (`INPUT_TARGET-BRANCH`, `PLAIN_VAR`) are unaffected —
 	* they are already in the spelling `fromEnv` produces, and they resolve. The
@@ -437,9 +421,8 @@ var ActionInput = class ActionInput {
 	* A layer installing {@link ActionInput.provider}.
 	*
 	* @remarks
-	* `ConfigProvider.ConfigProvider` is a `Context.Reference` in v4, so this is
-	* a reference override rather than a service — there is no
-	* `Effect.withConfigProvider`.
+	* `ConfigProvider.ConfigProvider` is a `Context.Reference`, so this is a
+	* reference override rather than a service.
 	*
 	* A parameterized layer factory mints a fresh reference per call; bind it to
 	* a `const` rather than calling it at each composition site.
@@ -459,10 +442,9 @@ var ActionInput = class ActionInput {
 	* passed to `ambient` untouched, so no path semantics are invented that the
 	* runner does not have.
 	*
-	* This exists because a live action shipped a **false green**: every bare
-	* `Config` read fell back to its `withDefault` because the runner exposes
-	* inputs as `INPUT_<MANGLED>` variables and a plain-named lookup finds
-	* nothing. Under this provider a bare read resolves through the same
+	* This exists because the runner exposes inputs as `INPUT_<MANGLED>`
+	* variables, so a plain-named lookup finds nothing and a bare `Config` read
+	* would silently fall back to its `withDefault`. Under this provider a bare read resolves through the same
 	* derivation `ActionInput.string` uses, so side-stepping the typed accessors
 	* degrades to the right answer instead of to the default.
 	*
@@ -518,7 +500,7 @@ var ActionInput = class ActionInput {
 	* `ActionInput.provider` dual-accepts both spellings, so neither can miss.
 	*
 	* When none is installed, a **fresh** `ConfigProvider.fromEnv()`
-	* is built rather than reading the reference's default: v4 caches that
+	* is built rather than reading the reference's default: core caches that
 	* default once per process, and a snapshot taken before the runner's
 	* variables are visible would resurrect exactly the missed-input class this
 	* layer exists to kill. An action's environment is fixed before the process

package/ActionLogger.js

@@ -1,5 +1,5 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
-import { WorkflowCommand } from "./WorkflowCommand.js";
+import { CommandNeutralizer, WorkflowCommand } from "@effected/github-commands";
 import { Console, Context, Effect, Exit, Inspectable, Layer, LogLevel, Logger, References } from "effect";
 
 //#region src/ActionLogger.ts
@@ -67,7 +67,11 @@ const annotationRecord = (properties) => ({ ...properties });
 * @remarks
 * `Info` is deliberately plain text with no command prefix — it is ordinary
 * step output, and prefixing it would make every informational line an
-* annotation in the workflow summary.
+* annotation in the workflow summary. It is neutralized, though: the text is
+* whatever the program logged, and the runner reads every line of stdout, so a
+* message carrying `::add-mask::` or a `##[` would be a command. The levels that
+* render AS a command escape their data instead, and a line that starts `::` is
+* read by the runner as that command alone.
 */
 const renderEntry = (level, message, annotations) => {
 	const text = formatMessage(message);
@@ -75,7 +79,7 @@ const renderEntry = (level, message, annotations) => {
 		const properties = readAnnotations(annotations);
 		return LogLevel.isGreaterThanOrEqualTo(level, "Error") ? WorkflowCommand.error(text, properties) : WorkflowCommand.warning(text, properties);
 	}
-	return LogLevel.isGreaterThanOrEqualTo(level, "Info") ? text : WorkflowCommand.debug(text);
+	return LogLevel.isGreaterThanOrEqualTo(level, "Info") ? CommandNeutralizer.text(text) : WorkflowCommand.debug(text);
 };
 /** The line the runner should see for one log event, with the fiber's annotations. */
 const renderLogger = Logger.make((options) => renderEntry(options.logLevel, options.message, options.fiber.getRef(References.CurrentLogAnnotations)));
@@ -106,7 +110,7 @@ const flush = (state) => Effect.suspend(() => {
 		`--- End buffered output for "${state.label}" ---`
 	];
 	state.entries.length = 0;
-	return Effect.forEach(body, (line) => Console.log(line), { discard: true });
+	return Effect.forEach(body, (line) => Console.log(CommandNeutralizer.text(line)), { discard: true });
 });
 const make = Effect.gen(function* () {
 	const env = yield* ActionEnvironment;
@@ -130,7 +134,7 @@ const make = Effect.gen(function* () {
 	return {
 		group: (name, effect) => Effect.acquireUseRelease(Console.log(WorkflowCommand.group(name)), () => Effect.tapCause(effect, () => flushActive), () => Console.log(WorkflowCommand.endGroup())),
 		withBuffer,
-		withStep: (name, effect, options) => withBuffer(name, Effect.tapCause(effect, () => Console.log(`❌ ${name}`)), { onSuccess: "discard" }).pipe(Effect.tap(() => Effect.logInfo(options?.summary ?? `✅ ${name}`))),
+		withStep: (name, effect, options) => withBuffer(name, Effect.tapCause(effect, () => Console.log(CommandNeutralizer.text(`❌ ${name}`))), { onSuccess: "discard" }).pipe(Effect.tap(() => Effect.logInfo(options?.summary ?? `✅ ${name}`))),
 		notice: (message, properties = {}) => Console.log(WorkflowCommand.notice(message, properties)),
 		annotated: (properties, effect) => Effect.annotateLogs(effect, annotationRecord(properties))
 	};
@@ -159,6 +163,14 @@ const make = Effect.gen(function* () {
 * @public
 */
 var ActionLogger = class ActionLogger extends Context.Service()("@effected/github-actions/ActionLogger") {
+	/**
+	* The service: groups, the buffered step renderer, notices and annotations.
+	*
+	* @remarks
+	* This installs no `Logger`. Without {@link ActionLogger.layerLogger} (or `Action.run`, which installs it) Effect's
+	* default logger writes `Effect.log*` text raw, so a message carrying `::add-mask::` or `##[` is a workflow command
+	* to the runner. Install both: the service for its structure, the logger for its neutralizing of every log line.
+	*/
 	static layer = Layer.effect(this, make);
 	/**
 	* The `Logger` that maps Effect log levels onto workflow commands.
@@ -172,7 +184,13 @@ var ActionLogger = class ActionLogger extends Context.Service()("@effected/githu
 	* observable in a test without a runner.
 	*/
 	static logger = commandLogger;
-	/** {@link ActionLogger.logger} installed as the only logger. */
+	/**
+	* {@link ActionLogger.logger} installed as the only logger.
+	*
+	* @remarks
+	* Bound to a constant so every composition site shares one layer;
+	* `ActionRuntime.layer` already includes it.
+	*/
 	static layerLogger = Logger.layer([ActionLogger.logger]);
 	/**
 	* A silent double.
@@ -198,10 +216,9 @@ var ActionLogger = class ActionLogger extends Context.Service()("@effected/githu
 	* A silent service **and** a silent `Effect.log*`.
 	*
 	* @remarks
-	* This one layer replaces the bare `Effect.provide(Logger.layer([]))` that
-	* appeared thirteen times in one consuming action and twenty-three in
-	* another, purely to keep test output quiet. Bound to a constant rather than
-	* exposed as a factory, so composing it twice is free.
+	* This one layer stands in for a bare `Effect.provide(Logger.layer([]))`
+	* repeated in every suite just to keep test output quiet. Bound to a
+	* constant rather than exposed as a factory, so composing it twice is free.
 	*/
 	static layerSilent = Layer.mergeAll(ActionLogger.layerTest(), Logger.layer([]));
 };

package/ActionOutputs.js

@@ -1,7 +1,7 @@
 import { ActionEnvironment } from "./ActionEnvironment.js";
-import { WorkflowCommand } from "./WorkflowCommand.js";
 import { heredocBlock, isUsableName } from "./internal/runnerFile.js";
 import { unstubbed } from "./internal/unstubbed.js";
+import { CommandNeutralizer, WorkflowCommand } from "@effected/github-commands";
 import { Console, Context, Effect, FileSystem, Layer, Schema } from "effect";
 
 //#region src/ActionOutputs.ts
@@ -180,9 +180,30 @@ const dies = unstubbed("ActionOutputs.makeTest");
 * — that is `Action.run`'s job, so that an action which reports a failure and
 * then recovers is not silently doomed by a side effect it cannot undo.
 *
+* Members that write a runner file fail with {@link ActionOutputError}.
+*
+* @example
+* ```ts
+* import { ActionOutputs } from "@effected/github-actions";
+* import { Effect, Schema } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const outputs = yield* ActionOutputs;
+*   yield* outputs.set("version", "1.2.3");
+*   yield* outputs.setJson("packages", ["a", "b"], Schema.Array(Schema.String));
+* });
+* ```
+*
 * @public
 */
 var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/github-actions/ActionOutputs") {
+	/**
+	* The live service, appending to the runner's `GITHUB_OUTPUT`, `GITHUB_ENV`,
+	* `GITHUB_PATH` and `GITHUB_STEP_SUMMARY` files.
+	*
+	* @remarks
+	* `ActionRuntime.layer` already provides every requirement.
+	*/
 	static layer = Layer.effect(this, make);
 	/**
 	* The outputs surface that is correct inside a **detached worker**.
@@ -192,10 +213,8 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 	* stdout is a **log file no runner parses**, so under the real layer
 	* `setSecret` emits `::add-mask::<plaintext>` into that file — a command
 	* that is simultaneously **inert** (nothing reads it, so nothing is masked)
-	* and a **secret leak** (the plaintext is now sitting verbatim in a log). A
-	* production action shipped exactly that for one round: an S3 secret and
-	* session token written into a worker's log by the masking call itself.
-	* This layer is the worker-side fix; the parent-side rule is that every
+	* and a **secret leak** (the plaintext is now sitting verbatim in a log).
+	* This layer is the worker-side guard; the parent-side rule is that every
 	* secret a worker will hold is masked **before** the spawn, by
 	* `Secret.forChildEnv` under the real layer.
 	*
@@ -208,7 +227,7 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 	*   spelling of it in the log IS the leak. Masking is the parent's job,
 	*   before the worker exists.
 	* - **`set`, `setJson`, `exportVariable`, `addPath`, `summary` — fail
-	*   typed** (`reason: "detached"`, naming the file). Each writes a runner
+	*   typed** with {@link DetachedOutputError}, naming the file. Each writes a runner
 	*   file that configures the parent job's *later steps* — `GITHUB_OUTPUT`,
 	*   `GITHUB_ENV`, `GITHUB_PATH` — or is collected when the step completes
 	*   (`GITHUB_STEP_SUMMARY`). A detached worker has no later steps, may
@@ -237,7 +256,7 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 			name
 		})),
 		addPath: () => Effect.fail(new DetachedOutputError({ file: RUNNER_FILE.addPath })),
-		setFailed: (message) => Console.error(message),
+		setFailed: (message) => Console.error(CommandNeutralizer.text(message)),
 		setSecret: () => Effect.void
 	});
 	/**
@@ -277,7 +296,7 @@ var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/git
 	* @remarks
 	* This is the double most tests of an action want — "what did it publish?"
 	* — shipped so that nobody hand-writes a `setJson` override that drops the
-	* schema encode (the trap `makeTest` now closes too). `setJson` encodes
+	* schema encode (a trap `makeTest` closes too). `setJson` encodes
 	* through its schema exactly as the real layer does, failing typed with
 	* {@link OutputEncodeError} and recording nothing on a drift, and records
 	* the **encoded JSON text** — what the runner would have read — not the

package/ActionState.js

@@ -6,7 +6,8 @@ import { Context, Effect, FileSystem, Layer, Option, Schema } from "effect";
 
 //#region src/ActionState.ts
 /**
-* Raised when state cannot cross the phase boundary.
+* Raised when action state cannot be saved, read or decoded across the phase
+* boundary.
 *
 * @public
 */
@@ -26,7 +27,9 @@ var ActionStateError = class extends Schema.TaggedError()("ActionStateError", {
 		"notPlainJson",
 		"writeFailed"
 	]),
+	/** The state key that was being saved or read. */
 	key: Schema.String,
+	/** The underlying failure, preserved structurally. */
 	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
@@ -110,11 +113,37 @@ const dies = unstubbed("ActionState.makeTest");
 * write-only file (`GITHUB_STATE`) whose entries the runner republishes to the
 * next phase as `STATE_<key>` environment variables — so saving and reading go
 * through different mechanisms, which is why this is a service rather than a
-* pair of helpers.
+* pair of helpers. Every member fails with {@link ActionStateError}.
+*
+* @example
+* ```ts
+* import { ActionState } from "@effected/github-actions";
+* import { Effect, Schema } from "effect";
+*
+* // in `pre`
+* const pre = Effect.gen(function* () {
+*   const state = yield* ActionState;
+*   yield* state.save("server-pid", 4242, Schema.Number);
+* });
+*
+* // in `post`
+* const post = Effect.gen(function* () {
+*   const state = yield* ActionState;
+*   const pid = yield* state.get("server-pid", Schema.Number);
+*   return pid;
+* });
+* ```
 *
 * @public
 */
 var ActionState = class ActionState extends Context.Service()("@effected/github-actions/ActionState") {
+	/**
+	* The live service, writing to the runner's `GITHUB_STATE` file and reading
+	* the `STATE_<key>` variables it republishes.
+	*
+	* @remarks
+	* `ActionRuntime.layer` already provides every requirement.
+	*/
 	static layer = Layer.effect(this, make);
 	/** A test double. Unstubbed members die rather than answering wrongly. */
 	static makeTest = (overrides = {}) => ({

package/ActionsIdentityToken.js

@@ -4,7 +4,8 @@ import { IdentityToken, IdentityTokenError } from "@effected/sbom";
 
 //#region src/ActionsIdentityToken.ts
 /**
-* The Actions side of `@effected/sbom`'s inverted OIDC contract.
+* Serves `@effected/sbom`'s `IdentityToken` contract from the runner's own OIDC
+* token service, so signing an SBOM inside a workflow needs no further wiring.
 *
 * @remarks
 * `@effected/sbom` declares `IdentityToken` — one method, one audience,

package/ActionsProvenance.js

@@ -15,7 +15,8 @@ import { SlsaProvenance } from "@effected/sbom";
 */
 const DEFAULT_SERVER_URL = "https://github.com";
 /**
-* The Actions side of `@effected/sbom`'s SLSA provenance constructor.
+* Builds the current run's SLSA provenance from the runner's OIDC claims: the
+* Actions side of `@effected/sbom`'s `SlsaProvenance.forGitHubWorkflow`.
 *
 * @remarks
 * `SlsaProvenance.forGitHubWorkflow` is total and does the real work, but it

package/Artifact.js

@@ -352,14 +352,10 @@ const dies = unstubbed("Artifact.makeTest");
 * third thing that can be absent, and it is reported as `misconfigured` for the
 * same reason.
 *
-* **This surface is provisional.** Unlike every other service here it was
-* ported without a call site to shape it against, so it keeps the source's
-* shape rather than a narrower one invented from nothing. The first consumer to
-* adopt it is the one whose feedback reshapes it — the members lost their
-* `Artifact` prefix (`artifact.uploadArtifact(...)` stutters) and the
-* cross-run `findBy` lookup is **not** ported, because every path through it in
-* the source is a typed "not implemented" failure. Adding it later is additive;
-* shipping a parameter that has never had behavior is not.
+* **This surface is provisional.** It has not yet been shaped by a real call
+* site, so it may be reworked once a consumer adopts it. It covers the current
+* run only: there is no cross-run lookup, and adding one later would be
+* additive.
 *
 * @example
 * ```ts