@effected/github-actions 0.1.0

package/ActionLogger.js

@@ -0,0 +1,205 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { WorkflowCommand } from "./WorkflowCommand.js";
+import { Console, Context, Effect, Inspectable, Layer, LogLevel, Logger, References } from "effect";
+
+//#region src/ActionLogger.ts
+/**
+* Render a log message, which arrives as an array of the values passed to
+* `Effect.log*`.
+*
+* @remarks
+* `toStringUnknown` is called with zero indentation on purpose: a pretty-printed
+* object would span lines, and a workflow command escapes every newline, so the
+* indented form buys nothing and costs readability.
+*/
+const formatMessage = (message) => {
+	return (Array.isArray(message) ? message : [message]).map((part) => Inspectable.toStringUnknown(part, 0)).join(" ");
+};
+/** A log annotation read as text, when it is text. */
+const textAnnotation = (record, key) => {
+	const value = record[key];
+	return typeof value === "string" ? value : void 0;
+};
+/** A log annotation read as a number, accepting the string form the runner produces. */
+const numericAnnotation = (record, key) => {
+	const value = record[key];
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value === "string" && value !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+};
+/**
+* Project log annotations onto the annotation vocabulary.
+*
+* @remarks
+* The keys are the readable ones from {@link AnnotationProperties}, not GitHub's
+* abbreviated wire names — one vocabulary per package, with the abbreviation
+* confined to {@link WorkflowCommand}. Undefined fields are omitted rather than
+* set, so a caller that annotated nothing renders a bare command.
+*/
+const readAnnotations = (record) => {
+	const title = textAnnotation(record, "title");
+	const file = textAnnotation(record, "file");
+	const startLine = numericAnnotation(record, "startLine");
+	const endLine = numericAnnotation(record, "endLine");
+	const startColumn = numericAnnotation(record, "startColumn");
+	const endColumn = numericAnnotation(record, "endColumn");
+	return {
+		...title === void 0 ? {} : { title },
+		...file === void 0 ? {} : { file },
+		...startLine === void 0 ? {} : { startLine },
+		...endLine === void 0 ? {} : { endLine },
+		...startColumn === void 0 ? {} : { startColumn },
+		...endColumn === void 0 ? {} : { endColumn }
+	};
+};
+/** The inverse: annotation fields as a record `Effect.annotateLogs` accepts. */
+const annotationRecord = (properties) => ({
+	...properties.title === void 0 ? {} : { title: properties.title },
+	...properties.file === void 0 ? {} : { file: properties.file },
+	...properties.startLine === void 0 ? {} : { startLine: properties.startLine },
+	...properties.endLine === void 0 ? {} : { endLine: properties.endLine },
+	...properties.startColumn === void 0 ? {} : { startColumn: properties.startColumn },
+	...properties.endColumn === void 0 ? {} : { endColumn: properties.endColumn }
+});
+/**
+* Map one log entry onto the line the runner should see.
+*
+* @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.
+*/
+const renderEntry = (level, message, annotations) => {
+	const text = formatMessage(message);
+	if (LogLevel.isGreaterThanOrEqualTo(level, "Warn")) {
+		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);
+};
+/**
+* The buffer the current fiber is writing into, or `null` when not buffering.
+*
+* @remarks
+* A `Context.Reference` rather than a module-level "current buffer": two steps
+* running concurrently each keep their own transcript, and neither has to
+* restore anything. A save/restore global is LIFO-correct only while the two
+* buffers nest, which concurrent steps do not.
+*
+* @internal
+*/
+const ActiveBuffer = Context.Reference("@effected/github-actions/ActiveBuffer", { defaultValue: () => null });
+/** Write a transcript out and clear it, so a second flush is a no-op. */
+const flush = (state) => Effect.suspend(() => {
+	if (state.entries.length === 0) return Effect.void;
+	const body = [
+		`--- Buffered output for "${state.label}" ---`,
+		...state.entries,
+		`--- End buffered output for "${state.label}" ---`
+	];
+	state.entries.length = 0;
+	return Effect.forEach(body, (line) => Console.log(line), { discard: true });
+});
+const make = Effect.gen(function* () {
+	const env = yield* ActionEnvironment;
+	const flushActive = Effect.flatMap(ActiveBuffer, (state) => state === null ? Effect.void : flush(state));
+	return {
+		group: (name, effect) => Effect.acquireUseRelease(Console.log(WorkflowCommand.group(name)), () => Effect.tapCause(effect, () => flushActive), () => Console.log(WorkflowCommand.endGroup())),
+		withBuffer: (label, effect) => Effect.gen(function* () {
+			const minimum = yield* References.MinimumLogLevel;
+			if ((yield* env.isDebug) || LogLevel.isLessThanOrEqualTo(minimum, "Debug")) return yield* effect;
+			const state = {
+				label,
+				entries: []
+			};
+			const buffering = Logger.make((options) => {
+				if (LogLevel.isGreaterThanOrEqualTo(options.logLevel, "Warn")) {
+					const annotations = options.fiber.getRef(References.CurrentLogAnnotations);
+					options.fiber.getRef(Console.Console).log(renderEntry(options.logLevel, options.message, annotations));
+					return;
+				}
+				state.entries.push(formatMessage(options.message));
+			});
+			return yield* effect.pipe(Effect.provideService(References.MinimumLogLevel, "All"), Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([buffering])), Effect.provideService(ActiveBuffer, state), Effect.onExit(() => flush(state)));
+		}),
+		notice: (message, properties = {}) => Console.log(WorkflowCommand.notice(message, properties)),
+		annotated: (properties, effect) => Effect.annotateLogs(effect, annotationRecord(properties))
+	};
+});
+/**
+* Groups, buffered step transcripts, notices — and the `Logger` that renders
+* every `Effect.log*` in the kit as a workflow command.
+*
+* @remarks
+* The `Logger` is the seam that lets every other `@effected` package stay
+* telemetry-agnostic: libraries call `Effect.logWarning`, and exactly one
+* logger — installed at the edge by an action — turns those into `::warning::`
+* annotations. No library needs to know it is running inside Actions.
+*
+* @example
+* ```ts
+* import { ActionLogger } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const logger = yield* ActionLogger;
+*   yield* logger.group("install", logger.withBuffer("pnpm", Effect.logInfo("resolving")));
+* });
+* ```
+*
+* @public
+*/
+var ActionLogger = class ActionLogger extends Context.Service()("@effected/github-actions/ActionLogger") {
+	static layer = Layer.effect(this, make);
+	/**
+	* The `Logger` that maps Effect log levels onto workflow commands.
+	*
+	* @remarks
+	* `Error` and `Fatal` render `::error::`, `Warn` renders `::warning::`,
+	* `Debug` and `Trace` render `::debug::`, and `Info` renders as plain text.
+	* Annotations set by `annotated` travel with the entry.
+	*
+	* It writes through core `Console`, which is what makes its output
+	* observable in a test without a runner.
+	*/
+	static logger = Logger.make((options) => {
+		const annotations = options.fiber.getRef(References.CurrentLogAnnotations);
+		options.fiber.getRef(Console.Console).log(renderEntry(options.logLevel, options.message, annotations));
+	});
+	/** {@link ActionLogger.logger} installed as the only logger. */
+	static layerLogger = Logger.layer([ActionLogger.logger]);
+	/**
+	* A silent double.
+	*
+	* @remarks
+	* **A recorded exception to the die-on-unstubbed rule**, alongside
+	* {@link ActionEnvironment.makeTest}. A logger that dies when a suite logs
+	* would make every double unusable, and silence is the honest default for a
+	* service whose whole job is output. Group and buffer wrappers pass their
+	* effect through unchanged.
+	*/
+	static makeTest = (overrides = {}) => ({
+		group: (_name, effect) => effect,
+		withBuffer: (_label, effect) => effect,
+		notice: () => Effect.void,
+		annotated: (_properties, effect) => effect,
+		...overrides
+	});
+	/** {@link ActionLogger.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ActionLogger, ActionLogger.makeTest(overrides));
+	/**
+	* 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.
+	*/
+	static layerSilent = Layer.mergeAll(ActionLogger.layerTest(), Logger.layer([]));
+};
+
+//#endregion
+export { ActionLogger };

package/ActionOutputs.js

@@ -0,0 +1,135 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { WorkflowCommand } from "./WorkflowCommand.js";
+import { Console, Context, Effect, FileSystem, Layer, Schema } from "effect";
+
+//#region src/ActionOutputs.ts
+/**
+* Raised when an action cannot publish an output.
+*
+* @public
+*/
+var ActionOutputError = class extends Schema.TaggedErrorClass()("ActionOutputError", {
+	/**
+	* `unavailable` — the runner file variable is not set, which usually means
+	* 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.
+	*/
+	reason: Schema.Literals([
+		"unavailable",
+		"writeFailed",
+		"invalidName",
+		"encodeFailed"
+	]),
+	/** Which runner file was involved, by environment variable name. */
+	file: Schema.optionalKey(Schema.String),
+	/** The output or variable name, when one is involved. */
+	name: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "unavailable": return `Runner file "${this.file}" is not available; is this running on a GitHub runner?`;
+			case "writeFailed": return `Failed to write to runner file "${this.file}"`;
+			case "invalidName": return `"${this.name}" is not a usable output name`;
+			default: return `Failed to encode the value for "${this.name}"`;
+		}
+	}
+};
+/** The base delimiter for a heredoc block. */
+const BASE_DELIMITER = "EFFECTED_EOF";
+/**
+* A delimiter guaranteed absent from `value`.
+*
+* @remarks
+* 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.
+*/
+const delimiterFor = (value) => {
+	let delimiter = BASE_DELIMITER;
+	while (value.includes(delimiter)) delimiter = `${delimiter}_`;
+	return delimiter;
+};
+/** A name that would break the block structure it lives in. */
+const isUsableName = (name) => name !== "" && !/[\r\n]/.test(name);
+const make = Effect.gen(function* () {
+	const env = yield* ActionEnvironment;
+	const fs = yield* FileSystem.FileSystem;
+	const append = (file, content) => Effect.gen(function* () {
+		const path = yield* env.get(file).pipe(Effect.mapError(() => new ActionOutputError({
+			reason: "unavailable",
+			file
+		})));
+		yield* fs.writeFileString(path, content, { flag: "a" }).pipe(Effect.mapError((cause) => new ActionOutputError({
+			reason: "writeFailed",
+			file,
+			cause
+		})));
+	});
+	const appendBlock = (file, name, value) => {
+		if (!isUsableName(name)) return Effect.fail(new ActionOutputError({
+			reason: "invalidName",
+			file,
+			name
+		}));
+		const delimiter = delimiterFor(value);
+		return append(file, `${name}<<${delimiter}\n${value}\n${delimiter}\n`);
+	};
+	const set = (name, value) => appendBlock("GITHUB_OUTPUT", name, value);
+	return {
+		set,
+		setJson: (name, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new ActionOutputError({
+			reason: "encodeFailed",
+			name,
+			cause
+		})), Effect.flatMap((encoded) => set(name, JSON.stringify(encoded)))),
+		summary: (content) => append("GITHUB_STEP_SUMMARY", content),
+		exportVariable: (name, value) => appendBlock("GITHUB_ENV", name, value),
+		addPath: (path) => append("GITHUB_PATH", `${path}\n`),
+		setFailed: (message) => Console.log(WorkflowCommand.error(message)),
+		setSecret: (value) => Console.log(WorkflowCommand.addMask(value))
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`ActionOutputs.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* Everything an action publishes: step outputs, exported variables, `PATH`
+* additions, the job summary, log masking and failure annotations.
+*
+* @remarks
+* Outputs and variables go to the runner's **files** (`GITHUB_OUTPUT` and
+* friends); masking and annotations go to stdout as workflow commands, through
+* core `Console` so a test can observe them without a runner.
+*
+* `setFailed` emits the annotation but does **not** set the process exit code
+* — 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.
+*
+* @public
+*/
+var ActionOutputs = class ActionOutputs extends Context.Service()("@effected/github-actions/ActionOutputs") {
+	static layer = Layer.effect(this, make);
+	/** A test double. Unstubbed members die rather than silently succeeding. */
+	static makeTest = (overrides = {}) => ({
+		set: () => Effect.sync(() => unimplemented("set")),
+		setJson: () => Effect.sync(() => unimplemented("setJson")),
+		summary: () => Effect.sync(() => unimplemented("summary")),
+		exportVariable: () => Effect.sync(() => unimplemented("exportVariable")),
+		addPath: () => Effect.sync(() => unimplemented("addPath")),
+		setFailed: () => Effect.sync(() => unimplemented("setFailed")),
+		setSecret: () => Effect.sync(() => unimplemented("setSecret")),
+		...overrides
+	});
+	/** {@link ActionOutputs.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ActionOutputs, ActionOutputs.makeTest(overrides));
+};
+
+//#endregion
+export { ActionOutputError, ActionOutputs };

package/ActionState.js

@@ -0,0 +1,117 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { ActionOutputs } from "./ActionOutputs.js";
+import { Context, Effect, FileSystem, Layer, Option, Schema } from "effect";
+
+//#region src/ActionState.ts
+/**
+* Raised when state cannot cross the phase boundary.
+*
+* @public
+*/
+var ActionStateError = class extends Schema.TaggedErrorClass()("ActionStateError", {
+	/**
+	* `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
+	* appended to.
+	*/
+	reason: Schema.Literals([
+		"missing",
+		"malformed",
+		"writeFailed"
+	]),
+	key: Schema.String,
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "missing": return `No action state was saved under "${this.key}"`;
+			case "malformed": return `Action state under "${this.key}" could not be decoded`;
+			default: return `Failed to persist action state under "${this.key}"`;
+		}
+	}
+};
+/** The runner republishes saved state as `STATE_<key>`. */
+const stateVariable = (key) => `STATE_${key}`;
+const make = Effect.gen(function* () {
+	const env = yield* ActionEnvironment;
+	const fs = yield* FileSystem.FileSystem;
+	const outputs = yield* ActionOutputs;
+	const write = (key, serialized) => Effect.gen(function* () {
+		const path = yield* env.get("GITHUB_STATE").pipe(Effect.mapError((cause) => new ActionStateError({
+			reason: "writeFailed",
+			key,
+			cause
+		})));
+		let delimiter = "EFFECTED_EOF";
+		while (serialized.includes(delimiter)) delimiter = `${delimiter}_`;
+		yield* fs.writeFileString(path, `${key}<<${delimiter}\n${serialized}\n${delimiter}\n`, { flag: "a" }).pipe(Effect.mapError((cause) => new ActionStateError({
+			reason: "writeFailed",
+			key,
+			cause
+		})));
+	});
+	const read = (key, schema) => Effect.gen(function* () {
+		const raw = yield* env.getOptional(stateVariable(key));
+		if (Option.isNone(raw)) return Option.none();
+		const parsed = yield* Effect.try({
+			try: () => JSON.parse(raw.value),
+			catch: (cause) => new ActionStateError({
+				reason: "malformed",
+				key,
+				cause
+			})
+		});
+		const decoded = yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(Effect.mapError((cause) => new ActionStateError({
+			reason: "malformed",
+			key,
+			cause
+		})));
+		return Option.some(decoded);
+	});
+	const save = (key, value, schema) => Schema.encodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => new ActionStateError({
+		reason: "malformed",
+		key,
+		cause
+	})), Effect.flatMap((encoded) => write(key, JSON.stringify(encoded))));
+	return {
+		save,
+		getOptional: read,
+		get: (key, schema) => Effect.flatMap(read(key, schema), (found) => Option.isSome(found) ? Effect.succeed(found.value) : Effect.fail(new ActionStateError({
+			reason: "missing",
+			key
+		}))),
+		saveSecret: (key, secret) => Effect.flatMap(outputs.setSecret(secret), () => write(key, JSON.stringify(secret)))
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`ActionState.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* State that survives the `pre` → `main` → `post` phase boundary.
+*
+* @remarks
+* Each phase of an action is a **separate process**. GitHub's protocol is a
+* 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.
+*
+* @public
+*/
+var ActionState = class ActionState extends Context.Service()("@effected/github-actions/ActionState") {
+	static layer = Layer.effect(this, make);
+	/** A test double. Unstubbed members die rather than answering wrongly. */
+	static makeTest = (overrides = {}) => ({
+		save: () => Effect.sync(() => unimplemented("save")),
+		get: () => Effect.sync(() => unimplemented("get")),
+		getOptional: () => Effect.sync(() => unimplemented("getOptional")),
+		saveSecret: () => Effect.sync(() => unimplemented("saveSecret")),
+		...overrides
+	});
+	/** {@link ActionState.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(ActionState, ActionState.makeTest(overrides));
+};
+
+//#endregion
+export { ActionState, ActionStateError };