@effected/github-actions 0.2.0 → 0.4.0

package/index.d.ts

@@ -4,6 +4,7 @@ import { HttpClient } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { IdentityToken, SlsaProvenance } from "@effected/sbom";
 import { BotIdentity, GitHubApp, GitHubClient, InstallationToken, PermissionLevel, RetryPolicy } from "@effected/github";
+import { PackageManagerPin } from "@effected/npm";
 //#region src/ActionEnvironment.d.ts
 declare const ActionEnvironmentError_base: Schema.Class<ActionEnvironmentError, Schema.TaggedStruct<"ActionEnvironmentError", {
   readonly reason: Schema.Literals<readonly ["missing", "malformed"]>;
@@ -35,6 +36,22 @@ declare const GitHubContext_base: Schema.Class<GitHubContext, Schema.Struct<{
   readonly ref: Schema.String;
   /** The short ref, e.g. `main`. */
   readonly refName: Schema.String;
+  /**
+   * The source branch of the pull request, when the event has one.
+   *
+   * @remarks
+   * `GITHUB_HEAD_REF` is only set for `pull_request` events — and on every
+   * other event the runner does not merely omit it, it may write the **empty
+   * string**, which a raw `process.env` read happily reports as present. That
+   * trap is encoded in the type: absent and `""` both decode to
+   * `Option.none()`, so a consumer cannot build a cache key segment out of an
+   * empty branch name by accident. For "the branch a human means", use
+   * {@link GitHubContext.branch}, which owns the fallback to `refName`.
+   *
+   * The encoded form is `string | null` rather than a serialized `Option`, so
+   * an encoded context stays plain JSON.
+   */
+  readonly headRef: Schema.OptionFromNullOr<Schema.String>;
   readonly sha: Schema.String;
   readonly workflow: Schema.String;
   readonly job: Schema.String;
@@ -52,7 +69,20 @@ declare const GitHubContext_base: Schema.Class<GitHubContext, Schema.Struct<{
  *
  * @public
  */
-declare class GitHubContext extends GitHubContext_base {}
+declare class GitHubContext extends GitHubContext_base {
+  /**
+   * The branch a human means: `headRef` when present (a pull request, where
+   * `refName` is the useless `123/merge`), otherwise `refName`.
+   *
+   * @remarks
+   * This is the universal branch-scoped-cache-key fallback chain, written
+   * once. On a `push` or any other non-PR event `headRef` is `Option.none()`
+   * — including when the runner wrote it as the empty string — so the answer
+   * is the short ref. Note that on a tag push `refName` names the tag, not a
+   * branch; a consumer that must distinguish still has the full `ref`.
+   */
+  get branch(): string;
+}
 declare const RunnerContext_base: Schema.Class<RunnerContext, Schema.Struct<{
   readonly os: Schema.String;
   readonly arch: Schema.String;
@@ -373,9 +403,11 @@ declare const ActionOutputError_base: Schema.Class<ActionOutputError, Schema.Tag
    * the code is running outside a GitHub runner. `writeFailed` — the file
    * exists but could not be appended to. `invalidName` — the name would
    * corrupt the file's block structure. `encodeFailed` — a value did not
-   * satisfy its schema.
+   * satisfy its schema. `detached` — the member was called under
+   * {@link ActionOutputs.layerDetached}, where the channel it writes cannot
+   * reach the job that would read it.
    */
-  readonly reason: Schema.Literals<readonly ["unavailable", "writeFailed", "invalidName", "encodeFailed"]>;
+  readonly reason: Schema.Literals<readonly ["unavailable", "writeFailed", "invalidName", "encodeFailed", "detached"]>;
   /** Which runner file was involved, by environment variable name. */
   readonly file: Schema.optionalKey<Schema.String>;
   /** The output or variable name, when one is involved. */
@@ -405,7 +437,17 @@ interface ActionOutputsShape {
   readonly summary: (content: string) => Effect.Effect<void, ActionOutputError>;
   /** Export an environment variable to **subsequent** steps. */
   readonly exportVariable: (name: string, value: string) => Effect.Effect<void, ActionOutputError>;
-  /** Prepend a directory to `PATH` for subsequent steps. */
+  /**
+   * Prepend a directory to `PATH` for **subsequent** steps.
+   *
+   * @remarks
+   * This appends to the `GITHUB_PATH` runner file and does **nothing else** —
+   * unlike `@actions/core`, it does NOT mutate the live `process.env.PATH` of
+   * the current process. A same-process probe of a tool that was just added
+   * (`pnpm --version`, a shim, a binary) will not find it by name; probe by
+   * absolute path instead. The runner applies the addition when the next step
+   * starts, exactly as it does for {@link ActionOutputsShape.exportVariable}.
+   */
   readonly addPath: (path: string) => Effect.Effect<void, ActionOutputError>;
   /** Emit an error annotation. Does not itself set the exit code. */
   readonly setFailed: (message: string) => Effect.Effect<void>;
@@ -430,6 +472,45 @@ declare const ActionOutputs_base: Context.ServiceClass<ActionOutputs, "@effected
  */
 declare class ActionOutputs extends ActionOutputs_base {
   static readonly layer: Layer.Layer<ActionOutputs, never, ActionEnvironment | FileSystem.FileSystem>;
+  /**
+   * The outputs surface that is correct inside a **detached worker**.
+   *
+   * @remarks
+   * The masking model assumes the runner parses stdout. A detached worker's
+   * 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
+   * secret a worker will hold is masked **before** the spawn, by
+   * `Secret.forChildEnv` under the real layer.
+   *
+   * The layer needs no environment and no filesystem — its `R` is `never` —
+   * so a worker composing it structurally *cannot* write a runner file.
+   * Per-member behavior:
+   *
+   * - **`setSecret` — silent no-op.** The value must not be written
+   *   *anywhere*: there is no runner on this channel to hand it to, and any
+   *   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
+   *   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
+   *   outlive the job entirely, and even an inherited file path would be
+   *   read at a moment unrelated to the write — so a worker calling one of
+   *   these is a program error worth surfacing, not a write to degrade
+   *   silently.
+   * - **`setFailed` — degrades to a plain log line** (`Console.error`,
+   *   without the `::error::` syntax nothing here would parse). Unlike the
+   *   file members it is log-like: "record that something failed" still
+   *   means something in a worker's log, and its signature carries no error
+   *   channel to fail through.
+   */
+  static readonly layerDetached: Layer.Layer<ActionOutputs>;
   /** A test double. Unstubbed members die rather than silently succeeding. */
   static readonly makeTest: (overrides?: Partial<ActionOutputsShape>) => ActionOutputsShape;
   /** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
@@ -441,10 +522,13 @@ declare const ActionStateError_base: Schema.Class<ActionStateError, Schema.Tagge
   /**
    * `missing` — no value was saved under this key in an earlier phase.
    * `malformed` — a value is there but is not JSON, or does not satisfy the
-   * schema it was read with. `writeFailed` — the state file could not be
+   * schema it was read with. `notPlainJson` — caught at SAVE time: the
+   * schema's encoded form does not survive `JSON.stringify`/`JSON.parse`, so
+   * persisting it would present one phase later as a `malformed` mystery with
+   * no pointer to the cause. `writeFailed` — the state file could not be
    * appended to.
    */
-  readonly reason: Schema.Literals<readonly ["missing", "malformed", "writeFailed"]>;
+  readonly reason: Schema.Literals<readonly ["missing", "malformed", "notPlainJson", "writeFailed"]>;
   readonly key: Schema.String;
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
@@ -462,7 +546,24 @@ declare class ActionStateError extends ActionStateError_base {
  * @public
  */
 interface ActionStateShape {
-  /** Persist a value for a later phase. */
+  /**
+   * Persist a value for a later phase.
+   *
+   * @remarks
+   * **The schema's ENCODED form must be plain JSON** — `GITHUB_STATE` is a
+   * text file and the value crosses it as `JSON.stringify(encoded)`. A schema
+   * whose encoded side is a class instance (`Schema.Option`'s is an `Option`,
+   * serialized via its `toJSON` to `{"_id":"Option",…}`) writes something no
+   * later phase can decode; use the plain-JSON codec instead —
+   * `Schema.OptionFromNullOr` for an optional value.
+   *
+   * Every save proves the rule: the encoded value is round-tripped through
+   * `JSON.stringify`/`JSON.parse` and re-decoded, and a value that does not
+   * survive fails HERE, typed (`reason: "notPlainJson"`, naming the key) —
+   * rather than one phase later as a `malformed` mystery in `post` that
+   * `main` believed it saved. Action state is small by protocol, so the
+   * per-save round-trip costs effectively nothing.
+   */
   readonly save: <A, I>(key: string, value: A, schema: Schema.Codec<A, I>) => Effect.Effect<void, ActionStateError>;
   /** Read a value saved by an earlier phase. */
   readonly get: <A, I>(key: string, schema: Schema.Codec<A, I>) => Effect.Effect<A, ActionStateError>;
@@ -709,6 +810,14 @@ declare class CacheKeyError extends CacheKeyError_base {
 declare const CacheKey_base: Schema.Class<CacheKey, Schema.Struct<{
   /** The components, most general first. */
   readonly segments: Schema.NonEmptyArray<Schema.String>;
+  /**
+   * The explicit ladder policy, when one was given: how many leading
+   * segments each rung keeps, in the order the rungs are tried. Absent for
+   * the default every-prefix ladder; **empty for no ladder at all** —
+   * exact-match-only. See {@link CacheKey.withRestoreDepths} and
+   * {@link CacheKey.withoutRestoreKeys}.
+   */
+  readonly restoreDepths: Schema.optionalKey<Schema.$Array<Schema.Number>>;
 }>, {}>;
 /**
  * A GitHub Actions cache key and the restore-key ladder that goes with it.
@@ -721,6 +830,12 @@ declare const CacheKey_base: Schema.Class<CacheKey, Schema.Struct<{
  * the primary key and its fallbacks impossible to drift apart, which is the
  * failure that produces a cache that never hits and never says why.
  *
+ * By default every prefix is a rung. When some segments must never be dropped
+ * — a rung without a version digest resurrects stale cross-version caches —
+ * give the key an explicit ladder policy with
+ * {@link CacheKey.withRestoreDepths}, or none at all with
+ * {@link CacheKey.withoutRestoreKeys}, instead of bypassing the typed key.
+ *
  * @example
  * ```ts
  * import { CacheKey } from "@effected/github-actions";
@@ -739,12 +854,69 @@ declare class CacheKey extends CacheKey_base {
    * The restore keys, most specific first.
    *
    * @remarks
-   * Each rung drops the last segment and keeps the trailing separator, so a
-   * three-segment key falls back to two prefixes and a one-segment key falls
-   * back to nothing — there is no rung that would match every cache in the
-   * repository.
+   * By default each rung drops the last segment and keeps the trailing
+   * separator, so a three-segment key falls back to two prefixes and a
+   * one-segment key falls back to nothing — there is no rung that would match
+   * every cache in the repository.
+   *
+   * **The default ladder is every prefix**, which is wrong for a key whose
+   * later segments must never be dropped alone: a
+   * `platform-arch-versionHash-branchHash-lockfileHash` key derives rungs
+   * without the version digest, and those resurrect stale cross-version
+   * caches. A key built with {@link CacheKey.withRestoreDepths} carries its
+   * own ladder instead, and this getter answers exactly that ladder — so
+   * `ActionCache.restore` picks the policy up through the same typed-key
+   * path, no hand-built restore-key list required. An **empty** policy
+   * ({@link CacheKey.withoutRestoreKeys}) answers no rungs at all: only
+   * *absence* selects the default ladder, so "none" is never mistaken for
+   * "every prefix".
    */
   get restoreKeys(): ReadonlyArray<string>;
+  /**
+   * A copy of this key carrying an explicit restore-key ladder policy.
+   *
+   * @remarks
+   * Each depth is the number of **leading segments** the rung keeps, and the
+   * rungs are emitted in exactly the order given — GitHub tries restore keys
+   * in order, so the order IS the policy. Descending depths (most specific
+   * first) are what a fallback ladder almost always wants; that convention is
+   * recommended rather than enforced, because rung ordering is the consumer's
+   * policy where commas, newlines and the length limit are the runner's
+   * protocol. A depth outside `1..segments.length - 1` is refused at
+   * construction: `0` would match every cache in the repository, and
+   * `segments.length` would just repeat the primary key.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   *
+   * const key = CacheKey.of("Linux", "X64", "v1hash", "main", "lockhash").withRestoreDepths([4, 3]);
+   * key.restoreKeys; // ["Linux-X64-v1hash-main-", "Linux-X64-v1hash-"]
+   * ```
+   */
+  withRestoreDepths(depths: readonly [number, ...Array<number>]): CacheKey;
+  /**
+   * A copy of this key that restores from its **exact key only** — no ladder.
+   *
+   * @remarks
+   * The third point in the policy space, and the one the typed key had no
+   * spelling for: absence of a policy means the default every-prefix ladder,
+   * so exact-match-only restores (a cache-bust mode, where a stale partial
+   * hit is worse than a cold start) previously forced the caller back to the
+   * string form. This is the same `restoreDepths` field carrying **zero
+   * rungs** — an honest value, not a sentinel: `ActionCache.restore` sends no
+   * `restore_keys` at all, so the backend answers this key or a miss.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   *
+   * const key = CacheKey.of("Linux", "pnpm-store", "abc123").withoutRestoreKeys();
+   * key.key;          // "Linux-pnpm-store-abc123"
+   * key.restoreKeys;  // []
+   * ```
+   */
+  withoutRestoreKeys(): CacheKey;
   /** Build a key from its segments. */
   static of(...segments: readonly [string, ...ReadonlyArray<string>]): CacheKey;
   /**
@@ -772,6 +944,44 @@ declare class CacheKey extends CacheKey_base {
     /** The content hash, e.g. from {@link CacheKey.hashFiles}. Included last when given. */
     readonly hash?: string;
   }): CacheKey;
+  /**
+   * A segment-safe short digest of a string.
+   *
+   * @remarks
+   * {@link CacheKey.hashFiles} covers file *content*; this covers the key
+   * segments built from **non-file** inputs — a sorted version list, a branch
+   * name — that every compound key hashes and truncates by hand, each caller
+   * re-deciding the length and the placement. One home for the derivation:
+   * SHA-256, lowercase hex, the first `length` characters.
+   *
+   * The answer is **guaranteed to satisfy the segment grammar**: lowercase hex
+   * is nonempty (for any permitted `length`) and can never contain the comma
+   * or newline the restore-key protocol reserves, so the result drops straight
+   * into {@link CacheKey.of} with nothing to check at the call site.
+   *
+   * Deterministic and pure — the same input always answers the same digest,
+   * which is the entire point of putting one in a cache key. Distinct inputs
+   * are only *probably* distinct, as with any truncated hash; eight hex
+   * characters (32 bits) is the conventional balance between key legibility
+   * and collision risk for cache segments.
+   *
+   * A `length` outside `1..64` (or a fractional one) is a wiring mistake, not
+   * data, and **throws a `RangeError`** rather than failing typed: 64 is all
+   * SHA-256 has, and asking for more would silently answer fewer characters
+   * than the caller believes it got.
+   *
+   * @example
+   * ```ts
+   * import { CacheKey } from "@effected/github-actions";
+   *
+   * const key = CacheKey.of(
+   *   "Linux",
+   *   CacheKey.digest("node:24.4.0,pnpm:10.13.1"),
+   *   CacheKey.digest("feat/my-branch"),
+   * );
+   * ```
+   */
+  static digest(input: string, length?: number): string;
   /**
    * Hash a set of files into a single digest.
    *
@@ -890,9 +1100,31 @@ declare class ActionCacheError extends ActionCacheError_base {
  */
 interface ActionCacheShape {
   /**
-   * Archive `paths` and store them under `key`.
+   * Archive the files and directories matching `paths` and store them under
+   * `key`.
    *
    * @remarks
+   * `paths` is a list of glob **patterns**, resolved with `actions/cache`
+   * parity before `tar` ever sees them: a pattern may match directories (a
+   * matched directory is archived recursively, never expanded into its
+   * descendants), a pattern that matches nothing — including a literal path
+   * that is not on disk — is silently dropped, and a list that resolves to
+   * nothing at all fails typed rather than reserving an entry no archive will
+   * ever back. A leading `~` expands to the caller's home directory, relative
+   * patterns root at `GITHUB_WORKSPACE` (falling back to the working
+   * directory), and a leading `!` marks an exclusion.
+   *
+   * The entry **version** is a digest of the literal pattern list, exactly as
+   * `actions/cache` computes it — resolution feeds `tar` only, never the
+   * version — so {@link ActionCacheShape.restore | restore}, which resolves
+   * nothing, derives the same version from the same list for free.
+   *
+   * One deliberate divergence from the toolkit: where `actions/cache` re-roots
+   * every match relative to the workspace, resolved paths here stay
+   * **absolute** and are archived with `tar -P`, so a restore puts every file
+   * back where it came from regardless of the restoring step's working
+   * directory.
+   *
    * A key that already exists is a **success**: cache entries are immutable, so
    * another job having written it first is the outcome the caller wanted.
    */
@@ -905,6 +1137,11 @@ interface ActionCacheShape {
    * `Option.none()` is a miss, not a failure — a cold cache is the normal state
    * of a new branch. Passing a {@link CacheKey} supplies its restore-key ladder
    * automatically; passing a `string` and no ladder means "this key or nothing".
+   *
+   * `paths` only derives the entry version and MUST be the same literal list
+   * the save used — no glob resolution happens here, because none is needed:
+   * extraction consumes no path list (the archive already names its contents),
+   * and `actions/cache` likewise hashes the un-resolved list on both sides.
    */
   readonly restore: (paths: ReadonlyArray<string>, key: string | CacheKey, restoreKeys?: ReadonlyArray<string>) => Effect.Effect<Option.Option<string>, ActionCacheError>;
 }
@@ -1011,6 +1248,21 @@ declare class ActionCache extends ActionCache_base {
  */
 declare class ActionInput {
   private constructor();
+  /**
+   * The exact environment variable the runner publishes an input under.
+   *
+   * @remarks
+   * `variable("biome-version")` is `"INPUT_BIOME-VERSION"` — GitHub
+   * uppercases, replaces **spaces** with underscores, and leaves every other
+   * character (**dashes included**) alone. This is the same derivation every
+   * accessor on this class resolves through, exported so a test that must
+   * spell a runner variable can derive it instead of hand-writing it: a
+   * hand-written `INPUT_BIOME_VERSION` reads as absent on a real runner, the
+   * default silently applies, and the suite goes green against the wrong
+   * value. Prefer keying the test environment by input name (see
+   * {@link ActionInput.provider}) so no variable is spelled at all.
+   */
+  static readonly variable: (name: string) => string;
   /**
    * A required string input.
    *
@@ -1120,14 +1372,37 @@ declare class ActionInput {
    */
   static schema<A, I>(name: string, schema: Schema.Codec<A, I>): Config.Config<A>;
   /**
-   * A `ConfigProvider` over a record of runner variables.
+   * A `ConfigProvider` over a record of runner variables **or input names**.
    *
    * @remarks
-   * Subsumes the source package's free-standing `ActionsConfigProvider`, whose
-   * three behaviors are preserved exactly: 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.
+   * 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.
+   * - 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
+   *   prefer in tests: a hand-written `INPUT_BIOME_VERSION` (underscore where
+   *   the runner keeps the dash) reads as absent and the default silently
+   *   applies, and the input-name form makes that class of bug
+   *   unrepresentable — the mangling never leaves this module.
+   *
+   * When both spellings of the same input are present and non-empty, the
+   * explicit `INPUT_`-spelled entry wins.
+   *
+   * A **flat single-segment** lookup additionally tries the `INPUT_`
+   * derivation of the name first, mirroring the order the production runtime
+   * 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.
+   *
+   * 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**,
+   * 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.
    *
    * Taking the environment as an argument rather than reading `process.env`
    * is what makes inputs testable without mutating the test process.
@@ -2214,6 +2489,152 @@ type CheckRunProjection = {
  */
 declare const projectCheckState: (state: CheckState) => CheckRunProjection;
 //#endregion
+//#region src/ChildEnv.d.ts
+/**
+ * The environment additions {@link ChildEnv.prependPath} builds: exactly one
+ * entry, keyed by the spelling of `PATH` the base environment already uses.
+ *
+ * @public
+ */
+interface PathPrependEnv {
+  /** The additions to hand a child, ready to merge over the parent's block. */
+  readonly env: Readonly<Record<string, string>>;
+  /**
+   * Always `true`, and part of the answer on purpose: `env` **without**
+   * `extendEnv: true` silently replaces the child's entire environment with
+   * this one entry. See {@link ChildEnv.prependPath}.
+   */
+  readonly extendEnv: true;
+}
+/**
+ * What {@link ChildEnv.prependPath} derives the additions from.
+ *
+ * @public
+ */
+interface PathPrependOptions {
+  /**
+   * The environment the child will inherit — on a runner, `process.env`.
+   *
+   * @remarks
+   * Explicit rather than defaulted, matching this package's rule that ambient
+   * process state is never read behind a caller's back — which is also what
+   * makes the Windows casing branch exercisable from a test on any host.
+   */
+  readonly base: Readonly<Record<string, string | undefined>>;
+  /**
+   * The platform the child runs on, `process.platform`-shaped. Decides the
+   * `PATH` entry delimiter: `;` on `win32`, `:` everywhere else.
+   */
+  readonly platform: string;
+}
+/**
+ * Child-process environment construction: prepending directories to `PATH`
+ * without falling into the three traps that each cost a real consumer a
+ * cross-OS matrix round.
+ *
+ * @remarks
+ * Spawning a child with directories prepended to `PATH` is one tiny concern
+ * with three sharp edges, and every one of them fails silently or only on
+ * Windows:
+ *
+ * 1. **`env` without `extendEnv: true` strips the child's environment.**
+ *    Core's `ChildProcess.CommandOptions.env` *replaces* the block unless
+ *    `extendEnv` says to merge, so a bare `{ env }` costs the child everything
+ *    — including the very `PATH` being extended.
+ * 2. **Windows spells it `Path`, and casing decides who wins.** The
+ *    environment block is case-insensitive on win32, and Node de-duplicates a
+ *    merged block by keeping the **lexicographically first** spelling — an
+ *    undocumented internal that happens to favour `PATH` over an inherited
+ *    `Path`, and that nothing obliges Node to keep. Writing through the
+ *    inherited key's own casing means never depending on it.
+ * 3. **`.cmd` shims need a shell since CVE-2024-27980.** See
+ *    {@link ChildEnv.needsShell}.
+ *
+ * The first two live in {@link ChildEnv.prependPath}; the third is a separate
+ * predicate because it belongs on the spawn call, not in the environment.
+ *
+ * This class is total and pure — no service, no `R`, nothing read from the
+ * ambient process — the same species as `Secret`'s statics, one concern per
+ * member.
+ *
+ * @public
+ */
+declare class ChildEnv {
+  private constructor();
+  /**
+   * The key `base` spells `PATH` with — `Path` on a typical Windows block,
+   * `PATH` elsewhere, and `PATH` when the base has no entry at all.
+   *
+   * @remarks
+   * The lookup is case-insensitive because the Windows environment block is;
+   * the answer preserves the base's own casing because that is the spelling a
+   * merged block must write through (trap 2 above).
+   */
+  static pathKeyOf(base: Readonly<Record<string, string | undefined>>): string;
+  /**
+   * The environment additions that prepend `dirs` to the child's `PATH`,
+   * paired with the `extendEnv: true` that keeps them a *prepend*.
+   *
+   * @remarks
+   * `dirs` are joined ahead of the inherited value **in the order given** —
+   * order is the caller's policy, because the first directory wins any name
+   * collision (a package manager's shim directory leads so it beats a runtime
+   * of the same name). The entry is written under the base's own `PATH`
+   * spelling ({@link ChildEnv.pathKeyOf}), so a Windows child never receives
+   * `PATH` beside its inherited `Path`. An absent or empty inherited value
+   * appends nothing — deliberately not an empty trailing entry, which both
+   * platforms historically read as "the current directory".
+   *
+   * Two consumers, two compositions, and the difference is exactly trap 1:
+   *
+   * - A spawner call takes the **whole pair** — spread it into the command
+   *   options, as in the example below, so the `extendEnv: true` that makes
+   *   `env` a merge rather than a replacement cannot be forgotten.
+   * - An API that already merges additions over the parent itself —
+   *   `DetachedProcess.spawn`, whose `env` is documented as merged — takes
+   *   `.env` alone; `extendEnv` would be meaningless there.
+   *
+   * On a runner, pass `{ base: process.env, platform: process.platform }`.
+   *
+   * @example
+   * ```ts
+   * import { ChildEnv } from "@effected/github-actions";
+   * import { ChildProcess } from "effect/unstable/process";
+   *
+   * const command = ChildProcess.make("pnpm", ["install"], {
+   *   ...ChildEnv.prependPath(["/opt/hostedtoolcache/pnpm/10.13.1/x64/bin"], {
+   *     base: process.env,
+   *     platform: process.platform,
+   *   }),
+   *   ...(ChildEnv.needsShell(process.platform) ? { shell: true } : {}),
+   * });
+   * ```
+   */
+  static prependPath(dirs: readonly [string, ...ReadonlyArray<string>], options: PathPrependOptions): PathPrependEnv;
+  /**
+   * Whether a bare-name command must be launched through a shell on this
+   * platform.
+   *
+   * @remarks
+   * On Windows every npm-installed tool on `PATH` is a `.cmd` batch shim, not
+   * an executable: `CreateProcess` cannot run one, and since CVE-2024-27980
+   * Node refuses to hand `.cmd`/`.bat` files to it at all unless a shell is
+   * asked for — so the spawn fails at launch, before the tool ever runs.
+   * Under `shell: true`, `cmd.exe` resolves the bare name off the **child's**
+   * `PATH` — the one {@link ChildEnv.prependPath} builds — through `PATHEXT`,
+   * where `.EXE` precedes `.CMD`, so a real binary of the same name is still
+   * found first and the prepends keep working exactly as they do without a
+   * shell.
+   *
+   * POSIX answers `false`: the direct spawn already works, and a shell would
+   * only add a quoting hazard between the caller and the exit code. Note the
+   * hazard `true` carries: under a shell Node concatenates the command line
+   * rather than passing an argv, so arguments must be static literals, never
+   * derived from input.
+   */
+  static needsShell(platform: string): boolean;
+}
+//#endregion
 //#region src/DetachedProcess.d.ts
 declare const DetachedProcessError_base: Schema.Class<DetachedProcessError, Schema.TaggedStruct<"DetachedProcessError", {
   /**
@@ -3079,106 +3500,6 @@ declare class ManagedDocument extends ManagedDocument_base {
   private ensureSentinel;
 }
 //#endregion
-//#region src/Secret.d.ts
-/**
- * The declassification seam: the **only** place in this package where a
- * `Redacted` value becomes a plain string.
- *
- * @remarks
- * Some boundaries cannot carry a `Redacted`. A detached child process reads
- * its configuration from environment variables; `GITHUB_STATE` is a plaintext
- * file by GitHub's protocol. `Redacted` refusing to serialize is the whole
- * value of the type, so this module does not try to make it serializable —
- * it makes declassification **explicit, auditable, and impossible to do
- * quietly**.
- *
- * The invariant: **masking and declassification are the same call.** Every
- * member registers the value with the runner's log filter (`::add-mask::`)
- * *before* returning plaintext, so a secret cannot reach a child's environment
- * or a state file without the runner already knowing to redact it from logs.
- *
- * `Redacted.value` appears nowhere else in this package, and a test asserts
- * that structurally — a reintroduction elsewhere fails the suite rather than
- * review.
- *
- * What this deliberately does **not** do is encrypt the handoff. The child
- * runs on the same runner, as the same user, as the parent; a key would have
- * to travel the same channel as the secret it protects.
- *
- * @example
- * ```ts
- * import { Secret } from "@effected/github-actions";
- * import { Effect } from "effect";
- *
- * const program = Effect.gen(function* () {
- *   const env = yield* Secret.forChildEnv({ MY_TOKEN: theToken });
- *   // every value in `env` is already masked in the runner log
- *   return env;
- * });
- * ```
- *
- * @public
- */
-declare class Secret {
-  private constructor();
-  /**
-   * Declassify a set of secrets for a child process's environment.
-   *
-   * @remarks
-   * Every value is masked before any plaintext is returned — including when
-   * one of them fails, because masking happens for the whole set first.
-   */
-  static readonly forChildEnv: (entries: Readonly<Record<string, Redacted.Redacted<string>>>) => Effect.Effect<Record<string, string>, never, ActionOutputs>;
-  /**
-   * Declassify one secret for a runner file (`GITHUB_STATE`, `GITHUB_OUTPUT`).
-   *
-   * @remarks
-   * Masks first. The runner file is plaintext regardless; the mask is what
-   * keeps the value out of the visible log.
-   */
-  static readonly forRunnerFile: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
-  /**
-   * Declassify one secret for an in-process use that needs the raw bytes.
-   *
-   * @remarks
-   * Request signing is the case this exists for: an HMAC cannot be computed
-   * over a `Redacted`, so a signing key has to become a string somewhere, and
-   * the point of this module is that "somewhere" is here and nowhere else.
-   *
-   * Signing named the member; it does not gate it. **Any in-process use that
-   * needs the raw value without writing it to a runner file is this
-   * operation** — handing a key to a library that takes a plain string. The
-   * dividing line is where the value goes, not what it is for: a value
-   * crossing into a **child's** environment is {@link Secret.forChildEnv},
-   * one written to `GITHUB_STATE` or `GITHUB_OUTPUT` is
-   * {@link Secret.forRunnerFile}, and one that stays in this process is this
-   * member. A third-party SDK that reads only the ambient environment is the
-   * hard case: this package never mutates `process.env` (reads are seeded
-   * once through `ActionEnvironment`), so if a consumer chooses that bridge,
-   * the mutation — and its restore discipline — lives in consumer code as
-   * the consumer's own tradeoff, not as a pattern this member recommends.
-   *
-   * It masks even though the value is never *written* anywhere, and that is
-   * deliberate rather than superstitious: a signing key that leaks does so
-   * through something nobody audited — a debug log of outgoing headers, a
-   * serialized error, a stack trace carrying the closure. Registering it with
-   * the runner's filter costs one call and makes every one of those redacted.
-   *
-   * Call it **once, at layer construction**, not per operation: masking is
-   * idempotent but a workflow command per request is noise in the log.
-   */
-  static readonly forSigning: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
-  /**
-   * The far side of a handoff: re-wrap a plaintext environment variable.
-   *
-   * @remarks
-   * A `Config`, so a missing or empty handoff is an honest `ConfigError`
-   * naming the variable rather than an empty `Redacted` that fails much later
-   * as an authentication error.
-   */
-  static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
-}
-//#endregion
 //#region src/ToolInstaller.d.ts
 declare const ToolInstallerError_base: Schema.Class<ToolInstallerError, Schema.TaggedStruct<"ToolInstallerError", {
   /**
@@ -3222,9 +3543,75 @@ declare class ToolInstallerError extends ToolInstallerError_base {
 interface ExtractOptions {
   /** The destination. A fresh temporary directory when omitted. */
   readonly destination?: string | undefined;
-  /** Flags for `tar`. Defaults to `["xzf"]`, i.e. a gzipped tarball. */
+  /**
+   * Flags for `tar`. Defaults to `["xzf"]`, i.e. a gzipped tarball.
+   *
+   * @remarks
+   * The argv is assembled as `[...flags, archive, "-C", destination]` — the
+   * archive path is appended directly AFTER the flags, so the LAST flag must
+   * be the one that consumes the archive operand. `["xzf"]` works because `f`
+   * is last inside the cluster; a custom set like `["xz", "--strip=1", "-f"]`
+   * must end the same way, deliberately rather than by ordering luck.
+   */
   readonly flags?: ReadonlyArray<string> | undefined;
 }
+/**
+ * How a {@link ToolInstallerShape.download} should behave.
+ *
+ * @public
+ */
+interface ToolDownloadOptions {
+  /**
+   * The overall time budget for ONE download attempt (request plus streaming
+   * the body to disk). Defaults to five minutes.
+   *
+   * @remarks
+   * The default is deliberately generous: toolchain archives run to hundreds
+   * of megabytes, and a healthy runner connection moves tens of megabytes a
+   * second — even a 500 MB archive on a degraded 2 MB/s link fits in five
+   * minutes. What the budget exists for is the connection that stops moving
+   * entirely: without it, a dead connection is a silent CI hang until the job
+   * timeout; with it, the attempt fails typed as `downloadFailed` with no
+   * status — which `retryable` classifies as a transport fault — and the
+   * download's own retry policy tries again.
+   */
+  readonly timeout?: Duration.Input | undefined;
+}
+/**
+ * What {@link ToolInstallerShape.provisionFile} should provision.
+ *
+ * @public
+ */
+interface ProvisionFileOptions {
+  /** The tool-cache name the binary is provisioned under, e.g. `"biome"`. */
+  readonly tool: string;
+  /** The exact version — a tool-cache path segment, so spell it canonically. */
+  readonly version: string;
+  /** The url the binary downloads from on a cache miss. */
+  readonly url: string;
+  /**
+   * The cached file's name — what the tool is invoked as once its directory
+   * is on the `PATH` (e.g. `"biome"`, or `"biome.exe"` on Windows).
+   */
+  readonly binary: string;
+}
+/**
+ * Where {@link ToolInstallerShape.provisionFile} put a single-binary tool.
+ *
+ * @remarks
+ * The same `directory`/`binDir` shape as `PackageManagerInstaller`'s
+ * `CachedPackageManager`, so a consumer publishes either the same way. For a
+ * single binary the two coincide: the cached directory contains exactly the
+ * executable, so it IS the directory to hand to `ActionOutputs.addPath`.
+ *
+ * @public
+ */
+interface ProvisionedFile {
+  /** The cached entry: `<tool-cache>/<tool>/<version>/<arch>`. */
+  readonly directory: string;
+  /** The directory to `addPath` — for a single binary, the cached directory itself. */
+  readonly binDir: string;
+}
 /**
  * The {@link ToolInstaller} service shape.
  *
@@ -3237,10 +3624,20 @@ interface ToolInstallerShape {
    * @remarks
    * Absent is not an error, and neither is an unreadable cache: both mean
    * "install it", which is the only thing a caller can do about either.
+   *
+   * **The tool cache is SHARED.** The hosted runner image pre-populates it and
+   * every `setup-*` action writes into it — this package is a co-writer, not
+   * the owner. A hit guarantees only the `<root>/<tool>/<version>/<arch>`
+   * location contract ({@link ToolInstaller.cachePath}); the directory's
+   * *interior* layout is whatever its writer produced, which is not
+   * necessarily what this consumer's own `cacheDir` would have written.
+   * Validate the layout of a foreign hit before relying on it — applying an
+   * assumption from your own install path (an archive-wrapper subdirectory,
+   * say) to a foreign entry is a real shipped bug.
    */
   readonly find: (tool: string, version: string) => Effect.Effect<Option.Option<string>>;
   /** Download a url to a temporary file, retrying what is worth retrying. */
-  readonly download: (url: string) => Effect.Effect<string, ToolInstallerError>;
+  readonly download: (url: string, options?: ToolDownloadOptions) => Effect.Effect<string, ToolInstallerError>;
   /** Extract a tarball. Returns the directory its contents landed in. */
   readonly extractTar: (archive: string, options?: ExtractOptions) => Effect.Effect<string, ToolInstallerError>;
   /** Extract a zip. Returns the directory its contents landed in. */
@@ -3249,16 +3646,38 @@ interface ToolInstallerShape {
   readonly cacheDir: (source: string, tool: string, version: string) => Effect.Effect<string, ToolInstallerError>;
   /** Install a single file into the tool cache under `name`. Returns the cached directory. */
   readonly cacheFile: (source: string, name: string, tool: string, version: string) => Effect.Effect<string, ToolInstallerError>;
+  /**
+   * Provision a single-binary tool: the whole `find` → `download` →
+   * chmod → `cacheFile` composition as one call.
+   *
+   * @remarks
+   * The one packaged workflow among the primitives, because the single-binary
+   * shape (biome, and every Rust/Go tool distributed as a bare executable) has
+   * no per-tool variation left to compose: there is no archive, so no
+   * extraction and no layout fixup. A cache hit whose entry contains the
+   * named `binary` short-circuits; a hit *missing* it — a foreign or partial
+   * entry, see {@link ToolInstallerShape.find}'s shared-cache warning — is
+   * treated as a miss and reinstalled over, rather than handing back a
+   * directory that cannot run the tool. On the install path the downloaded
+   * file is made executable (`0o755`) BEFORE caching — skipped when
+   * `RUNNER_OS` is Windows, where the bit does not exist — so the cache only
+   * ever contains a runnable tool; a chmod failure is `cacheFailed` with the
+   * file as its subject.
+   */
+  readonly provisionFile: (options: ProvisionFileOptions) => Effect.Effect<ProvisionedFile, ToolInstallerError>;
 }
 declare const ToolInstaller_base: Context.ServiceClass<ToolInstaller, "@effected/github-actions/ToolInstaller", ToolInstallerShape>;
 /**
  * Download, extract and cache a toolchain in the runner's tool cache.
  *
  * @remarks
- * The primitives, not a workflow: a consumer composes `find` → `download` →
- * `extractTar` → `cacheDir` in whatever order its tool needs, because the
- * orders genuinely differ (a single binary skips extraction, a tarball with a
- * nested root directory needs a path fixup between extract and cache).
+ * The primitives, plus exactly one packaged workflow: a consumer composes
+ * `find` → `download` → `extractTar` → `cacheDir` in whatever order its tool
+ * needs, because the orders genuinely differ (a tarball with a nested root
+ * directory needs a path fixup between extract and cache). The one shape with
+ * no per-tool variation — a single bare binary, which skips extraction and
+ * needs only the executable bit — ships whole as
+ * {@link ToolInstallerShape.provisionFile}.
  *
  * No `@actions/tool-cache` dependency — the cache is a directory layout, and
  * this reproduces the layout rather than importing a package to compute it.
@@ -3305,5 +3724,339 @@ declare class ToolInstaller extends ToolInstaller_base {
   static readonly layerTest: (overrides?: Partial<ToolInstallerShape>) => Layer.Layer<ToolInstaller>;
 }
 //#endregion
-export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, ProcessId, type ProvisionOptions, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, WorkflowCommand, describeCause, projectCheckState };
+//#region src/PackageManagerInstaller.d.ts
+declare const PackageManagerInstallerError_base: Schema.Class<PackageManagerInstallerError, Schema.TaggedStruct<"PackageManagerInstallerError", {
+  /**
+   * `downloadFailed`, `extractFailed` and `cacheFailed` mirror the
+   * {@link ToolInstallerError} that caused them, preserved on `cause`
+   * (`cacheFailed` also covers a shim that could not be written into the
+   * entry). `integrityMismatch` — the downloaded artifact does not hash to
+   * what the pin declares; nothing was cached. `integrityMissing` — the pin
+   * carries no integrity and the caller asked for `requireIntegrity`.
+   * `unsupportedPlatform` — bun publishes no build for this runner's
+   * OS/architecture pair. `layoutUnexpected` — the artifact extracted, but
+   * its contents are not shaped like the package manager it claims to be.
+   */
+  readonly reason: Schema.Literals<readonly ["downloadFailed", "extractFailed", "integrityMismatch", "integrityMissing", "unsupportedPlatform", "layoutUnexpected", "cacheFailed"]>;
+  /** The package manager being installed. */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The exact version being installed, in string form. */
+  readonly version: Schema.String;
+  /** What was being worked on — a url, a path, or an OS/arch pair. */
+  readonly subject: Schema.optionalKey<Schema.String>;
+  /** The integrity the pin declares (`<algo>.<hex>`), on a mismatch. */
+  readonly expected: Schema.optionalKey<Schema.String>;
+  /** The integrity the artifact actually hashed to, on a mismatch. */
+  readonly actual: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a package manager cannot be provisioned on the runner.
+ *
+ * @public
+ */
+declare class PackageManagerInstallerError extends PackageManagerInstallerError_base {
+  get message(): string;
+}
+/**
+ * How {@link PackageManagerInstallerShape.install} should behave.
+ *
+ * @public
+ */
+interface PackageManagerInstallOptions {
+  /**
+   * Fail with `integrityMissing` when the pin carries no integrity hash,
+   * instead of proceeding with a logged warning. Off by default, because
+   * in-the-wild `devEngines` pins routinely carry no integrity.
+   */
+  readonly requireIntegrity?: boolean | undefined;
+  /**
+   * The npm registry host the npm, pnpm and yarn tarballs download from.
+   * Defaults to `https://registry.npmjs.org`; a corporate mirror that serves
+   * the standard `/<name>/-/<basename>-<version>.tgz` tarball routes works
+   * unchanged. bun does not ship through a registry — its per-platform zip
+   * always comes from GitHub releases.
+   */
+  readonly registry?: string | undefined;
+  /**
+   * Whether an npm pin may be answered by the runner's own ambient npm.
+   * Defaults to `true`.
+   *
+   * @remarks
+   * Set `false` when the run REPLACES node: a consumer that installs a pinned
+   * node in the same run puts that node's bundled npm ahead of the runner's on
+   * every path that matters afterward (the install child's `PATH`, and every
+   * later workflow step via `GITHUB_PATH`). The ambient probe interrogates the
+   * RUNNER's npm, so its exact-version match can diverge from the npm that
+   * actually executes once the pinned node shadows it. Suppressing the probe
+   * skips it entirely — no `npm --version` is ever spawned — and the install
+   * goes straight to the tool-cache/dist path, answering
+   * `source: "tool-cache"` with its own `binDir` as usual.
+   */
+  readonly allowAmbient?: boolean | undefined;
+}
+declare const AmbientPackageManager_base: Schema.Class<AmbientPackageManager, Schema.Struct<{
+  /** The discriminant: the runner's own toolchain answered. */
+  readonly source: Schema.tag<"ambient">;
+  /** The package-manager name (`npm`, `pnpm`, `yarn` or `bun`). */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The exact installed version, in string form. */
+  readonly version: Schema.String;
+  /** Bin name → the ambient command name that invokes it. */
+  readonly bins: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A package manager the runner's own toolchain already had: nothing was
+ * downloaded and nothing was cached, so there is no directory to publish.
+ *
+ * @remarks
+ * `bins` values are bare command names (`npm`, `npx`) resolved through the
+ * ambient `PATH` — the toolchain already put them there.
+ *
+ * @public
+ */
+declare class AmbientPackageManager extends AmbientPackageManager_base {}
+declare const CachedPackageManager_base: Schema.Class<CachedPackageManager, Schema.Struct<{
+  /** The discriminant: the manager lives in the tool cache. */
+  readonly source: Schema.tag<"tool-cache">;
+  /** The package-manager name (`npm`, `pnpm`, `yarn` or `bun`). */
+  readonly name: Schema.Literals<readonly ["npm", "pnpm", "yarn", "bun"]>;
+  /** The exact installed version, in string form. */
+  readonly version: Schema.String;
+  /** The cached entry: `<tool-cache>/<name>/<version>/<arch>`. */
+  readonly directory: Schema.String;
+  /** The directory to `addPath` — executable shims, or bun's own directory. */
+  readonly binDir: Schema.String;
+  /** Bin name → the absolute path of the underlying entry point. */
+  readonly bins: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A package manager living in the runner's tool cache — found there, or
+ * installed into it by this call.
+ *
+ * @remarks
+ * `binDir` is the directory a consumer hands to `ActionOutputs.addPath` to
+ * make the manager invokable by name in subsequent workflow steps. For the
+ * npm-registry managers it is the entry's `.bin` directory of executable
+ * shims this installer writes (`#!/bin/sh` exec wrappers, or `.cmd` wrappers
+ * on Windows); for bun it is the entry directory itself, because the cached
+ * `bun` binary is directly executable and a shim would add nothing but a
+ * fork. `bins` still maps each published bin name to the underlying entry —
+ * a Node script to run with `node` for npm/pnpm/yarn, the native binary for
+ * bun. Calling `addPath` remains deliberately the consumer's move, and note
+ * that `addPath` targets *subsequent* steps: a same-process probe must use
+ * the absolute paths in `bins` or `binDir`.
+ *
+ * @public
+ */
+declare class CachedPackageManager extends CachedPackageManager_base {}
+/**
+ * An installed package manager, discriminated by `source`: `ambient` carries
+ * no directory, `tool-cache` carries the cached `directory` and the
+ * `addPath`-able `binDir`. The union is a `Schema`, so the record round-trips
+ * through `ActionState` for a later phase to read back.
+ *
+ * @remarks
+ * **Construct the variant classes, never the union.** The union's inherited
+ * `make` typechecks against *both* variants at once, so a wrong field yields
+ * a confusing two-branch error instead of "this variant wants X" — reach for
+ * {@link AmbientPackageManager}`.make` / {@link CachedPackageManager}`.make`,
+ * whose `Schema.tag` fills `source` for you. The same tag is why an
+ * overrides-style test helper should be typed
+ * `Partial<Omit<typeof CachedPackageManager.Type, "source">>` — a plain
+ * `Partial` offers `source`, which `make` auto-fills and rejects as input.
+ *
+ * @public
+ */
+declare const InstalledPackageManager: Schema.Union<readonly [typeof AmbientPackageManager, typeof CachedPackageManager]>;
+/**
+ * The decoded type of {@link (InstalledPackageManager:variable)}:
+ * {@link AmbientPackageManager} `|` {@link CachedPackageManager}.
+ *
+ * @public
+ */
+type InstalledPackageManager = typeof InstalledPackageManager.Type;
+/**
+ * The {@link PackageManagerInstaller} service shape.
+ *
+ * @public
+ */
+interface PackageManagerInstallerShape {
+  /**
+   * Provision the exact package-manager version a pin names, answering with
+   * where it landed and how to invoke it.
+   */
+  readonly install: (pin: PackageManagerPin, options?: PackageManagerInstallOptions) => Effect.Effect<InstalledPackageManager, PackageManagerInstallerError>;
+}
+declare const PackageManagerInstaller_base: Context.ServiceClass<PackageManagerInstaller, "@effected/github-actions/PackageManagerInstaller", PackageManagerInstallerShape>;
+/**
+ * First-class exact-version package-manager provisioning on a GitHub runner.
+ *
+ * @remarks
+ * Takes a corepack pin (`@effected/npm`'s `PackageManagerPin`) and answers
+ * with an installed manager: tool-cache `find` first, then — for npm — an
+ * ambient `npm --version` probe (every Node toolchain ships npm), and only
+ * then the manager's own dist: npm, pnpm and yarn 1.x from their registry
+ * tarballs, yarn 2+ (Berry) from `@yarnpkg/cli-dist`, bun from its
+ * per-platform GitHub-release zip. A pin that carries integrity is verified
+ * fail-closed against what corepack itself hashes; one that does not proceeds
+ * with a logged warning unless `requireIntegrity` says otherwise.
+ *
+ * Every tool-cache answer carries a `binDir` a consumer can hand straight to
+ * `ActionOutputs.addPath`: the npm-registry managers get a `.bin` directory
+ * of executable shims written as part of the cached entry, bun's entry is its
+ * own `binDir`. Caching goes through {@link ToolInstaller}, so the
+ * stage-then-swap invariant holds here for free — shims included, the tool
+ * cache only ever contains complete package managers.
+ *
+ * @example
+ * ```ts
+ * import { ActionOutputs, PackageManagerInstaller } from "@effected/github-actions";
+ * import { PackageManagerPin } from "@effected/npm";
+ * import { Effect } from "effect";
+ *
+ * const provision = Effect.gen(function* () {
+ *   const installer = yield* PackageManagerInstaller;
+ *   const outputs = yield* ActionOutputs;
+ *   const pin = yield* PackageManagerPin.parse("pnpm@10.13.1");
+ *   const installed = yield* installer.install(pin);
+ *   if (installed.source === "tool-cache") {
+ *     yield* outputs.addPath(installed.binDir);
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class PackageManagerInstaller extends PackageManagerInstaller_base {
+  static readonly layer: Layer.Layer<PackageManagerInstaller, never, ActionEnvironment | FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner | ToolInstaller>;
+  /** A test double. The unstubbed member dies rather than reporting an install that did not happen. */
+  static readonly makeTest: (overrides?: Partial<PackageManagerInstallerShape>) => PackageManagerInstallerShape;
+  /** {@link PackageManagerInstaller.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<PackageManagerInstallerShape>) => Layer.Layer<PackageManagerInstaller>;
+}
+//#endregion
+//#region src/Secret.d.ts
+/**
+ * The declassification seam: the **only** place in this package where a
+ * `Redacted` value becomes a plain string.
+ *
+ * @remarks
+ * Some boundaries cannot carry a `Redacted`. A detached child process reads
+ * its configuration from environment variables; `GITHUB_STATE` is a plaintext
+ * file by GitHub's protocol. `Redacted` refusing to serialize is the whole
+ * value of the type, so this module does not try to make it serializable —
+ * it makes declassification **explicit, auditable, and impossible to do
+ * quietly**.
+ *
+ * The invariant: **masking and declassification are the same call.** Every
+ * member registers the value with the runner's log filter (`::add-mask::`)
+ * *before* returning plaintext, so a secret cannot reach a child's environment
+ * or a state file without the runner already knowing to redact it from logs.
+ *
+ * `Redacted.value` appears nowhere else in this package, and a test asserts
+ * that structurally — a reintroduction elsewhere fails the suite rather than
+ * review.
+ *
+ * What this deliberately does **not** do is encrypt the handoff. The child
+ * runs on the same runner, as the same user, as the parent; a key would have
+ * to travel the same channel as the secret it protects.
+ *
+ * @example
+ * ```ts
+ * import { Secret } from "@effected/github-actions";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const env = yield* Secret.forChildEnv({ MY_TOKEN: theToken });
+ *   // every value in `env` is already masked in the runner log
+ *   return env;
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class Secret {
+  private constructor();
+  /**
+   * Declassify a set of secrets for a child process's environment.
+   *
+   * @remarks
+   * Every value is masked before any plaintext is returned — including when
+   * one of them fails, because masking happens for the whole set first.
+   *
+   * **Detached workers invert the masking model.** Masking works because the
+   * runner parses this process's stdout; a *detached* child's stdout is a log
+   * file no runner parses, so a mask emitted **inside** the worker is inert
+   * and writes the plaintext verbatim into that log — a shipped incident, not
+   * a hypothetical. The rule: **the parent masks, before the spawn** — call
+   * this member in the parent, where the runner is listening, and hand the
+   * already-masked plaintext to the worker's environment. Inside the worker,
+   * compose `ActionOutputs.layerDetached`, whose `setSecret` is a documented
+   * no-op, so the same code cannot re-leak what the parent already masked.
+   */
+  static readonly forChildEnv: (entries: Readonly<Record<string, Redacted.Redacted<string>>>) => Effect.Effect<Record<string, string>, never, ActionOutputs>;
+  /**
+   * Declassify one secret for a runner file (`GITHUB_STATE`, `GITHUB_OUTPUT`).
+   *
+   * @remarks
+   * Masks first. The runner file is plaintext regardless; the mask is what
+   * keeps the value out of the visible log.
+   */
+  static readonly forRunnerFile: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
+  /**
+   * Declassify one secret for an in-process use that needs the raw bytes.
+   *
+   * @remarks
+   * Request signing is the case this exists for: an HMAC cannot be computed
+   * over a `Redacted`, so a signing key has to become a string somewhere, and
+   * the point of this module is that "somewhere" is here and nowhere else.
+   *
+   * Signing named the member; it does not gate it. **Any in-process use that
+   * needs the raw value without writing it to a runner file is this
+   * operation** — handing a key to a library that takes a plain string. The
+   * dividing line is where the value goes, not what it is for: a value
+   * crossing into a **child's** environment is {@link Secret.forChildEnv},
+   * one written to `GITHUB_STATE` or `GITHUB_OUTPUT` is
+   * {@link Secret.forRunnerFile}, and one that stays in this process is this
+   * member. A third-party SDK that reads only the ambient environment is the
+   * hard case: this package never mutates `process.env` (reads are seeded
+   * once through `ActionEnvironment`), so if a consumer chooses that bridge,
+   * the mutation — and its restore discipline — lives in consumer code as
+   * the consumer's own tradeoff, not as a pattern this member recommends.
+   *
+   * It masks even though the value is never *written* anywhere, and that is
+   * deliberate rather than superstitious: a signing key that leaks does so
+   * through something nobody audited — a debug log of outgoing headers, a
+   * serialized error, a stack trace carrying the closure. Registering it with
+   * the runner's filter costs one call and makes every one of those redacted.
+   *
+   * Call it **once, at layer construction**, not per operation: masking is
+   * idempotent but a workflow command per request is noise in the log.
+   *
+   * **In a detached worker, the mask this member emits is a leak.** The
+   * `::add-mask::` command only masks when the runner parses this process's
+   * stdout; a detached worker's stdout is a log file no runner parses, so
+   * there the command masks nothing *and* spells the plaintext into the log
+   * — a signing key shipped exactly that way for one round. A worker that
+   * signs (an S3-style `BlobStore` is the canonical case) must compose
+   * `ActionOutputs.layerDetached`, under which this member still returns the
+   * raw key for the HMAC but the mask is a documented no-op; the masking
+   * itself is the **parent's** job, done before the spawn via
+   * {@link Secret.forChildEnv} under the real layer.
+   */
+  static readonly forSigning: (secret: Redacted.Redacted<string>) => Effect.Effect<string, never, ActionOutputs>;
+  /**
+   * The far side of a handoff: re-wrap a plaintext environment variable.
+   *
+   * @remarks
+   * A `Config`, so a missing or empty handoff is an honest `ConfigError`
+   * naming the variable rather than an empty `Redacted` that fails much later
+   * as an authentication error.
+   */
+  static readonly adopt: (name: string) => Config.Config<Redacted.Redacted<string>>;
+}
+//#endregion
+export { Action, ActionCache, ActionCacheError, type ActionCacheShape, ActionEnvironment, ActionEnvironmentError, type ActionEnvironmentShape, ActionInput, ActionLogger, type ActionLoggerShape, ActionOutputError, ActionOutputs, type ActionOutputsShape, type ActionRunOptions, ActionRuntime, type ActionServices, ActionState, ActionStateError, type ActionStateShape, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, type AnnotationProperties, Artifact, ArtifactError, type ArtifactItem, type ArtifactRef, type ArtifactShape, type Blob, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, type BlobStoreShape, BlobTransferError, CacheKey, CacheKeyError, CachedPackageManager, CheckDocument, CheckDocumentError, type CheckDocumentOptions, type CheckDocumentShape, type CheckDocumentSink, CheckReport, type CheckRunConclusion, type CheckRunProjection, CheckState, ChildEnv, type ClientLayerOptions, type DataBlobTransfer, DetachedProcess, DetachedProcessError, type DetachedSpawnOptions, type DownloadOptions, type DownloadResult, DryRun, type DryRunShape, type ExtractOptions, type FileBlobTransfer, GitHubCacheBlobStore, GitHubContext, type GitHubHeadingDepth, type GitHubListOptions, GitHubMarkdown, type GitHubRowSchema, type GitHubSchemaTable, type GitHubSchemaTableColumn, type GitHubSchemaTableColumns, type GitHubSchemaTableFormatRequiredKeys, type GitHubSchemaTableFormattedColumn, type GitHubSchemaTableOptions, GitHubToken, GitHubTokenError, InstalledPackageManager, ManagedDocument, ManagedDocumentError, type ManagedDocumentSource, OidcClaims, OidcTokenError, OidcTokenIssuer, type OidcTokenIssuerShape, type PackageManagerInstallOptions, PackageManagerInstaller, PackageManagerInstallerError, type PackageManagerInstallerShape, type PathPrependEnv, type PathPrependOptions, ProcessId, type ProvisionFileOptions, type ProvisionOptions, type ProvisionedFile, type ReadOptions, type ReadinessOptions, RunnerContext, type S3Config, Secret, type ToolDownloadOptions, ToolInstaller, ToolInstallerError, type ToolInstallerShape, type UploadOptions, type UploadResult, type WithBufferOptions, WorkflowCommand, describeCause, projectCheckState };
 //# sourceMappingURL=index.d.ts.map