@effected/github-actions 0.19.1 → 0.20.0

package/index.js

@@ -1,6 +1,5 @@
 import { ActionEnvironment, ActionEnvironmentError, GitHubContext, RunnerContext } from "./ActionEnvironment.js";
 import { ActionInput } from "./ActionInput.js";
-import { WorkflowCommand } from "./WorkflowCommand.js";
 import { ActionLogger } from "./ActionLogger.js";
 import { ActionOutputs, DetachedOutputError, InvalidOutputNameError, OutputEncodeError, RecordedOutput, RunnerFileUnavailableError, RunnerFileWriteError } from "./ActionOutputs.js";
 import { ActionState, ActionStateError } from "./ActionState.js";
@@ -26,5 +25,6 @@ import { GitHubMarkdown } from "./GitHubMarkdown.js";
 import { GitHubToken, GitHubTokenError } from "./GitHubToken.js";
 import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
 import { AmbientPackageManager, CachedPackageManager, InstalledPackageManager, PackageManagerInstaller, PackageManagerInstallerError } from "./PackageManagerInstaller.js";
+import { WorkflowCommand } from "@effected/github-commands";
 
 export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputs, ActionRuntime, ActionState, ActionStateError, ActionsIdentityToken, ActionsProvenance, AmbientPackageManager, Artifact, ArtifactError, BlobEnvelope, BlobMetadataDecodeError, BlobMetadataEncodeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyBadPatternError, CacheKeyReadError, CachedPackageManager, CheckDocument, CheckDocumentError, CheckDocumentStamp, CheckReport, CheckState, ChildEnv, DetachedLogUnavailableError, DetachedNotReadyError, DetachedOutputError, DetachedProcess, DetachedSignalFailedError, DetachedSpawnFailedError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubMarkdown, GitHubToken, GitHubTokenError, InstalledPackageManager, InvalidOutputNameError, InvalidPidError, ManagedDocument, ManagedDocumentError, NotABlobEnvelopeError, OidcClaims, OidcTokenError, OidcTokenIssuer, OutputEncodeError, PackageManagerInstaller, PackageManagerInstallerError, ProcessId, RecordedOutput, RunnerContext, RunnerFileUnavailableError, RunnerFileWriteError, Secret, ToolInstaller, ToolInstallerError, TruncatedBlobEnvelopeError, UnsupportedBlobEnvelopeVersionError, WorkflowCommand, describeCause, projectCheckState };

package/internal/actionsResults.js

@@ -2,18 +2,6 @@ import { payloadOf } from "./jwt.js";
 import { Effect, Option, Redacted, Result } from "effect";
 
 //#region src/internal/actionsResults.ts
-/**
-* Reading the runner's *results backend* coordinates — the two variables the
-* cache, artifact and blob-store protocols all speak through.
-*
-* @remarks
-* Shared by `ActionCache`, `Artifact` and `BlobStore.githubCache`, and
-* deliberately free of `@azure/storage-blob`: an internal helper is exactly how
-* a heavy import leaks into a light module's graph, so the one piece those
-* three modules share is the piece with no dependencies.
-*
-* @internal
-*/
 /** The variable naming the backend. Absent outside a `uses:` step. */
 const RESULTS_URL = "ACTIONS_RESULTS_URL";
 /** The variable holding the run-scoped credential. Absent outside a `uses:` step. */

package/internal/archiveCommands.js

@@ -1,72 +1,6 @@
 import { ChildProcess } from "effect/process";
 
 //#region src/internal/archiveCommands.ts
-/**
-* The archiver command lines this package spawns, spelled once.
-*
-* @remarks
-* `Artifact` (pack and unpack) and `ToolInstaller` (unpack only) each spawn
-* the same three shapes — a zip, an unzip, a tar extraction — and each has a
-* Windows half that no test on a POSIX host can execute. Two hand-written
-* copies drifted: `ToolInstaller.extractZip` learned the overwrite overload
-* and the stderr capture below, `Artifact.download` did not, and a download
-* into a non-empty directory kept failing on Windows with an EMPTY stderr.
-* This module is the one spelling; the tests pin its text verbatim, which
-* is the only proof the Windows halves get.
-*
-* **The pwsh unzip is deliberately belt-and-braces.** The THREE-argument
-* `ExtractToDirectory(src, dest, $true)` overload overwrites existing files —
-* the two-argument one refuses, which is what turned a repeated extraction
-* into a hard failure — and the `$ErrorActionPreference = 'Stop'` plus
-* try/catch writes the actual .NET exception text plainly to stderr and
-* exits 1. pwsh's own error rendering does not reliably reach a captured
-* stream, and an empty complaint costs a source dive to even hypothesize
-* about.
-*
-* **The pwsh zip drives .NET's `ZipFile` directly, not `Compress-Archive`.**
-* Microsoft's own reference for `Compress-Archive -Path` states both faults:
-* handed individual file paths it stores every entry under its bare file
-* name — directory structure is kept only when `-Path` names a directory —
-* so `dir\b.txt` landed as `b.txt`, same-named files in different
-* directories collided, and a Windows artifact was structurally different
-* from the POSIX `zip -qr` one; and `-Path` expands wildcards, so a literal
-* `report[1].txt` matched nothing and failed the upload. Stating every entry
-* name explicitly through `CreateEntryFromFile(zip, source, entryName)`
-* removes both: the source is `Path.Combine(root, rel)`, taken literally,
-* and the entry name is `rel` with `\` turned to `/`, which is what `zip`
-* records on POSIX.
-*
-* **The Windows script is constant-size: the file list travels in a manifest
-* file, never in `-Command`.** `CreateProcessW` caps the whole command line
-* at 32,767 characters, and inlining one `CreateEntryFromFile` statement per
-* file (~214 characters each) hit that ceiling at roughly 150 files with
-* `ENAMETOOLONG` — fewer than the `Compress-Archive` form it replaced carried.
-* The script now reads {@link zipManifest}'s output (one relative path per
-* line) with `File.ReadAllLines` and loops. **The two branches deliberately
-* differ in mechanism**: POSIX `zip` takes the files as argv, whose ceiling
-* (`ARG_MAX`, megabytes on the hosted runners) is far larger, so the only
-* file-count ceiling left is that POSIX argv limit. The manifest is written by
-* the caller (`Artifact.zip`) as UTF-8 WITHOUT a BOM, which is what
-* `ReadAllLines` reads by default. Its BOM detection would consume a BOM
-* rather than leak it into the first path (measured), so this is a
-* plain-bytes preference, not a correctness guard.
-*
-* **Every `CreateEntryFromFile` is assigned to `$null`.** Unassigned, pwsh
-* writes the returned `ZipArchiveEntry` to stdout — roughly 430 bytes of
-* formatted object per file — and `internal/spawn.ts` interleaves stdout with
-* stderr into the captured output, which is what `ArtifactError.stderr`
-* carries. Left in, that chatter buried the one line that matters, the .NET
-* exception, under kilobytes of entry listings.
-*
-* Every path handed to PowerShell is single-quoted, and a single quote inside
-* one is doubled — the only escape a single-quoted PowerShell literal has.
-*
-* Pure: no filesystem, no environment, no spawn. `internal/spawn.ts` is the
-* execution half. Reaches `effect/process` alone, so it is safe for
-* any module to import (`__test__/reachability.test.ts`).
-*
-* @internal
-*/
 /** A PowerShell single-quoted literal: `'` becomes `''`, nothing else is special. */
 const pwshLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
 /** A non-interactive pwsh invocation of one command line. */

package/internal/cacheService.js

@@ -2,22 +2,6 @@ import { CONFLICT, isOk, stringField } from "./twirp.js";
 import { Effect, Option } from "effect";
 
 //#region src/internal/cacheService.ts
-/**
-* The Actions `CacheService` choreography — reserve, upload, finalize; look up
-* — spelled once for the two services that speak it.
-*
-* @remarks
-* `ActionCache` files a tar archive under a path-derived version and
-* `BlobStore.githubCache` files an envelope under a constant one, but the
-* three RPCs between them and their conflict semantics are identical. Each
-* caller supplies its own per-key `call` and its own `refused` constructor, so
-* the errors stay the caller's; this module owns only the protocol. It reaches
-* `effect` and the Twirp client and nothing heavier — the Azure transfer of
-* the bytes between the two RPCs stays in the three modules licensed to import
-* it (`__test__/reachability.test.ts`).
-*
-* @internal
-*/
 /** The Twirp service the Actions cache protocol lives under. @internal */
 const CACHE_SERVICE = "github.actions.results.api.v1.CacheService";
 /**

package/internal/digest.js

@@ -3,19 +3,6 @@ import { createHash } from "node:crypto";
 import * as Hex from "effect/encoding/Hex";
 
 //#region src/internal/digest.ts
-/**
-* The sanctioned `node:crypto` digests, spelled once.
-*
-* @remarks
-* Core `Crypto` offers one-shot SHA digests over bytes already in memory, but
-* no HMAC and no incremental hasher, so this package's licence for a `node:`
-* import covers hashing (see the Module concept in `okf/`). Keeping every
-* `createHash` behind this module is what makes that licence auditable in one
-* place rather than six, and keeps the streamed file digest — the shape a
-* multi-gigabyte toolchain archive needs — from being re-derived per caller.
-*
-* @internal
-*/
 /** The raw SHA-256 of a string or byte array held in memory. @internal */
 const sha256 = (value) => new Uint8Array(createHash("sha256").update(value).digest());
 /** The hex SHA-256 of a string or byte array held in memory. @internal */

package/internal/jwt.js

@@ -3,23 +3,6 @@ import * as Base64Url from "effect/encoding/Base64Url";
 
 //#region src/internal/jwt.ts
 /**
-* The JWT segment codec — read a payload, or frame an unsigned token — for the
-* two places this package reads a runner-issued token's claims.
-*
-* @remarks
-* **No signature verification, deliberately.** Every token read here was
-* handed to this process by the runner that started it, and the claim read
-* scopes a request (`actionsResults`) or is republished for a verifier
-* elsewhere (`OidcTokenIssuer`); neither authorizes anything on the strength
-* of the claim alone. Do not "fix" it here.
-*
-* Core `Base64Url` does the base64url work, so no `Buffer` is involved: it is
-* strict about the alphabet where Node's decoder is forgiving, which is why
-* there is a test whose payload actually contains `-` and `_`.
-*
-* @internal
-*/
-/**
 * The decoded payload of `token` — the middle segment, base64url JSON —
 * without any check on the signature.
 *

package/internal/pnpmExe.js

@@ -3,21 +3,6 @@ import * as Hex from "effect/encoding/Hex";
 import * as Base64 from "effect/encoding/Base64";
 
 //#region src/internal/pnpmExe.ts
-/**
-* The pnpm native-binary layout: from pnpm 12 the `pnpm` registry package is a
-* thin wrapper whose `pnpm` bin is a shebang-less placeholder that the
-* package's own install script overwrites with the host's native executable,
-* fetched as an optional dependency named `@pnpm/exe.<os>-<arch>[-musl]`.
-* The installer never runs lifecycle scripts, so it performs that overlay
-* itself; the pure pieces of that live here, where they are testable without
-* a tarball.
-*
-* Detection is by LAYOUT (the manifest's `optionalDependencies` naming an
-* `@pnpm/exe.*` package), never by major version — pnpm 11 and earlier ship
-* no such dependency and keep their Node entry points.
-*
-* @internal
-*/
 /** The prefix every native-binary package name carries. @internal */
 const PNPM_EXE_PREFIX = "@pnpm/exe.";
 /**

package/internal/runnerFile.js

@@ -1,20 +1,4 @@
 //#region src/internal/runnerFile.ts
-/**
-* The runner-file heredoc protocol — `GITHUB_OUTPUT`, `GITHUB_ENV` and
-* `GITHUB_STATE` all take `name<<DELIM\nvalue\nDELIM\n` — spelled once for
-* `ActionOutputs` and `ActionState`.
-*
-* @remarks
-* **Delimiters are derived, never random.** GitHub's own toolkit uses a
-* random UUID here and accepts the (tiny) chance of collision. Deriving the
-* delimiter instead makes collision **impossible** rather than improbable,
-* needs no randomness — so no `Crypto` in `R` and no unreproducible output —
-* and is trivially testable. A value that contains a delimiter would
-* terminate its block early and corrupt every entry after it, which is a
-* value-controlled injection into the runner's own file.
-*
-* @internal
-*/
 /** The base delimiter for a heredoc block. */
 const BASE_DELIMITER = "EFFECTED_EOF";
 /** A delimiter guaranteed absent from `value`. @internal */

package/internal/sigv4.js

@@ -45,10 +45,7 @@ const timestamps = (now) => {
 * @remarks
 * Exported separately from {@link sign} so a test can pin it against AWS's
 * **own documented** canonical request rather than against this
-* implementation's output. That distinction is not pedantry: the first draft of
-* this module was checked against a remembered signature constant that turned
-* out to be from a different example, and the only thing that settled which side
-* was wrong was reproducing a value AWS publishes.
+* implementation's output.
 */
 const canonicalize = (request, credentials) => {
 	const { amzDate, dateStamp } = timestamps(request.now);

package/internal/unstubbed.js

@@ -2,18 +2,6 @@ import { Effect } from "effect";
 
 //#region src/internal/unstubbed.ts
 /**
-* The one way an unstubbed test-double member dies, for every `makeTest` in
-* this package.
-*
-* @remarks
-* A double's unstubbed member must die rather than silently succeed — a stub
-* that returns nothing teaches a test that nothing happened. The message names
-* the double, the member and the override that fixes it, and it is spelled
-* here once so a wording change is one edit rather than ten.
-*
-* @internal
-*/
-/**
 * The die-on-call members of `<double>.makeTest`: `dies("save")` is an
 * `Effect` that defects naming `save` when run. Each package double binds its
 * own name once, then lists its members.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github-actions",
-	"version": "0.19.1",
+	"version": "0.20.0",
 	"private": false,
 	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
 	"keywords": [
@@ -39,18 +39,19 @@
 	},
 	"dependencies": {
 		"@azure/storage-blob": "^12.33.0",
-		"@effected/github": "^0.14.0",
-		"@effected/glob": "^0.9.0",
-		"@effected/markdown": "^0.14.0",
-		"@effected/npm": "^0.19.0",
-		"@effected/sbom": "^0.9.1",
-		"@effected/semver": "^0.10.1",
-		"@effected/templates": "^0.9.1",
-		"@effected/walker": "^0.14.0"
+		"@effected/github": "^0.15.0",
+		"@effected/github-commands": "^0.1.0",
+		"@effected/glob": "^0.10.0",
+		"@effected/markdown": "^0.15.0",
+		"@effected/npm": "^0.20.0",
+		"@effected/sbom": "^0.10.0",
+		"@effected/semver": "^0.11.0",
+		"@effected/templates": "^0.10.0",
+		"@effected/walker": "^0.15.0"
 	},
 	"peerDependencies": {
-		"@effect/platform-node": "4.0.0-rc.118",
-		"effect": "4.0.0-rc.118"
+		"@effect/platform-node": "^4.0.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/WorkflowCommand.js

@@ -1,100 +0,0 @@
-//#region src/WorkflowCommand.ts
-/**
-* Escape a command's message.
-*
-* @remarks
-* The percent sign is replaced **first**, and the order is load-bearing: doing
-* it last would re-escape the `%` of an escape sequence this function just
-* produced, turning `%0A` into `%250A`.
-*/
-const escapeMessage = (value) => value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
-/**
-* Escape a property value.
-*
-* @remarks
-* Everything a message escapes, plus `:` and `,` — the two characters that
-* delimit the property list and terminate it. An unescaped one truncates the
-* command or lets a value be read as a new property.
-*/
-const escapeProperty = (value) => escapeMessage(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
-/**
-* The GitHub Actions workflow-command wire protocol: `::name key=value::message`.
-*
-* @remarks
-* **Pure.** This module renders strings and nothing else — it performs no IO
-* and holds no service — which is what makes the escaping rules testable
-* without a runner, and what lets a non-Actions consumer reuse the protocol.
-* Writing a rendered command to stdout is {@link ActionOutputs}'s job.
-*
-* The escaping is the whole point of the module. A message carrying a raw
-* newline does not merely render oddly: the runner reads the text after it as
-* a **new command**, so an unescaped log line is a command-injection vector.
-*
-* @example
-* ```ts
-* import { WorkflowCommand } from "@effected/github-actions";
-*
-* WorkflowCommand.error("build failed", { file: "src/main.ts", startLine: 12 });
-* // "::error file=src/main.ts,line=12::build failed"
-* ```
-*
-* @public
-*/
-var WorkflowCommand = class WorkflowCommand {
-	constructor() {}
-	/**
-	* Render an arbitrary command. The primitive every other member uses.
-	*
-	* @remarks
-	* The property type is written out structurally rather than as the module's
-	* `CommandProperties` alias: an internal named type on a `@public` signature
-	* fails the API Extractor gate, and neither an `@internal` tag nor a second
-	* alias helps — only inlining does.
-	*/
-	static render(name, properties, message) {
-		const rendered = Object.entries(properties).filter((entry) => entry[1] !== void 0).map(([key, value]) => `${key}=${escapeProperty(String(value))}`).join(",");
-		return `${rendered === "" ? `::${name}::` : `::${name} ${rendered}::`}${escapeMessage(message)}`;
-	}
-	/** `::debug::` — shown only when `ACTIONS_STEP_DEBUG` is enabled. */
-	static debug(message) {
-		return WorkflowCommand.render("debug", {}, message);
-	}
-	/** `::notice::` with optional source annotation. */
-	static notice(message, properties = {}) {
-		return WorkflowCommand.render("notice", WorkflowCommand.annotation(properties), message);
-	}
-	/** `::warning::` with optional source annotation. */
-	static warning(message, properties = {}) {
-		return WorkflowCommand.render("warning", WorkflowCommand.annotation(properties), message);
-	}
-	/** `::error::` with optional source annotation. */
-	static error(message, properties = {}) {
-		return WorkflowCommand.render("error", WorkflowCommand.annotation(properties), message);
-	}
-	/** `::group::` — opens a collapsible section in the runner log. */
-	static group(name) {
-		return WorkflowCommand.render("group", {}, name);
-	}
-	/** `::endgroup::` — closes the innermost open group. */
-	static endGroup() {
-		return WorkflowCommand.render("endgroup", {}, "");
-	}
-	/** `::add-mask::` — registers a value for redaction in the runner log. */
-	static addMask(value) {
-		return WorkflowCommand.render("add-mask", {}, value);
-	}
-	/** Map readable annotation fields onto GitHub's abbreviated wire names. */
-	static annotation(properties) {
-		return {
-			title: properties.title,
-			file: properties.file,
-			line: properties.startLine,
-			endLine: properties.endLine,
-			col: properties.startColumn,
-			endColumn: properties.endColumn
-		};
-	}
-};
-
-//#endregion
-export { WorkflowCommand };