@savvy-web/github-action-effects 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Savvy Web Strategy, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @savvy-web/github-action-effects
+
+[![npm version](https://img.shields.io/npm/v/@savvy-web/github-action-effects)](https://www.npmjs.com/package/@savvy-web/github-action-effects)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Build GitHub Actions with [Effect](https://effect.website) -- schema-validated
+inputs, structured logging with buffered output, and type-safe outputs through
+composable service layers.
+
+## Features
+
+- **Schema-validated inputs and outputs** using Effect Schema
+- **Three-tier action logger** (info/verbose/debug) with automatic log buffering
+- **GitHub Flavored Markdown builders** for step summaries
+- **Test layers for every service** -- no mocking `@actions/core` required
+- **Full TypeScript** with strict mode and ESM
+
+## Installation
+
+```bash
+npm install @savvy-web/github-action-effects effect @actions/core
+```
+
+## Quick Start
+
+```typescript
+import { Effect, Layer, Schema } from "effect";
+import {
+  ActionInputs,
+  ActionInputsLive,
+  ActionOutputs,
+  ActionOutputsLive,
+  ActionLoggerLive,
+  ActionLoggerLayer,
+  LogLevelInput,
+  resolveLogLevel,
+  setLogLevel,
+  table,
+} from "@savvy-web/github-action-effects";
+
+const program = Effect.gen(function* () {
+  const inputs = yield* ActionInputs;
+  const outputs = yield* ActionOutputs;
+
+  const level = yield* inputs.get("log-level", LogLevelInput);
+  yield* setLogLevel(resolveLogLevel(level));
+
+  const name = yield* inputs.get("name", Schema.String);
+  yield* outputs.set("greeting", `Hello, ${name}!`);
+  yield* outputs.summary(table(["Input", "Value"], [["name", name]]));
+});
+
+const MainLive = Layer.mergeAll(
+  ActionInputsLive,
+  ActionOutputsLive,
+  ActionLoggerLive,
+);
+
+program.pipe(
+  Effect.provide(ActionLoggerLayer),
+  Effect.provide(MainLive),
+  Effect.runPromise,
+);
+```
+
+## Documentation
+
+For architecture, API reference, testing guides, and advanced usage, see
+[docs](./docs/).
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,416 @@
+/**
+ * \@savvy-web/github-action-effects
+ *
+ * Effect-based utility library for building robust, well-logged,
+ * and schema-validated GitHub Actions.
+ *
+ * @packageDocumentation
+ */
+
+import type { AnnotationProperties } from '@actions/core';
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Equals } from 'effect/Types';
+import { FiberRef } from 'effect';
+import { Layer } from 'effect';
+import { Logger } from 'effect';
+import type { Option } from 'effect';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+/**
+ * Error when a GitHub Action input is missing or fails schema validation.
+ */
+export declare class ActionInputError extends ActionInputErrorBase<{
+    /** The input name from action.yml. */
+    readonly inputName: string;
+    /** Human-readable description of what went wrong. */
+    readonly reason: string;
+    /** The raw string value received, if any. */
+    readonly rawValue: string | undefined;
+}> {
+}
+
+/**
+ * Base class for ActionInputError.
+ *
+ * @internal
+ */
+export declare const ActionInputErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "ActionInputError";
+} & Readonly<A>;
+
+/**
+ * Service interface for reading GitHub Action inputs with schema validation.
+ *
+ * @public
+ */
+export declare interface ActionInputs {
+    /**
+     * Read a required input and validate it against a schema.
+     */
+    readonly get: <A, I>(name: string, schema: Schema.Schema<A, I, never>) => Effect.Effect<A, ActionInputError>;
+    /**
+     * Read an optional input. Returns `Option.none()` if empty.
+     */
+    readonly getOptional: <A, I>(name: string, schema: Schema.Schema<A, I, never>) => Effect.Effect<Option.Option<A>, ActionInputError>;
+    /**
+     * Read a required input and mask it as a secret in logs.
+     */
+    readonly getSecret: <A, I>(name: string, schema: Schema.Schema<A, I, never>) => Effect.Effect<A, ActionInputError>;
+    /**
+     * Read a required input as a JSON string, parse and validate it.
+     */
+    readonly getJson: <A, I>(name: string, schema: Schema.Schema<A, I, never>) => Effect.Effect<A, ActionInputError>;
+}
+
+/**
+ * ActionInputs tag for dependency injection.
+ *
+ * @public
+ */
+export declare const ActionInputs: Context.Tag<ActionInputs, ActionInputs>;
+
+export declare const ActionInputsLive: Layer.Layer<ActionInputs>;
+
+/**
+ * Test implementation that reads from a provided record.
+ *
+ * @example
+ * ```ts
+ * const layer = ActionInputsTest.layer({ "package-name": "my-pkg" });
+ * ```
+ */
+export declare const ActionInputsTest: {
+    readonly layer: (inputs: Record<string, string>) => Layer.Layer<ActionInputs, never, never>;
+};
+
+/**
+ * Service interface for action-specific logging operations beyond the Effect Logger.
+ *
+ * @remarks
+ * The core log-level routing is handled by the Effect Logger installed
+ * via {@link ActionLoggerLayer}. This service provides additional
+ * GitHub Actions-specific operations like log groups and buffering.
+ *
+ * @public
+ */
+export declare interface ActionLogger {
+    /**
+     * Run an effect inside a collapsible log group.
+     */
+    readonly group: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Run an effect with buffered logging. At `info` level, verbose output
+     * is captured in memory. On success the buffer is discarded. On failure
+     * the buffer is flushed before the error is reported.
+     */
+    readonly withBuffer: <A, E, R>(label: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    /**
+     * Emit an error annotation (red, blocks PR checks).
+     */
+    readonly annotationError: (message: string, properties?: AnnotationProperties) => Effect.Effect<void>;
+    /**
+     * Emit a warning annotation (yellow, informational).
+     */
+    readonly annotationWarning: (message: string, properties?: AnnotationProperties) => Effect.Effect<void>;
+    /**
+     * Emit a notice annotation (blue, informational).
+     */
+    readonly annotationNotice: (message: string, properties?: AnnotationProperties) => Effect.Effect<void>;
+}
+
+/**
+ * ActionLogger tag for dependency injection.
+ *
+ * @public
+ */
+export declare const ActionLogger: Context.Tag<ActionLogger, ActionLogger>;
+
+/**
+ * Layer that installs the GitHub Actions logger as the default Effect logger.
+ */
+export declare const ActionLoggerLayer: Layer.Layer<never>;
+
+/**
+ * Live implementation of the ActionLogger service.
+ */
+export declare const ActionLoggerLive: Layer.Layer<ActionLogger>;
+
+/**
+ * Test implementation that captures log operations in memory.
+ *
+ * @example
+ * ```ts
+ * const state = ActionLoggerTest.empty();
+ * const layer = ActionLoggerTest.layer(state);
+ * ```
+ */
+export declare const ActionLoggerTest: {
+    /**
+     * Create a fresh empty test state container.
+     */
+    readonly empty: () => ActionLoggerTestState;
+    /**
+     * Create a test layer from the given state.
+     */
+    readonly layer: (state: ActionLoggerTestState) => Layer.Layer<ActionLogger, never, never>;
+};
+
+/**
+ * In-memory state captured by the test logger.
+ */
+export declare interface ActionLoggerTestState {
+    readonly entries: Array<{
+        readonly level: string;
+        readonly message: string;
+    }>;
+    readonly groups: Array<{
+        readonly name: string;
+        readonly entries: Array<{
+            readonly level: string;
+            readonly message: string;
+        }>;
+    }>;
+    readonly annotations: Array<{
+        readonly type: TestAnnotationType;
+        readonly message: string;
+        readonly properties?: AnnotationProperties;
+    }>;
+    readonly flushedBuffers: Array<{
+        readonly label: string;
+        readonly entries: Array<string>;
+    }>;
+}
+
+/**
+ * The three log levels supported by the action logger.
+ *
+ * - `info` — Buffered. Shows only outcome summaries. Flushes verbose buffer on failure.
+ * - `verbose` — Unbuffered milestones. Start/finish markers for operations.
+ * - `debug` — Everything. Full command output, input/output values, internal state.
+ */
+export declare const ActionLogLevel: Schema.Literal<["info", "verbose", "debug"]>;
+
+export declare type ActionLogLevel = typeof ActionLogLevel.Type;
+
+/**
+ * Error when a GitHub Action output fails schema validation or writing.
+ */
+export declare class ActionOutputError extends ActionOutputErrorBase<{
+    /** The output name. */
+    readonly outputName: string;
+    /** Human-readable description of what went wrong. */
+    readonly reason: string;
+}> {
+}
+
+/**
+ * Base class for ActionOutputError.
+ *
+ * @internal
+ */
+export declare const ActionOutputErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "ActionOutputError";
+} & Readonly<A>;
+
+/**
+ * Service interface for setting GitHub Action outputs with schema validation.
+ *
+ * @public
+ */
+export declare interface ActionOutputs {
+    /**
+     * Set a string output value.
+     */
+    readonly set: (name: string, value: string) => Effect.Effect<void>;
+    /**
+     * Serialize a value as JSON and set it as an output.
+     * Validates against the schema before serializing.
+     */
+    readonly setJson: <A, I>(name: string, value: A, schema: Schema.Schema<A, I, never>) => Effect.Effect<void, ActionOutputError>;
+    /**
+     * Write markdown content to the step summary.
+     */
+    readonly summary: (content: string) => Effect.Effect<void, ActionOutputError>;
+    /**
+     * Export an environment variable for subsequent steps.
+     */
+    readonly exportVariable: (name: string, value: string) => Effect.Effect<void>;
+    /**
+     * Add a directory to PATH for subsequent steps.
+     */
+    readonly addPath: (path: string) => Effect.Effect<void>;
+}
+
+/**
+ * ActionOutputs tag for dependency injection.
+ *
+ * @public
+ */
+export declare const ActionOutputs: Context.Tag<ActionOutputs, ActionOutputs>;
+
+export declare const ActionOutputsLive: Layer.Layer<ActionOutputs>;
+
+/**
+ * Test implementation that captures outputs in memory.
+ *
+ * @example
+ * ```ts
+ * const state = ActionOutputsTest.empty();
+ * const layer = ActionOutputsTest.layer(state);
+ * ```
+ */
+export declare const ActionOutputsTest: {
+    /**
+     * Create a fresh empty test state container.
+     */
+    readonly empty: () => ActionOutputsTestState;
+    /**
+     * Create a test layer from the given state.
+     */
+    readonly layer: (state: ActionOutputsTestState) => Layer.Layer<ActionOutputs, never, never>;
+};
+
+/**
+ * In-memory state captured by the test output layer.
+ */
+export declare interface ActionOutputsTestState {
+    readonly outputs: Array<CapturedOutput>;
+    readonly summaries: Array<string>;
+    readonly variables: Array<CapturedOutput>;
+    readonly paths: Array<string>;
+}
+
+/**
+ * Bold text.
+ */
+export declare const bold: (text: string) => string;
+
+/**
+ * A captured output entry.
+ */
+export declare const CapturedOutput: Schema.Struct<{
+    name: typeof Schema.String;
+    value: typeof Schema.String;
+}>;
+
+export declare type CapturedOutput = typeof CapturedOutput.Type;
+
+/**
+ * Build a checkbox checklist.
+ */
+export declare const checklist: (items: readonly {
+    readonly label: string;
+    readonly checked: boolean;
+}[]) => string;
+
+/**
+ * A single item in a checklist.
+ */
+export declare const ChecklistItem: Schema.Struct<{
+    label: typeof Schema.String;
+    checked: typeof Schema.Boolean;
+}>;
+
+export declare type ChecklistItem = typeof ChecklistItem.Type;
+
+/**
+ * Inline code.
+ */
+export declare const code: (text: string) => string;
+
+/**
+ * Fenced code block.
+ */
+export declare const codeBlock: (content: string, language?: string) => string;
+
+/**
+ * FiberRef that holds the current action log level for the fiber.
+ */
+export declare const CurrentLogLevel: FiberRef.FiberRef<ActionLogLevel>;
+
+/**
+ * Build a collapsible `<details>` block.
+ */
+export declare const details: (summary: string, content: string) => string;
+
+/**
+ * Build a markdown heading.
+ *
+ * @param level - Heading level 1-6, defaults to 2.
+ */
+export declare const heading: (text: string, level?: 1 | 2 | 3 | 4 | 5 | 6) => string;
+
+/**
+ * Build a markdown link.
+ */
+export declare const link: (text: string, url: string) => string;
+
+/**
+ * Build a bulleted list.
+ */
+export declare const list: (items: readonly string[]) => string;
+
+/**
+ * Log level input values accepted by the standardized `log-level` action input.
+ * Includes `auto` which resolves based on the GitHub Actions environment.
+ */
+export declare const LogLevelInput: Schema.Literal<["info", "verbose", "debug", "auto"]>;
+
+export declare type LogLevelInput = typeof LogLevelInput.Type;
+
+/**
+ * Create an Effect Logger that routes to GitHub Actions log functions.
+ *
+ * - Always writes to `core.debug()` (GitHub-gated shadow channel).
+ * - Writes to user-facing output based on the action log level.
+ */
+export declare const makeActionLogger: () => Logger.Logger<unknown, void>;
+
+/**
+ * Resolve a {@link LogLevelInput} to a concrete {@link ActionLogLevel}.
+ *
+ * `"auto"` resolves to `"info"` unless `RUNNER_DEBUG` is `"1"`,
+ * in which case it resolves to `"debug"`.
+ */
+export declare const resolveLogLevel: (input: "auto" | "debug" | "info" | "verbose") => "debug" | "info" | "verbose";
+
+/**
+ * Horizontal rule.
+ */
+export declare const rule: () => string;
+
+/**
+ * Set the action log level for the current scope.
+ */
+export declare const setLogLevel: (level: "debug" | "info" | "verbose") => Effect.Effect<void, never, never>;
+
+/**
+ * Status values for {@link statusIcon}.
+ */
+export declare const Status: Schema.Literal<["pass", "fail", "skip", "warn"]>;
+
+export declare type Status = typeof Status.Type;
+
+/**
+ * Map a {@link Status} to its emoji indicator.
+ */
+export declare const statusIcon: (status: "fail" | "pass" | "skip" | "warn") => string;
+
+/**
+ * Build a GFM table from headers and rows.
+ *
+ * @example
+ * ```ts
+ * table(["Name", "Status"], [["build", "pass"], ["test", "fail"]])
+ * ```
+ */
+export declare const table: (headers: readonly string[], rows: readonly (readonly string[])[]) => string;
+
+/**
+ * Annotation type captured by the test layer.
+ */
+export declare type TestAnnotationType = "error" | "warning" | "notice";
+
+export { }

package/index.js

@@ -0,0 +1,295 @@
+import { Context, Data, Effect, FiberRef, FiberRefs, Layer, LogLevel, Logger, Option, Schema } from "effect";
+import { addPath, debug, endGroup, error as core_error, exportVariable, getInput, info, notice, setOutput, setSecret, startGroup, summary as core_summary, warning } from "@actions/core";
+const ActionInputErrorBase = Data.TaggedError("ActionInputError");
+class ActionInputError extends ActionInputErrorBase {
+}
+const ActionOutputErrorBase = Data.TaggedError("ActionOutputError");
+class ActionOutputError extends ActionOutputErrorBase {
+}
+const ActionInputs = Context.GenericTag("ActionInputs");
+const decodeInput = (name, raw, schema)=>Schema.decode(schema)(raw).pipe(Effect.mapError((parseError)=>new ActionInputError({
+            inputName: name,
+            reason: `Input "${name}" validation failed: ${parseError.message}`,
+            rawValue: raw
+        })));
+const decodeJsonInput = (name, raw, schema)=>Effect["try"]({
+        try: ()=>JSON.parse(raw),
+        catch: (error)=>new ActionInputError({
+                inputName: name,
+                reason: `Input "${name}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+                rawValue: raw
+            })
+    }).pipe(Effect.flatMap((parsed)=>Schema.decode(schema)(parsed).pipe(Effect.mapError((parseError)=>new ActionInputError({
+                inputName: name,
+                reason: `Input "${name}" JSON validation failed: ${parseError.message}`,
+                rawValue: raw
+            })))));
+const ActionInputsLive = Layer.succeed(ActionInputs, {
+    get: (name, schema)=>Effect.sync(()=>getInput(name, {
+                required: true
+            })).pipe(Effect.flatMap((raw)=>decodeInput(name, raw, schema))),
+    getOptional: (name, schema)=>Effect.sync(()=>getInput(name, {
+                required: false
+            })).pipe(Effect.flatMap((raw)=>{
+            if ("" === raw) return Effect.succeed(Option.none());
+            return decodeInput(name, raw, schema).pipe(Effect.map((a)=>Option.some(a)));
+        })),
+    getSecret: (name, schema)=>Effect.sync(()=>{
+            const raw = getInput(name, {
+                required: true
+            });
+            setSecret(raw);
+            return raw;
+        }).pipe(Effect.flatMap((raw)=>decodeInput(name, raw, schema))),
+    getJson: (name, schema)=>Effect.sync(()=>getInput(name, {
+                required: true
+            })).pipe(Effect.flatMap((raw)=>decodeJsonInput(name, raw, schema)))
+});
+const missingInput = (name)=>new ActionInputError({
+        inputName: name,
+        reason: `Input "${name}" is required but not provided`,
+        rawValue: void 0
+    });
+const ActionInputsTest = {
+    layer: (inputs)=>Layer.succeed(ActionInputs, {
+            get: (name, schema)=>{
+                const raw = inputs[name];
+                if (void 0 === raw) return Effect.fail(missingInput(name));
+                return decodeInput(name, raw, schema);
+            },
+            getOptional: (name, schema)=>{
+                const raw = inputs[name];
+                if (void 0 === raw || "" === raw) return Effect.succeed(Option.none());
+                return decodeInput(name, raw, schema).pipe(Effect.map((a)=>Option.some(a)));
+            },
+            getSecret: (name, schema)=>{
+                const raw = inputs[name];
+                if (void 0 === raw) return Effect.fail(missingInput(name));
+                return decodeInput(name, raw, schema);
+            },
+            getJson: (name, schema)=>{
+                const raw = inputs[name];
+                if (void 0 === raw) return Effect.fail(missingInput(name));
+                return decodeJsonInput(name, raw, schema);
+            }
+        })
+};
+const ActionLogger = Context.GenericTag("ActionLogger");
+const CurrentLogLevel = FiberRef.unsafeMake("info");
+const setLogLevel = (level)=>FiberRef.set(CurrentLogLevel, level);
+const formatMessage = (message)=>{
+    const value = Array.isArray(message) && 1 === message.length ? message[0] : message;
+    return "string" == typeof value ? value : JSON.stringify(value);
+};
+const shouldEmitUserFacing = (effectLevel, actionLevel)=>{
+    if ("debug" === actionLevel) return true;
+    if ("verbose" === actionLevel) return LogLevel.greaterThanEqual(effectLevel, LogLevel.Info);
+    return LogLevel.greaterThanEqual(effectLevel, LogLevel.Warning);
+};
+const emitToGitHub = (level, message)=>{
+    if (LogLevel.greaterThanEqual(level, LogLevel.Error)) core_error(message);
+    else if (LogLevel.greaterThanEqual(level, LogLevel.Warning)) warning(message);
+    else info(message);
+};
+const makeActionLogger = ()=>Logger.make(({ logLevel, message, context })=>{
+        const text = formatMessage(message);
+        debug(text);
+        const actionLevel = FiberRefs.getOrDefault(context, CurrentLogLevel);
+        if (shouldEmitUserFacing(logLevel, actionLevel)) emitToGitHub(logLevel, text);
+    });
+const ActionLoggerLayer = Logger.replace(Logger.defaultLogger, makeActionLogger());
+const createBuffer = ()=>({
+        entries: []
+    });
+const flushBuffer = (label, buffer)=>{
+    if (buffer.entries.length > 0) {
+        info(`--- Buffered output for "${label}" ---`);
+        for (const entry of buffer.entries)info(entry);
+        info(`--- End buffered output for "${label}" ---`);
+    }
+};
+const ActionLoggerLive = Layer.succeed(ActionLogger, {
+    group: (name, effect)=>Effect.acquireUseRelease(Effect.sync(()=>startGroup(name)), ()=>effect, ()=>Effect.sync(()=>endGroup())),
+    withBuffer: (label, effect)=>FiberRef.get(CurrentLogLevel).pipe(Effect.flatMap((level)=>{
+            if ("info" !== level) return effect;
+            const buffer = createBuffer();
+            const bufferingLogger = Logger.make(({ logLevel, message })=>{
+                const text = formatMessage(message);
+                debug(text);
+                if (LogLevel.greaterThanEqual(logLevel, LogLevel.Warning)) emitToGitHub(logLevel, text);
+                else buffer.entries.push(text);
+            });
+            return effect.pipe(Logger.withMinimumLogLevel(LogLevel.All), Effect.provide(Logger.replace(Logger.defaultLogger, bufferingLogger)), Effect.tapErrorCause(()=>Effect.sync(()=>flushBuffer(label, buffer))));
+        })),
+    annotationError: (message, properties)=>Effect.sync(()=>{
+            void 0 !== properties ? core_error(message, properties) : core_error(message);
+        }),
+    annotationWarning: (message, properties)=>Effect.sync(()=>{
+            void 0 !== properties ? warning(message, properties) : warning(message);
+        }),
+    annotationNotice: (message, properties)=>Effect.sync(()=>{
+            void 0 !== properties ? notice(message, properties) : notice(message);
+        })
+});
+const makeAnnotation = (state, type)=>(message, properties)=>Effect.sync(()=>{
+            state.annotations.push({
+                type,
+                message,
+                ...void 0 !== properties ? {
+                    properties
+                } : {}
+            });
+        });
+const ActionLoggerTest = {
+    empty: ()=>({
+            entries: [],
+            groups: [],
+            annotations: [],
+            flushedBuffers: []
+        }),
+    layer: (state)=>Layer.succeed(ActionLogger, {
+            group: (name, effect)=>{
+                const groupEntries = [];
+                state.groups.push({
+                    name,
+                    entries: groupEntries
+                });
+                return effect;
+            },
+            withBuffer: (label, effect)=>FiberRef.get(CurrentLogLevel).pipe(Effect.flatMap((level)=>{
+                    if ("info" !== level) return effect;
+                    return effect.pipe(Effect.tapErrorCause(()=>Effect.sync(()=>{
+                            state.flushedBuffers.push({
+                                label,
+                                entries: []
+                            });
+                        })));
+                })),
+            annotationError: makeAnnotation(state, "error"),
+            annotationWarning: makeAnnotation(state, "warning"),
+            annotationNotice: makeAnnotation(state, "notice")
+        })
+};
+const ActionOutputs = Context.GenericTag("ActionOutputs");
+const ActionOutputsLive = Layer.succeed(ActionOutputs, {
+    set: (name, value)=>Effect.sync(()=>setOutput(name, value)),
+    setJson: (name, value, schema)=>Schema.encode(schema)(value).pipe(Effect.tap((encoded)=>Effect.sync(()=>setOutput(name, JSON.stringify(encoded)))), Effect.asVoid, Effect.mapError((parseError)=>new ActionOutputError({
+                outputName: name,
+                reason: `Output "${name}" validation failed: ${parseError.message}`
+            }))),
+    summary: (content)=>Effect.tryPromise({
+            try: ()=>core_summary.addRaw(content).write(),
+            catch: (error)=>new ActionOutputError({
+                    outputName: "summary",
+                    reason: `Failed to write step summary: ${error instanceof Error ? error.message : String(error)}`
+                })
+        }).pipe(Effect.asVoid),
+    exportVariable: (name, value)=>Effect.sync(()=>exportVariable(name, value)),
+    addPath: (path)=>Effect.sync(()=>addPath(path))
+});
+const ActionOutputsTest = {
+    empty: ()=>({
+            outputs: [],
+            summaries: [],
+            variables: [],
+            paths: []
+        }),
+    layer: (state)=>Layer.succeed(ActionOutputs, {
+            set: (name, value)=>Effect.sync(()=>{
+                    state.outputs.push({
+                        name,
+                        value
+                    });
+                }),
+            setJson: (name, value, schema)=>Schema.encode(schema)(value).pipe(Effect.tap((encoded)=>Effect.sync(()=>{
+                        state.outputs.push({
+                            name,
+                            value: JSON.stringify(encoded)
+                        });
+                    })), Effect.asVoid, Effect.mapError((parseError)=>new ActionOutputError({
+                        outputName: name,
+                        reason: `Output "${name}" validation failed: ${parseError.message}`
+                    }))),
+            summary: (content)=>Effect.sync(()=>{
+                    state.summaries.push(content);
+                }),
+            exportVariable: (name, value)=>Effect.sync(()=>{
+                    state.variables.push({
+                        name,
+                        value
+                    });
+                }),
+            addPath: (path)=>Effect.sync(()=>{
+                    state.paths.push(path);
+                })
+        })
+};
+const Status = Schema.Literal("pass", "fail", "skip", "warn").annotations({
+    identifier: "Status",
+    title: "Check Status",
+    description: "Status indicator for check run outcomes"
+});
+const ChecklistItem = Schema.Struct({
+    label: Schema.String,
+    checked: Schema.Boolean
+}).annotations({
+    identifier: "ChecklistItem",
+    title: "Checklist Item"
+});
+const CapturedOutput = Schema.Struct({
+    name: Schema.String,
+    value: Schema.String
+}).annotations({
+    identifier: "CapturedOutput",
+    title: "Captured Output"
+});
+const ActionLogLevel = Schema.Literal("info", "verbose", "debug").annotations({
+    identifier: "ActionLogLevel",
+    title: "Action Log Level",
+    description: "Logging verbosity for GitHub Action output"
+});
+const LogLevelInput = Schema.Literal("info", "verbose", "debug", "auto").annotations({
+    identifier: "LogLevelInput",
+    title: "Log Level Input",
+    description: "Logging verbosity: info, verbose, debug, or auto",
+    message: ()=>({
+            message: 'log-level must be one of: "info", "verbose", "debug", "auto"',
+            override: true
+        })
+});
+const resolveLogLevel = (input)=>{
+    if ("auto" !== input) return input;
+    return "1" === process.env.RUNNER_DEBUG ? "debug" : "info";
+};
+const table = (headers, rows)=>{
+    const headerRow = `| ${headers.join(" | ")} |`;
+    const separator = `| ${headers.map(()=>"---").join(" | ")} |`;
+    const dataRows = rows.map((row)=>`| ${row.join(" | ")} |`);
+    return [
+        headerRow,
+        separator,
+        ...dataRows
+    ].join("\n");
+};
+const heading = (text, level = 2)=>`${"#".repeat(level)} ${text}`;
+const details = (summary, content)=>`<details>\n<summary>${summary}</summary>\n\n${content}\n\n</details>`;
+const rule = ()=>"---";
+const statusIcon = (status)=>{
+    switch(status){
+        case "pass":
+            return "\u2705";
+        case "fail":
+            return "\u274C";
+        case "skip":
+            return "\uD83D\uDDC3\uFE0F";
+        case "warn":
+            return "\u26A0\uFE0F";
+    }
+};
+const GithubMarkdown_link = (text, url)=>`[${text}](${url})`;
+const list = (items)=>items.map((item)=>`- ${item}`).join("\n");
+const checklist = (items)=>items.map((item)=>`- [${item.checked ? "x" : " "}] ${item.label}`).join("\n");
+const bold = (text)=>`**${text}**`;
+const code = (text)=>`\`${text}\``;
+const codeBlock = (content, language = "")=>`\`\`\`${language}\n${content}\n\`\`\``;
+export { ActionInputError, ActionInputErrorBase, ActionInputs, ActionInputsLive, ActionInputsTest, ActionLogLevel, ActionLogger, ActionLoggerLayer, ActionLoggerLive, ActionLoggerTest, ActionOutputError, ActionOutputErrorBase, ActionOutputs, ActionOutputsLive, ActionOutputsTest, CapturedOutput, ChecklistItem, CurrentLogLevel, GithubMarkdown_link as link, LogLevelInput, Status, bold, checklist, code, codeBlock, details, heading, list, makeActionLogger, resolveLogLevel, rule, setLogLevel, statusIcon, table };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@savvy-web/github-action-effects",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Effect-based utility library for building robust, well-logged, and schema-validated GitHub Actions.",
+  "homepage": "https://github.com/savvy-web/github-action-effects#readme",
+  "bugs": {
+    "url": "https://github.com/savvy-web/github-action-effects/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/savvy-web/github-action-effects.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "C. Spencer Beggs",
+    "email": "spencer@savvyweb.systems",
+    "url": "https://savvyweb.systems"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "peerDependencies": {
+    "@actions/core": "^3.0.0",
+    "@actions/exec": "^3.0.0",
+    "@actions/github": "^9.0.0",
+    "@effect/platform": ">=0.94.0",
+    "@effect/platform-node": ">=0.104.0",
+    "effect": "^3.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@actions/core": {
+      "optional": false
+    },
+    "@actions/exec": {
+      "optional": true
+    },
+    "@actions/github": {
+      "optional": true
+    },
+    "@effect/platform": {
+      "optional": true
+    },
+    "@effect/platform-node": {
+      "optional": true
+    },
+    "effect": {
+      "optional": false
+    }
+  },
+  "files": [
+    "!github-action-effects.api.json",
+    "!tsconfig.json",
+    "!tsdoc.json",
+    "LICENSE",
+    "README.md",
+    "index.d.ts",
+    "index.js",
+    "package.json",
+    "tsdoc-metadata.json"
+  ]
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.6"
+    }
+  ]
+}