@savvy-web/github-action-effects 0.1.0 → 0.3.0

package/README.md

@@ -2,71 +2,49 @@
 
 [![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 
-Build GitHub Actions with [Effect](https://effect.website) -- schema-validated
-inputs, structured logging with buffered output, and type-safe outputs through
-composable service layers.
+Composable [Effect](https://effect.website) services for building Node.js 24 GitHub Actions with schema-validated inputs, structured logging, typed outputs and multi-phase state management without the boilerplate.
 
 ## 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
+- **Schema-validated inputs** — read, parse, and validate action inputs with Effect Schema
+- **Structured logging** — three-tier logger (info/verbose/debug) with buffer-on-failure
+- **Typed outputs** — set outputs, export variables, and write GFM job summaries
+- **Multi-phase state** — transfer schema-serialized state across pre/main/post phases
+- **In-memory test layers** — test every service without mocking `@actions/core`
 
 ## Installation
 
 ```bash
-npm install @savvy-web/github-action-effects effect @actions/core
+npm install @savvy-web/github-action-effects effect @actions/core @effect/platform @effect/platform-node
 ```
 
 ## 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";
+import { Effect, Schema } from "effect";
+import { Action, ActionInputs, ActionOutputs } 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 name = yield* inputs.get("package-name", Schema.String);
+  yield* outputs.set("result", `checked ${name}`);
 });
 
-const MainLive = Layer.mergeAll(
-  ActionInputsLive,
-  ActionOutputsLive,
-  ActionLoggerLive,
-);
-
-program.pipe(
-  Effect.provide(ActionLoggerLayer),
-  Effect.provide(MainLive),
-  Effect.runPromise,
-);
+Action.run(program);
 ```
 
+`Action.run` provides all core service layers (including `NodeContext.layer` for `FileSystem`, `Path`, `Terminal`, `CommandExecutor`, and `WorkerManager` from `@effect/platform`), installs the Effect logger, and catches errors with `core.setFailed` automatically.
+
+See the [full walkthrough](./docs/example-action.md) for log level configuration, batch input reading, GFM summaries, multi-phase state, and error handling.
+
 ## Documentation
 
-For architecture, API reference, testing guides, and advanced usage, see
-[docs](./docs/).
+- [Example Action](./docs/example-action.md) — end-to-end tutorial
+- [Architecture](./docs/architecture.md) — API reference and layer composition
+- [Testing](./docs/testing.md) — testing with in-memory layers
 
 ## License
 

package/index.d.ts

@@ -13,11 +13,69 @@ import { Effect } from 'effect';
 import { Equals } from 'effect/Types';
 import { FiberRef } from 'effect';
 import { Layer } from 'effect';
-import { Logger } from 'effect';
+import { Logger } from 'effect/Logger';
 import type { Option } from 'effect';
+import * as PlatformNode from '@effect/platform-node';
 import { Schema } from 'effect';
 import { YieldableError } from 'effect/Cause';
 
+/**
+ * Namespace for top-level GitHub Action helpers.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Action, ActionInputs, ActionLogger } from "@savvy-web/github-action-effects"
+ *
+ * const program = Effect.gen(function* () {
+ *   const inputs = yield* ActionInputs
+ *   const logger = yield* ActionLogger
+ *   // ... your action logic
+ * })
+ *
+ * Action.run(program)
+ * ```
+ *
+ * @public
+ */
+export declare const Action: {
+    /**
+     * Run a GitHub Action program with standard boilerplate handled.
+     *
+     * Handles:
+     * - Providing all standard Live layers (ActionInputs, ActionLogger, ActionOutputs)
+     * - Installing ActionLoggerLayer (routes Effect.log to core.info/debug)
+     * - Catching all errors and calling `core.setFailed`
+     * - Running with `Effect.runPromise`
+     *
+     * Returns a Promise that resolves when the action completes. In production
+     * the return value can be ignored (fire-and-forget). In tests, await it
+     * to avoid timing issues.
+     */
+    readonly run: {
+        <E>(program: Effect.Effect<void, E, CoreServices>): Promise<void>;
+        <E, R>(program: Effect.Effect<void, E, R | CoreServices>, layer: Layer.Layer<R, never, never>): Promise<void>;
+    };
+    /**
+     * Read and validate all inputs at once, with optional cross-validation.
+     *
+     * @example
+     * ```ts
+     * const inputs = yield* Action.parseInputs({
+     *   "app-id": { schema: Schema.NumberFromString, required: true },
+     *   "branch": { schema: Schema.String, default: "main" },
+     * })
+     * ```
+     */
+    readonly parseInputs: <T extends Record<string, InputConfig<Schema.Schema.AnyNoContext>>>(config: T, crossValidate?: ((parsed: ParsedInputs<T>) => Effect.Effect<ParsedInputs<T>, ActionInputError, never>) | undefined) => Effect.Effect<ParsedInputs<T>, ActionInputError, ActionInputs>;
+    /** Create an Effect Logger that routes to GitHub Actions log functions. */
+    readonly makeLogger: () => Logger<unknown, void>;
+    /** Set the action log level for the current scope. */
+    readonly setLogLevel: (level: "debug" | "info" | "verbose") => Effect.Effect<void, never, never>;
+    /** Resolve a LogLevelInput to a concrete ActionLogLevel. */
+    readonly resolveLogLevel: (input: "auto" | "debug" | "info" | "verbose") => "debug" | "info" | "verbose";
+};
+
 /**
  * Error when a GitHub Action input is missing or fails schema validation.
  */
@@ -62,6 +120,21 @@ export declare interface ActionInputs {
      * 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>;
+    /**
+     * Read a multiline input (newline-delimited list).
+     * Splits on newlines, trims each line, filters blank lines and comment lines (starting with #).
+     * Each remaining item is validated against the schema.
+     */
+    readonly getMultiline: <A, I>(name: string, itemSchema: Schema.Schema<A, I, never>) => Effect.Effect<Array<A>, ActionInputError>;
+    /**
+     * Read a boolean input. Accepts "true"/"false" (case-insensitive).
+     */
+    readonly getBoolean: (name: string) => Effect.Effect<boolean, ActionInputError>;
+    /**
+     * Read an optional boolean input with a default value.
+     * Returns the default if the input is not provided.
+     */
+    readonly getBooleanOptional: (name: string, defaultValue: boolean) => Effect.Effect<boolean, ActionInputError>;
 }
 
 /**
@@ -241,6 +314,16 @@ export declare interface ActionOutputs {
      * Add a directory to PATH for subsequent steps.
      */
     readonly addPath: (path: string) => Effect.Effect<void>;
+    /**
+     * Mark the action as failed with a message.
+     * This is the standard way to signal action failure.
+     */
+    readonly setFailed: (message: string) => Effect.Effect<void>;
+    /**
+     * Register a value as a secret so it is masked in logs.
+     * Use for values not read through ActionInputs (e.g., generated tokens).
+     */
+    readonly setSecret: (value: string) => Effect.Effect<void>;
 }
 
 /**
@@ -280,12 +363,93 @@ export declare interface ActionOutputsTestState {
     readonly summaries: Array<string>;
     readonly variables: Array<CapturedOutput>;
     readonly paths: Array<string>;
+    readonly secrets: Array<string>;
+    readonly failed: Array<string>;
 }
 
 /**
- * Bold text.
+ * Service interface for reading and writing GitHub Action state
+ * with schema-based serialization across action phases (pre/main/post).
+ *
+ * @public
  */
-export declare const bold: (text: string) => string;
+export declare interface ActionState {
+    /**
+     * Save a value to action state. Uses Schema.encode to serialize
+     * complex objects to JSON strings for storage.
+     */
+    readonly save: <A, I>(key: string, value: A, schema: Schema.Schema<A, I, never>) => Effect.Effect<void, ActionStateError>;
+    /**
+     * Read a required state value. Uses Schema.decode to deserialize
+     * and validate the stored JSON string.
+     */
+    readonly get: <A, I>(key: string, schema: Schema.Schema<A, I, never>) => Effect.Effect<A, ActionStateError>;
+    /**
+     * Read an optional state value. Returns Option.none() if the key
+     * has no stored value.
+     */
+    readonly getOptional: <A, I>(key: string, schema: Schema.Schema<A, I, never>) => Effect.Effect<Option.Option<A>, ActionStateError>;
+}
+
+/**
+ * ActionState tag for dependency injection.
+ *
+ * @public
+ */
+export declare const ActionState: Context.Tag<ActionState, ActionState>;
+
+/**
+ * Error when GitHub Action state reading/writing fails.
+ */
+export declare class ActionStateError extends ActionStateErrorBase<{
+    /** The state key name. */
+    readonly key: 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 ActionStateError.
+ *
+ * @internal
+ */
+export declare const ActionStateErrorBase: 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: "ActionStateError";
+} & Readonly<A>;
+
+export declare const ActionStateLive: Layer.Layer<ActionState>;
+
+/**
+ * Test implementation that captures state in memory.
+ *
+ * @example
+ * ```ts
+ * const state = ActionStateTest.empty();
+ * const layer = ActionStateTest.layer(state);
+ * ```
+ */
+export declare const ActionStateTest: {
+    /**
+     * Create a fresh empty test state container.
+     */
+    readonly empty: () => ActionStateTestState;
+    /**
+     * Create a test layer from the given state.
+     * Pre-populate entries to simulate state from a previous phase.
+     */
+    readonly layer: (state: ActionStateTestState) => Layer.Layer<ActionState, never, never>;
+};
+
+/**
+ * In-memory state captured by the test state layer.
+ */
+export declare interface ActionStateTestState {
+    /** Stored state entries (key to JSON string). */
+    readonly entries: Map<string, string>;
+}
 
 /**
  * A captured output entry.
@@ -297,14 +461,6 @@ export declare const CapturedOutput: Schema.Struct<{
 
 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.
  */
@@ -315,15 +471,8 @@ export declare const ChecklistItem: Schema.Struct<{
 
 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;
+/** Core services provided automatically by {@link Action.run}. */
+export declare type CoreServices = ActionInputs | ActionLogger | ActionOutputs | PlatformNode.NodeContext.NodeContext;
 
 /**
  * FiberRef that holds the current action log level for the fiber.
@@ -331,26 +480,94 @@ export declare const codeBlock: (content: string, language?: string) => string;
 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.
+ * Namespace for GitHub-Flavored Markdown builder functions.
  *
- * @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.
+ * @example
+ * ```ts
+ * import { GithubMarkdown } from "@savvy-web/github-action-effects"
+ *
+ * GithubMarkdown.table(["Name", "Status"], [["build", "pass"]])
+ * GithubMarkdown.bold("hello")
+ * ```
+ *
+ * @public
  */
-export declare const link: (text: string, url: string) => string;
+export declare const GithubMarkdown: {
+    /**
+     * Build a GFM table from headers and rows.
+     */
+    readonly table: (headers: readonly string[], rows: readonly (readonly string[])[]) => string;
+    /**
+     * Build a markdown heading.
+     *
+     * @param level - Heading level 1-6, defaults to 2.
+     */
+    readonly heading: (text: string, level?: 1 | 2 | 3 | 4 | 5 | 6) => string;
+    /**
+     * Build a collapsible `<details>` block.
+     */
+    readonly details: (summary: string, content: string) => string;
+    /**
+     * Horizontal rule.
+     */
+    readonly rule: () => string;
+    /**
+     * Map a {@link Status} to its emoji indicator.
+     */
+    readonly statusIcon: (status: "fail" | "pass" | "skip" | "warn") => string;
+    /**
+     * Build a markdown link.
+     */
+    readonly link: (text: string, url: string) => string;
+    /**
+     * Build a bulleted list.
+     */
+    readonly list: (items: readonly string[]) => string;
+    /**
+     * Build a checkbox checklist.
+     */
+    readonly checklist: (items: readonly {
+        readonly label: string;
+        readonly checked: boolean;
+    }[]) => string;
+    /**
+     * Bold text.
+     */
+    readonly bold: (text: string) => string;
+    /**
+     * Inline code.
+     */
+    readonly code: (text: string) => string;
+    /**
+     * Fenced code block.
+     */
+    readonly codeBlock: (content: string, language?: string) => string;
+};
 
 /**
- * Build a bulleted list.
+ * Configuration for a single input in {@link Action.parseInputs}.
+ *
+ * Precedence rules for how an input is read:
+ * 1. `json: true` — reads as JSON string, parses and validates (always required)
+ * 2. `multiline: true` — reads as newline-delimited list (always required)
+ * 3. `secret: true` — reads and masks the value (always required)
+ * 4. `default` is set — reads as optional, falls back to default if missing
+ * 5. `required: false` — reads as optional, returns undefined if missing
+ * 6. Otherwise — reads as required (default behavior)
+ *
+ * When `json`, `multiline`, or `secret` is set, the input is always
+ * treated as required regardless of `required` or `default` values.
+ *
+ * @public
  */
-export declare const list: (items: readonly string[]) => string;
+export declare interface InputConfig<S extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext> {
+    readonly schema: S;
+    readonly required?: boolean;
+    readonly default?: Schema.Schema.Type<S>;
+    readonly multiline?: boolean;
+    readonly secret?: boolean;
+    readonly json?: boolean;
+}
 
 /**
  * Log level input values accepted by the standardized `log-level` action input.
@@ -361,30 +578,11 @@ export declare const LogLevelInput: Schema.Literal<["info", "verbose", "debug",
 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"`.
+ * Infer the output type from an input config record.
  */
-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>;
+export declare type ParsedInputs<T extends Record<string, InputConfig>> = {
+    readonly [K in keyof T]: T[K] extends InputConfig<infer S> ? Schema.Schema.Type<S> : never;
+};
 
 /**
  * Status values for {@link statusIcon}.
@@ -393,21 +591,6 @@ 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.
  */

package/index.js

@@ -1,11 +1,9 @@
-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";
+import { addPath, debug, endGroup, error as core_error, exportVariable, getInput, getMultilineInput, getState, info, notice, saveState, setFailed, setOutput, setSecret, startGroup, summary as core_summary, warning } from "@actions/core";
+import { NodeContext } from "@effect/platform-node";
+import { Cause, Context, Data, Effect, FiberRef, FiberRefs, Layer, LogLevel, Logger, Option, Schema } from "effect";
 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,
@@ -24,6 +22,16 @@ const decodeJsonInput = (name, raw, schema)=>Effect["try"]({
                 reason: `Input "${name}" JSON validation failed: ${parseError.message}`,
                 rawValue: raw
             })))));
+const parseBoolean = (name, raw)=>{
+    const lower = raw.toLowerCase().trim();
+    if ("true" === lower) return Effect.succeed(true);
+    if ("false" === lower) return Effect.succeed(false);
+    return Effect.fail(new ActionInputError({
+        inputName: name,
+        reason: `Input "${name}" is not a valid boolean: expected "true" or "false", got "${raw}"`,
+        rawValue: raw
+    }));
+};
 const ActionInputsLive = Layer.succeed(ActionInputs, {
     get: (name, schema)=>Effect.sync(()=>getInput(name, {
                 required: true
@@ -43,37 +51,20 @@ const ActionInputsLive = Layer.succeed(ActionInputs, {
         }).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)))
+            })).pipe(Effect.flatMap((raw)=>decodeJsonInput(name, raw, schema))),
+    getMultiline: (name, itemSchema)=>Effect.sync(()=>getMultilineInput(name, {
+                required: true
+            })).pipe(Effect.map((lines)=>lines.map((l)=>l.trim()).filter((l)=>l.length > 0 && !l.startsWith("#"))), Effect.flatMap((lines)=>Effect.forEach(lines, (line)=>decodeInput(name, line, itemSchema)))),
+    getBoolean: (name)=>Effect.sync(()=>getInput(name, {
+                required: true
+            })).pipe(Effect.flatMap((raw)=>parseBoolean(name, raw))),
+    getBooleanOptional: (name, defaultValue)=>Effect.sync(()=>getInput(name, {
+                required: false
+            })).pipe(Effect.flatMap((raw)=>{
+            if ("" === raw) return Effect.succeed(defaultValue);
+            return parseBoolean(name, raw);
+        }))
 });
-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);
@@ -131,6 +122,136 @@ const ActionLoggerLive = Layer.succeed(ActionLogger, {
             void 0 !== properties ? notice(message, properties) : notice(message);
         })
 });
+const ActionOutputErrorBase = Data.TaggedError("ActionOutputError");
+class ActionOutputError extends ActionOutputErrorBase {
+}
+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)),
+    setFailed: (message)=>Effect.sync(()=>setFailed(message)),
+    setSecret: (value)=>Effect.sync(()=>setSecret(value))
+});
+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 CoreLive = Layer.mergeAll(ActionInputsLive, ActionLoggerLive, ActionOutputsLive, NodeContext.layer);
+const Action = {
+    run: (program, layer)=>{
+        const fullLayer = layer ? Layer.mergeAll(CoreLive, layer) : CoreLive;
+        const runnable = program.pipe(Effect.provide(fullLayer), Effect.provide(ActionLoggerLayer), Effect.catchAllCause((cause)=>{
+            const message = Cause.pretty(cause);
+            return Effect.sync(()=>setFailed(`Action failed: ${message}`));
+        }));
+        return Effect.runPromise(runnable).catch(()=>{
+            process.exitCode = 1;
+        });
+    },
+    parseInputs: (config, crossValidate)=>Effect.flatMap(ActionInputs, (svc)=>{
+            const entries = Object.entries(config);
+            return Effect.forEach(entries, ([name, cfg])=>{
+                const { schema, json, multiline, secret } = cfg;
+                const isOptional = false === cfg.required || void 0 !== cfg.default;
+                let readEffect;
+                readEffect = json ? svc.getJson(name, schema) : multiline ? svc.getMultiline(name, schema) : secret ? svc.getSecret(name, schema) : isOptional ? svc.getOptional(name, schema).pipe(Effect.map((opt)=>{
+                    if ("None" === opt._tag) return cfg.default;
+                    return opt.value;
+                })) : svc.get(name, schema);
+                return Effect.map(readEffect, (value)=>[
+                        name,
+                        value
+                    ]);
+            }).pipe(Effect.map((pairs)=>Object.fromEntries(pairs)), Effect.flatMap((parsed)=>crossValidate ? crossValidate(parsed) : Effect.succeed(parsed)));
+        }),
+    makeLogger: makeActionLogger,
+    setLogLevel: setLogLevel,
+    resolveLogLevel: resolveLogLevel
+};
+const ActionStateErrorBase = Data.TaggedError("ActionStateError");
+class ActionStateError extends ActionStateErrorBase {
+}
+const missingInput = (name)=>new ActionInputError({
+        inputName: name,
+        reason: `Input "${name}" is required but not provided`,
+        rawValue: void 0
+    });
+const ActionInputsTest_parseBoolean = (name, raw)=>{
+    const lower = raw.toLowerCase().trim();
+    if ("true" === lower) return Effect.succeed(true);
+    if ("false" === lower) return Effect.succeed(false);
+    return Effect.fail(new ActionInputError({
+        inputName: name,
+        reason: `Input "${name}" is not a valid boolean: expected "true" or "false", got "${raw}"`,
+        rawValue: raw
+    }));
+};
+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);
+            },
+            getMultiline: (name, itemSchema)=>{
+                const raw = inputs[name];
+                if (void 0 === raw) return Effect.fail(missingInput(name));
+                const lines = raw.split("\n").map((l)=>l.trim()).filter((l)=>l.length > 0 && !l.startsWith("#"));
+                return Effect.forEach(lines, (line)=>decodeInput(name, line, itemSchema));
+            },
+            getBoolean: (name)=>{
+                const raw = inputs[name];
+                if (void 0 === raw) return Effect.fail(missingInput(name));
+                return ActionInputsTest_parseBoolean(name, raw);
+            },
+            getBooleanOptional: (name, defaultValue)=>{
+                const raw = inputs[name];
+                if (void 0 === raw || "" === raw) return Effect.succeed(defaultValue);
+                return ActionInputsTest_parseBoolean(name, raw);
+            }
+        })
+};
 const makeAnnotation = (state, type)=>(message, properties)=>Effect.sync(()=>{
             state.annotations.push({
                 type,
@@ -170,29 +291,14 @@ const ActionLoggerTest = {
             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: []
+            paths: [],
+            secrets: [],
+            failed: []
         }),
     layer: (state)=>Layer.succeed(ActionOutputs, {
             set: (name, value)=>Effect.sync(()=>{
@@ -221,9 +327,72 @@ const ActionOutputsTest = {
                 }),
             addPath: (path)=>Effect.sync(()=>{
                     state.paths.push(path);
+                }),
+            setFailed: (message)=>Effect.sync(()=>{
+                    state.failed.push(message);
+                }),
+            setSecret: (value)=>Effect.sync(()=>{
+                    state.secrets.push(value);
                 })
         })
 };
+const ActionState = Context.GenericTag("ActionState");
+const encodeState = (key, value, schema)=>Schema.encode(schema)(value).pipe(Effect.map((encoded)=>JSON.stringify(encoded)), Effect.mapError((error)=>new ActionStateError({
+            key,
+            reason: `State "${key}" encode failed: ${error instanceof Error ? error.message : String(error)}`,
+            rawValue: void 0
+        })));
+const decodeState = (key, raw, schema)=>Effect["try"]({
+        try: ()=>JSON.parse(raw),
+        catch: (error)=>new ActionStateError({
+                key,
+                reason: `State "${key}" 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 ActionStateError({
+                key,
+                reason: `State "${key}" decode failed: ${parseError.message}`,
+                rawValue: raw
+            })))));
+const ActionStateLive = Layer.succeed(ActionState, {
+    save: (key, value, schema)=>encodeState(key, value, schema).pipe(Effect.tap((json)=>Effect.sync(()=>saveState(key, json))), Effect.asVoid),
+    get: (key, schema)=>Effect.sync(()=>getState(key)).pipe(Effect.flatMap((raw)=>{
+            if ("" === raw) return Effect.fail(new ActionStateError({
+                key,
+                reason: `State "${key}" is not set (phase ordering issue?)`,
+                rawValue: void 0
+            }));
+            return decodeState(key, raw, schema);
+        })),
+    getOptional: (key, schema)=>Effect.sync(()=>getState(key)).pipe(Effect.flatMap((raw)=>{
+            if ("" === raw) return Effect.succeed(Option.none());
+            return decodeState(key, raw, schema).pipe(Effect.map((a)=>Option.some(a)));
+        }))
+});
+const ActionStateTest = {
+    empty: ()=>({
+            entries: new Map()
+        }),
+    layer: (state)=>Layer.succeed(ActionState, {
+            save: (key, value, schema)=>encodeState(key, value, schema).pipe(Effect.tap((json)=>Effect.sync(()=>{
+                        state.entries.set(key, json);
+                    })), Effect.asVoid),
+            get: (key, schema)=>{
+                const raw = state.entries.get(key);
+                if (void 0 === raw) return Effect.fail(new ActionStateError({
+                    key,
+                    reason: `State "${key}" is not set (phase ordering issue?)`,
+                    rawValue: void 0
+                }));
+                return decodeState(key, raw, schema);
+            },
+            getOptional: (key, schema)=>{
+                const raw = state.entries.get(key);
+                if (void 0 === raw) return Effect.succeed(Option.none());
+                return decodeState(key, raw, schema).pipe(Effect.map((a)=>Option.some(a)));
+            }
+        })
+};
 const Status = Schema.Literal("pass", "fail", "skip", "warn").annotations({
     identifier: "Status",
     title: "Check Status",
@@ -243,53 +412,37 @@ const CapturedOutput = Schema.Struct({
     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 = {
+    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");
+    },
+    heading: (text, level = 2)=>`${"#".repeat(level)} ${text}`,
+    details: (summary, content)=>`<details>\n<summary>${summary}</summary>\n\n${content}\n\n</details>`,
+    rule: ()=>"---",
+    statusIcon: (status)=>{
+        switch(status){
+            case "pass":
+                return "\u2705";
+            case "fail":
+                return "\u274C";
+            case "skip":
+                return "\uD83D\uDDC3\uFE0F";
+            case "warn":
+                return "\u26A0\uFE0F";
+        }
+    },
+    link: (text, url)=>`[${text}](${url})`,
+    list: (items)=>items.map((item)=>`- ${item}`).join("\n"),
+    checklist: (items)=>items.map((item)=>`- [${item.checked ? "x" : " "}] ${item.label}`).join("\n"),
+    bold: (text)=>`**${text}**`,
+    code: (text)=>`\`${text}\``,
+    codeBlock: (content, language = "")=>`\`\`\`${language}\n${content}\n\`\`\``
 };
-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 };
+export { Action, ActionInputError, ActionInputErrorBase, ActionInputs, ActionInputsLive, ActionInputsTest, ActionLogLevel, ActionLogger, ActionLoggerLayer, ActionLoggerLive, ActionLoggerTest, ActionOutputError, ActionOutputErrorBase, ActionOutputs, ActionOutputsLive, ActionOutputsTest, ActionState, ActionStateError, ActionStateErrorBase, ActionStateLive, ActionStateTest, CapturedOutput, ChecklistItem, CurrentLogLevel, GithubMarkdown, LogLevelInput, Status };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvy-web/github-action-effects",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -43,10 +43,10 @@
       "optional": true
     },
     "@effect/platform": {
-      "optional": true
+      "optional": false
     },
     "@effect/platform-node": {
-      "optional": true
+      "optional": false
     },
     "effect": {
       "optional": false