@savvy-web/github-action-builder 0.7.3 → 0.7.5

package/schemas/config.js

@@ -0,0 +1,190 @@
+import { Schema } from "effect";
+
+//#region src/schemas/config.ts
+/**
+* Configuration schemas for GitHub Action Builder using Effect Schema.
+*
+* @remarks
+* This module defines the schemas for validating configuration
+* and provides the {@link defineConfig} helper for type-safe configuration files.
+*
+* @internal
+*/
+/**
+* Schema for entry point paths.
+*
+* @remarks
+* GitHub Actions support three entry points:
+* - `main`: The primary action entry point (required)
+* - `pre`: Runs before the main action (optional)
+* - `post`: Runs after the main action for cleanup (optional)
+*
+* @internal
+*/
+const EntriesSchema = Schema.Struct({
+	/** Path to the main action entry point. Defaults to "src/main.ts". */
+	main: Schema.optionalWith(Schema.String, { default: () => "src/main.ts" }),
+	/** Path to the pre-action hook entry point. */
+	pre: Schema.optional(Schema.String),
+	/** Path to the post-action hook entry point. */
+	post: Schema.optional(Schema.String)
+});
+/**
+* Schema for build options.
+*
+* @remarks
+* Build options control how the TypeScript source is bundled using rsbuild.
+* The bundler creates a single JavaScript file with all dependencies inlined.
+*
+* @internal
+*/
+const BuildOptionsSchema = Schema.Struct({
+	/** Enable minification to reduce bundle size. Defaults to true. */
+	minify: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	/** Generate source maps for debugging. Defaults to false. */
+	sourceMap: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	/** Packages to exclude from the bundle (in addition to node: builtins). Defaults to []. */
+	externals: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+	/** Packages to exclude from the bundle and replace with a stub that throws if loaded at runtime. Use for optional transitive dependencies the action never exercises (e.g. native modules). Defaults to []. */
+	ignore: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] })
+});
+/**
+* Schema for validation options.
+*
+* @remarks
+* Validation options control how strictly the build process validates
+* the project structure and configuration before building.
+*
+* @internal
+*/
+const ValidationOptionsSchema = Schema.Struct({
+	/** Require action.yml to exist and be valid. Defaults to true. */
+	requireActionYml: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	/** Maximum bundle size before warning/error (e.g., "5mb", "500kb"). */
+	maxBundleSize: Schema.optional(Schema.String),
+	/** Treat warnings as errors. Auto-detects from CI when undefined. */
+	strict: Schema.optional(Schema.Boolean)
+});
+/**
+* Schema for persist-local options.
+*
+* @remarks
+* Controls automatic copying of build output to a local action directory
+* for testing with nektos/act.
+*
+* @internal
+*/
+const PersistLocalOptionsSchema = Schema.Struct({
+	/** Enable persisting build output locally. Defaults to true. */
+	enabled: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	/** Path for the local action directory, relative to cwd. Defaults to ".github/actions/local". */
+	path: Schema.optionalWith(Schema.String, { default: () => ".github/actions/local" }),
+	/** Generate act boilerplate files (.actrc, act-test.yml) if they don't exist. Defaults to true. */
+	actTemplate: Schema.optionalWith(Schema.Boolean, { default: () => true })
+});
+/**
+* User-provided configuration input (all fields optional).
+*
+* @remarks
+* This schema is used for parsing user-provided configuration.
+* All sections are optional; defaults are applied via {@link defineConfig}.
+*
+* @internal
+*/
+const ConfigInputSchema = Schema.Struct({
+	entries: Schema.optional(Schema.Struct({
+		main: Schema.optional(Schema.String),
+		pre: Schema.optional(Schema.String),
+		post: Schema.optional(Schema.String)
+	})),
+	build: Schema.optional(Schema.Struct({
+		minify: Schema.optional(Schema.Boolean),
+		sourceMap: Schema.optional(Schema.Boolean),
+		externals: Schema.optional(Schema.Array(Schema.String)),
+		ignore: Schema.optional(Schema.Array(Schema.String))
+	})),
+	validation: Schema.optional(Schema.Struct({
+		requireActionYml: Schema.optional(Schema.Boolean),
+		maxBundleSize: Schema.optional(Schema.String),
+		strict: Schema.optional(Schema.Boolean)
+	})),
+	persistLocal: Schema.optional(Schema.Struct({
+		enabled: Schema.optional(Schema.Boolean),
+		path: Schema.optional(Schema.String),
+		actTemplate: Schema.optional(Schema.Boolean)
+	}))
+});
+/**
+* Fully resolved configuration with all defaults applied.
+*
+* @internal
+*/
+const ConfigSchema = Schema.Struct({
+	entries: EntriesSchema,
+	build: BuildOptionsSchema,
+	validation: ValidationOptionsSchema,
+	persistLocal: PersistLocalOptionsSchema
+});
+/**
+* Define a configuration with full TypeScript support.
+*
+* @remarks
+* This function validates the configuration and applies all defaults.
+* Use it in your `action.config.ts` file for autocomplete and type checking.
+*
+* @param config - Partial configuration object
+* @returns Fully resolved configuration with defaults applied
+*
+* @example Basic configuration file
+* ```typescript
+* // action.config.ts
+* import { defineConfig } from "@savvy-web/github-action-builder";
+*
+* export default defineConfig({
+*   entries: {
+*     main: "src/main.ts",
+*   },
+*   build: {
+*     minify: true,
+*   },
+* });
+* ```
+*
+* @example Full configuration with all options
+* ```typescript
+* // action.config.ts
+* import { defineConfig } from "@savvy-web/github-action-builder";
+*
+* export default defineConfig({
+*   entries: {
+*     main: "src/action.ts",
+*     pre: "src/setup.ts",
+*     post: "src/cleanup.ts",
+*   },
+*   build: {
+*     minify: true,
+*     sourceMap: true,
+*     externals: ["@aws-sdk/client-s3"],
+*     ignore: ["libxmljs2"],
+*   },
+*   validation: {
+*     requireActionYml: true,
+*     maxBundleSize: "10mb",
+*     strict: true,
+*   },
+* });
+* ```
+*
+* @public
+*/
+function defineConfig(config = {}) {
+	return Schema.decodeUnknownSync(ConfigSchema)({
+		entries: config.entries ?? {},
+		build: config.build ?? {},
+		validation: config.validation ?? {},
+		persistLocal: config.persistLocal ?? {}
+	});
+}
+
+//#endregion
+export { BuildOptionsSchema, ConfigInputSchema, ConfigSchema, EntriesSchema, PersistLocalOptionsSchema, ValidationOptionsSchema, defineConfig };

package/schemas/path.js

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+import { fileURLToPath } from "node:url";
+
+//#region src/schemas/path.ts
+/**
+* Convert a PathLike value to a string.
+*
+* @param pathLike - A string, Buffer, or URL path
+* @returns The path as a string
+*
+* @internal
+*/
+/* v8 ignore start - edge case branches for Buffer/URL paths */
+function pathLikeToString(pathLike) {
+	if (typeof pathLike === "string") return pathLike;
+	if (Buffer.isBuffer(pathLike)) return pathLike.toString("utf8");
+	if (pathLike instanceof URL) return fileURLToPath(pathLike);
+	return String(pathLike);
+}
+/* v8 ignore stop */
+/**
+* Schema that accepts PathLike (string, Buffer, or URL) and normalizes to string.
+*
+* @remarks
+* This schema is designed for user-facing inputs where flexibility is important.
+* Internally, paths are stored as strings for serialization compatibility.
+*
+* @internal
+*/
+const PathLikeSchema = Schema.transform(Schema.Union(Schema.String, Schema.instanceOf(Buffer), Schema.instanceOf(URL)), Schema.String, {
+	strict: true,
+	decode: (pathLike) => pathLikeToString(pathLike),
+	/* v8 ignore next */
+	encode: (s) => s
+});
+/**
+* Optional PathLike schema.
+* @internal
+*/
+const OptionalPathLikeSchema = Schema.optional(PathLikeSchema);
+
+//#endregion
+export { OptionalPathLikeSchema };

package/services/build-live.js

@@ -0,0 +1,223 @@
+import { BundleFailed, CleanError, WriteError } from "../errors.js";
+import { BuildService } from "./build.js";
+import { ConfigService } from "./config.js";
+import { Effect, Layer } from "effect";
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createRsbuild } from "@rsbuild/core";
+
+//#region src/services/build-live.ts
+/* v8 ignore start - build service requires actual bundling for integration testing */
+/**
+* BuildService Layer implementation.
+*
+*/
+/**
+* Source of the stub module that replaces packages listed in `build.ignore`.
+* It is bundled in place of the real module and throws if ever loaded.
+*/
+const IGNORE_STUB_SOURCE = `throw new Error("A module excluded via the build 'ignore' option was loaded at runtime.");\n`;
+/**
+* Format bytes as a human-readable string.
+*/
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+* Format build result for terminal output.
+*/
+/* v8 ignore start - formatting function tested via integration */
+function formatBuildResult(result) {
+	const lines = [];
+	if (result.success) {
+		lines.push("Build Summary:");
+		for (const entry of result.entries) if (entry.success && entry.stats) {
+			const { entry: name, size, duration, outputPath } = entry.stats;
+			lines.push(`  ✓ ${name}: ${formatBytes(size)} (${duration}ms) → ${outputPath}`);
+		}
+		lines.push(`\nTotal time: ${result.duration}ms`);
+	} else {
+		lines.push("Build Failed:");
+		for (const entry of result.entries) if (!entry.success) lines.push(`  ✗ ${entry.error}`);
+	}
+	return lines.join("\n");
+}
+/* v8 ignore stop */
+/**
+* Clean output directory.
+*/
+function cleanDirectory(dir) {
+	return Effect.try({
+		try: () => {
+			if (existsSync(dir)) rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		},
+		/* v8 ignore next 5 - error branch requires fs permission failures */
+		catch: (error) => new CleanError({
+			directory: dir,
+			cause: error
+		})
+	});
+}
+/**
+* Write file with directory creation.
+*/
+function writeFile(path, content) {
+	return Effect.try({
+		try: () => {
+			mkdirSync(resolve(path, ".."), { recursive: true });
+			writeFileSync(path, content, "utf8");
+		},
+		/* v8 ignore next 5 - error branch requires fs permission failures */
+		catch: (error) => new WriteError({
+			path,
+			cause: error
+		})
+	});
+}
+/**
+* Bundle a single entry with rsbuild.
+*/
+/* v8 ignore start - bundling requires actual rsbuild execution */
+function bundleEntry(entry, config, cwd) {
+	return Effect.gen(function* () {
+		const startTime = Date.now();
+		const outputDir = resolve(cwd, "dist");
+		const externalsSet = new Set(config.build.externals);
+		const ignoreSet = new Set(config.build.ignore);
+		const ignoreAlias = {};
+		if (config.build.ignore.length > 0) {
+			const stubPath = resolve(cwd, "node_modules", ".cache", "github-action-builder", "ignore-stub.mjs");
+			yield* writeFile(stubPath, IGNORE_STUB_SOURCE);
+			for (const moduleName of config.build.ignore) ignoreAlias[`${moduleName}$`] = stubPath;
+		}
+		const rsbuild = yield* Effect.tryPromise({
+			try: () => createRsbuild({ rsbuildConfig: {
+				source: { entry: { [entry.type]: entry.path } },
+				resolve: { alias: ignoreAlias },
+				output: {
+					target: "node",
+					module: true,
+					distPath: { root: outputDir },
+					filename: { js: "[name].js" },
+					externals: (data) => {
+						const request = data.request;
+						if (!request) return false;
+						if (request.startsWith("node:")) return `node-commonjs ${request}`;
+						if (externalsSet.has(request) && !ignoreSet.has(request)) return request;
+						return false;
+					},
+					cleanDistPath: false,
+					legalComments: "inline",
+					minify: config.build.minify,
+					sourceMap: config.build.sourceMap ? { js: "source-map" } : false
+				},
+				performance: { chunkSplit: { strategy: "all-in-one" } },
+				tools: { rspack: {
+					node: {
+						__dirname: "node-module",
+						__filename: "node-module"
+					},
+					output: { asyncChunks: false }
+				} }
+			} }),
+			catch: (error) => new BundleFailed({
+				entry: entry.path,
+				cause: error
+			})
+		});
+		const buildResult = yield* Effect.tryPromise({
+			try: () => rsbuild.build(),
+			catch: (error) => new BundleFailed({
+				entry: entry.path,
+				cause: error
+			})
+		});
+		yield* Effect.tryPromise({
+			try: () => buildResult.close(),
+			catch: (error) => new BundleFailed({
+				entry: entry.path,
+				cause: /* @__PURE__ */ new Error(`rsbuild close() failed: ${error}`)
+			})
+		});
+		const outputPath = resolve(outputDir, `${entry.type}.js`);
+		const size = yield* Effect.try({
+			try: () => statSync(outputPath).size,
+			catch: (error) => new BundleFailed({
+				entry: entry.path,
+				cause: error
+			})
+		});
+		const duration = Date.now() - startTime;
+		return {
+			success: true,
+			stats: {
+				entry: entry.type,
+				size,
+				duration,
+				outputPath: entry.output
+			}
+		};
+	});
+}
+/* v8 ignore stop */
+/**
+* Live implementation of BuildService.
+*
+* @remarks
+* Uses rsbuild for bundling.
+*/
+const BuildServiceLive = Layer.effect(BuildService, Effect.gen(function* () {
+	const configService = yield* ConfigService;
+	return {
+		/* v8 ignore start - build execution requires actual rsbuild bundling */
+		build: (config, options = {}) => Effect.gen(function* () {
+			const cwd = options.cwd ?? process.cwd();
+			const shouldClean = options.clean ?? true;
+			const startTime = Date.now();
+			const entriesConfig = { main: config.entries.main };
+			if (config.entries.pre) entriesConfig.pre = config.entries.pre;
+			if (config.entries.post) entriesConfig.post = config.entries.post;
+			const entriesResult = yield* configService.detectEntries(cwd, entriesConfig);
+			if (shouldClean) yield* cleanDirectory(resolve(cwd, "dist"));
+			const entryResults = [];
+			for (const entry of entriesResult.entries) {
+				const result = yield* Effect.either(bundleEntry(entry, config, cwd));
+				if (result._tag === "Left") {
+					const err = result.left;
+					entryResults.push({
+						success: false,
+						error: err.cause instanceof Error ? err.cause.message : String(err.cause)
+					});
+				} else entryResults.push(result.right);
+			}
+			yield* writeFile(resolve(cwd, "dist/package.json"), "{ \"type\": \"module\" }");
+			const duration = Date.now() - startTime;
+			const success = entryResults.every((r) => r.success);
+			if (!success) return {
+				success,
+				entries: entryResults,
+				duration,
+				error: "One or more entries failed to build"
+			};
+			return {
+				success,
+				entries: entryResults,
+				duration
+			};
+		}),
+		/* v8 ignore stop */
+		bundle: (entry, config) => bundleEntry(entry, config, process.cwd()),
+		clean: (outputDir) => cleanDirectory(outputDir),
+		formatResult: formatBuildResult,
+		formatBytes
+	};
+}));
+/* v8 ignore stop */
+
+//#endregion
+export { BuildServiceLive };

package/services/build.js

@@ -0,0 +1,63 @@
+import { OptionalPathLikeSchema } from "../schemas/path.js";
+import { Context, Schema } from "effect";
+
+//#region src/services/build.ts
+/**
+* Options for the build process.
+* @internal
+*/
+const BuildRunnerOptionsSchema = Schema.Struct({
+	/** Working directory for the build. Accepts string, Buffer, or URL. */
+	cwd: OptionalPathLikeSchema,
+	/** Clean output directory before building. Defaults to true. */
+	clean: Schema.optional(Schema.Boolean)
+});
+/**
+* Statistics for a single bundled entry.
+* @internal
+*/
+const BundleStatsSchema = Schema.Struct({
+	/** Entry type (main, pre, or post). */
+	entry: Schema.String,
+	/** Bundle size in bytes. */
+	size: Schema.Number,
+	/** Build duration in milliseconds. */
+	duration: Schema.Number,
+	/** Output path relative to working directory. */
+	outputPath: Schema.String
+});
+/**
+* Result of bundling a single entry.
+* @internal
+*/
+const BundleResultSchema = Schema.Struct({
+	/** Whether bundling succeeded. */
+	success: Schema.Boolean,
+	/** Bundle statistics if successful. */
+	stats: Schema.optional(BundleStatsSchema),
+	/** Error message if failed. */
+	error: Schema.optional(Schema.String)
+});
+/**
+* Result of the complete build process.
+* @internal
+*/
+const BuildResultSchema = Schema.Struct({
+	/** Whether the overall build succeeded. */
+	success: Schema.Boolean,
+	/** Results for each entry that was built. */
+	entries: Schema.Array(BundleResultSchema),
+	/** Total build duration in milliseconds. */
+	duration: Schema.Number,
+	/** Error message if build failed. */
+	error: Schema.optional(Schema.String)
+});
+/**
+* BuildService tag for dependency injection.
+*
+* @public
+*/
+const BuildService = Context.GenericTag("BuildService");
+
+//#endregion
+export { BuildResultSchema, BuildRunnerOptionsSchema, BuildService, BundleResultSchema, BundleStatsSchema };

package/services/config-live.js

@@ -0,0 +1,111 @@
+import { ConfigInvalid, ConfigLoadFailed, ConfigNotFound, MainEntryMissing } from "../errors.js";
+import { defineConfig } from "../schemas/config.js";
+import { ConfigService } from "./config.js";
+import { Effect, Layer } from "effect";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createJiti } from "jiti";
+
+//#region src/services/config-live.ts
+/**
+* ConfigService Layer implementation.
+*
+*/
+const CONFIG_FILENAMES = [
+	"action.config.ts",
+	"action.config.js",
+	"action.config.mjs"
+];
+const DEFAULT_ENTRIES = {
+	main: "src/main.ts",
+	pre: "src/pre.ts",
+	post: "src/post.ts"
+};
+/**
+* Find config file in the given directory.
+*/
+function findConfigFile(cwd) {
+	for (const filename of CONFIG_FILENAMES) {
+		const configPath = resolve(cwd, filename);
+		if (existsSync(configPath)) return configPath;
+	}
+}
+/**
+* Detect a single optional entry.
+*/
+function detectOptionalEntry(cwd, type, explicitPath) {
+	const defaultPath = DEFAULT_ENTRIES[type];
+	const absolutePath = resolve(cwd, explicitPath ?? defaultPath);
+	if (existsSync(absolutePath)) return {
+		type,
+		path: absolutePath,
+		output: `dist/${type}.js`
+	};
+}
+/**
+* Live implementation of ConfigService.
+*/
+const ConfigServiceLive = Layer.succeed(ConfigService, {
+	load: (options = {}) => Effect.gen(function* () {
+		const cwd = options.cwd ?? process.cwd();
+		const configPath = options.configPath ?? findConfigFile(cwd);
+		if (!configPath) return {
+			config: defineConfig({}),
+			usingDefaults: true
+		};
+		/* v8 ignore start - requires explicit configPath to non-existent file */
+		if (!existsSync(configPath)) return yield* Effect.fail(new ConfigNotFound({
+			path: configPath,
+			message: "Specified config file does not exist"
+		}));
+		/* v8 ignore stop */
+		const absolutePath = resolve(cwd, configPath);
+		/* v8 ignore stop */
+		const configInput = (yield* Effect.tryPromise({
+			try: async () => {
+				if (absolutePath.endsWith(".ts")) return createJiti(absolutePath, { interopDefault: true }).import(absolutePath);
+				return import(absolutePath);
+			},
+			catch: (error) => new ConfigLoadFailed({
+				path: configPath,
+				cause: error
+			})
+		})).default;
+		/* v8 ignore start - requires config file with non-object default export */
+		if (!configInput || typeof configInput !== "object") return yield* Effect.fail(new ConfigInvalid({
+			path: configPath,
+			errors: ["Config file must export a default configuration object"]
+		}));
+		return {
+			config: defineConfig(configInput),
+			configPath,
+			usingDefaults: false
+		};
+	}),
+	resolve: (input = {}) => Effect.succeed(defineConfig(input)),
+	detectEntries: (cwd, entries) => Effect.gen(function* () {
+		const detected = [];
+		const mainPath = entries?.main ?? DEFAULT_ENTRIES.main;
+		const absoluteMainPath = resolve(cwd, mainPath);
+		if (!existsSync(absoluteMainPath)) return yield* Effect.fail(new MainEntryMissing({
+			expectedPath: mainPath,
+			cwd
+		}));
+		detected.push({
+			type: "main",
+			path: absoluteMainPath,
+			output: "dist/main.js"
+		});
+		const preEntry = detectOptionalEntry(cwd, "pre", entries?.pre);
+		if (preEntry) detected.push(preEntry);
+		const postEntry = detectOptionalEntry(cwd, "post", entries?.post);
+		if (postEntry) detected.push(postEntry);
+		return {
+			success: true,
+			entries: detected
+		};
+	})
+});
+
+//#endregion
+export { ConfigServiceLive };

package/services/config.js

@@ -0,0 +1,63 @@
+import { OptionalPathLikeSchema } from "../schemas/path.js";
+import { ConfigSchema } from "../schemas/config.js";
+import { Context, Schema } from "effect";
+
+//#region src/services/config.ts
+/**
+* Options for loading configuration.
+* @internal
+*/
+const LoadConfigOptionsSchema = Schema.Struct({
+	/** Working directory to search for config. Accepts string, Buffer, or URL. */
+	cwd: OptionalPathLikeSchema,
+	/** Explicit path to config file. Accepts string, Buffer, or URL. */
+	configPath: OptionalPathLikeSchema
+});
+/**
+* Entry point type.
+* @internal
+*/
+const EntryTypeSchema = Schema.Literal("main", "pre", "post");
+/**
+* Detected entry point information.
+* @internal
+*/
+const DetectedEntrySchema = Schema.Struct({
+	/** Entry type (main, pre, or post). */
+	type: EntryTypeSchema,
+	/** Absolute path to the entry file. */
+	path: Schema.String,
+	/** Output path for the bundled file. */
+	output: Schema.String
+});
+/**
+* Result of entry detection.
+* @internal
+*/
+const DetectEntriesResultSchema = Schema.Struct({
+	/** Whether detection was successful. */
+	success: Schema.Boolean,
+	/** Detected entries. */
+	entries: Schema.Array(DetectedEntrySchema)
+});
+/**
+* Result of configuration loading.
+* @internal
+*/
+const LoadConfigResultSchema = Schema.Struct({
+	/** The resolved configuration. */
+	config: ConfigSchema,
+	/** Path to the config file that was loaded, if any. */
+	configPath: Schema.optional(Schema.String),
+	/** Whether defaults were used (no config file found). */
+	usingDefaults: Schema.Boolean
+});
+/**
+* ConfigService tag for dependency injection.
+*
+* @public
+*/
+const ConfigService = Context.GenericTag("ConfigService");
+
+//#endregion
+export { ConfigService, DetectEntriesResultSchema, DetectedEntrySchema, LoadConfigOptionsSchema };