@savvy-web/github-action-builder 0.6.4 → 0.7.1

package/677.js

@@ -1,5 +1,6 @@
 import { Context, Data, Effect, Layer, ParseResult, Schema } from "effect";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { createRsbuild } from "@rsbuild/core";
 import { fileURLToPath } from "node:url";
@@ -102,6 +103,9 @@ const BuildOptionsSchema = Schema.Struct({
     }),
     externals: Schema.optionalWith(Schema.Array(Schema.String), {
         default: ()=>[]
+    }),
+    ignore: Schema.optionalWith(Schema.Array(Schema.String), {
+        default: ()=>[]
     })
 });
 const ValidationOptionsSchema = Schema.Struct({
@@ -131,7 +135,8 @@ const ConfigInputSchema = Schema.Struct({
     build: Schema.optional(Schema.Struct({
         minify: Schema.optional(Schema.Boolean),
         sourceMap: Schema.optional(Schema.Boolean),
-        externals: Schema.optional(Schema.Array(Schema.String))
+        externals: Schema.optional(Schema.Array(Schema.String)),
+        ignore: Schema.optional(Schema.Array(Schema.String))
     })),
     validation: Schema.optional(Schema.Struct({
         requireActionYml: Schema.optional(Schema.Boolean),
@@ -178,6 +183,7 @@ Schema.Struct({
     usingDefaults: Schema.Boolean
 });
 const ConfigService = Context.GenericTag("ConfigService");
+const IGNORE_STUB_SOURCE = `throw new Error("A module excluded via the build 'ignore' option was loaded at runtime.");\n`;
 function formatBytes(bytes) {
     if (bytes < 1024) return `${bytes} B`;
     if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -231,6 +237,22 @@ 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 = {};
+        let stubDir;
+        if (config.build.ignore.length > 0) {
+            stubDir = yield* Effect["try"]({
+                try: ()=>mkdtempSync(join(tmpdir(), "github-action-builder-")),
+                catch: (error)=>new WriteError({
+                        path: tmpdir(),
+                        cause: error
+                    })
+            });
+            const stubPath = resolve(stubDir, "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: {
@@ -239,6 +261,9 @@ function bundleEntry(entry, config, cwd) {
                                 [entry.type]: entry.path
                             }
                         },
+                        resolve: {
+                            alias: ignoreAlias
+                        },
                         output: {
                             target: "node",
                             module: true,
@@ -248,10 +273,13 @@ function bundleEntry(entry, config, cwd) {
                             filename: {
                                 js: "[name].js"
                             },
-                            externals: [
-                                (data)=>data.request?.startsWith("node:") ? `node-commonjs ${data.request}` : false,
-                                ...config.build.externals
-                            ],
+                            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,
                             minify: config.build.minify,
                             sourceMap: config.build.sourceMap ? {
@@ -262,6 +290,17 @@ function bundleEntry(entry, config, cwd) {
                             chunkSplit: {
                                 strategy: "all-in-one"
                             }
+                        },
+                        tools: {
+                            rspack: {
+                                node: {
+                                    __dirname: "node-module",
+                                    __filename: "node-module"
+                                },
+                                output: {
+                                    asyncChunks: false
+                                }
+                            }
                         }
                     }
                 }),
@@ -284,6 +323,13 @@ function bundleEntry(entry, config, cwd) {
                     cause: new Error(`rsbuild close() failed: ${error}`)
                 })
         });
+        if (void 0 !== stubDir) {
+            const dir = stubDir;
+            yield* Effect.ignore(Effect["try"](()=>rmSync(dir, {
+                    recursive: true,
+                    force: true
+                })));
+        }
         const outputPath = resolve(outputDir, `${entry.type}.js`);
         const size = yield* Effect["try"]({
             try: ()=>statSync(outputPath).size,

package/README.md

@@ -1,27 +1,23 @@
 # @savvy-web/github-action-builder
 
-A zero-config build tool for creating GitHub Actions from TypeScript source
-code. Bundles your action with [@rsbuild/core](https://github.com/web-infra-dev/rsbuild)
-(rspack-based), validates `action.yml` against GitHub's official schema, and
-outputs production-ready Node.js 24 actions.
+[![npm](https://img.shields.io/npm/v/@savvy-web%2Fgithub-action-builder?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/github-action-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js 24](https://img.shields.io/badge/Node.js-24-5fa04e.svg)](https://nodejs.org/)
+
+Build a GitHub Action from TypeScript source without writing build config. The builder bundles your code with [@rsbuild/core](https://github.com/web-infra-dev/rsbuild) (rspack under the hood) and checks `action.yml` against GitHub's published metadata schema. The output is a single Node.js 24 file you commit to your repo.
 
 ## Features
 
-- **Zero-config** - Auto-detects entry points from `src/main.ts`, `src/pre.ts`,
-  `src/post.ts`
-- **Node.js 24** - Builds modern ESM actions for the latest GitHub Actions
-  runtime
-- **Schema validation** - Validates `action.yml` against GitHub's official
-  metadata specification
-- **Single-file bundles** - All npm dependencies inlined via rsbuild, `node:`
-  builtins externalized, with tree-shaking support
-- **Local testing** - Auto-persists build output for testing with
-  [nektos/act](https://github.com/nektos/act)
+- **No build config required** - Picks up entry points from `src/main.ts`, `src/pre.ts`, `src/post.ts` on its own
+- **Node.js 24** - Emits ESM actions that run on the `node24` GitHub Actions runtime
+- **Schema validation** - Validates `action.yml` against GitHub's official metadata specification
+- **Single-file bundles** - All npm dependencies inlined via rsbuild; `node:` builtins externalized; user-configured `externals` and `ignore` options for optional or native modules
+- **Local testing** - Auto-persists build output for testing with [nektos/act](https://github.com/nektos/act)
 - **CI-aware** - Strict validation in CI, warnings-only locally
 
-## Quick Start
+## Quick start
 
-Create a new GitHub Action project with a single command:
+Scaffold a new GitHub Action project, then build it:
 
 ```bash
 npx @savvy-web/github-action-builder init my-action
@@ -30,8 +26,7 @@ npm install
 npm run build
 ```
 
-That's it! Your action is built and ready. The `init` command generates a
-complete project:
+The `init` command lays down the project:
 
 ```text
 my-action/
@@ -45,10 +40,9 @@ my-action/
 └── tsconfig.json    # TypeScript configuration
 ```
 
-Edit `src/main.ts` with your action logic, then rebuild with `npm run build`.
-Your bundled action is in `dist/main.js`, ready to commit and use.
+Put your action logic in `src/main.ts` and run `npm run build` again. The bundled action lands at `dist/main.js` — commit that file to your repo.
 
-## Basic Usage
+## Basic usage
 
 ### Initialize
 
@@ -78,7 +72,7 @@ npm run validate
 npx @savvy-web/github-action-builder validate
 ```
 
-## Project Structure
+## Project structure
 
 The builder expects this structure:
 
@@ -112,7 +106,7 @@ export default GitHubAction.create({
 });
 ```
 
-## action.yml Requirements
+## action.yml requirements
 
 Your `action.yml` must use Node.js 24:
 
@@ -127,12 +121,12 @@ runs:
 
 ## Documentation
 
-- [Getting Started](./docs/getting-started.md) - Installation and first build
-- [Configuration](./docs/configuration.md) - All configuration options
-- [Local Testing](./docs/local-testing.md) - Testing with nektos/act
-- [CLI Reference](./docs/cli-reference.md) - Complete command reference
-- [Architecture](./docs/architecture.md) - How it works internally
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+- [Getting started](./docs/01-getting-started.md) - Installation and first build
+- [Configuration](./docs/02-configuration.md) - All configuration options
+- [Local testing](./docs/03-local-testing.md) - Testing with nektos/act
+- [CLI reference](./docs/04-cli-reference.md) - Complete command reference
+- [Architecture](./docs/05-architecture.md) - How it works internally
+- [Troubleshooting](./docs/06-troubleshooting.md) - Common issues and solutions
 
 ## Programmatic API
 
@@ -146,10 +140,11 @@ const result = await action.build();
 
 if (result.success) {
   console.log(`Built ${result.build?.entries.length} entry points`);
+  // e.g. "Built 3 entry points"
 }
 ```
 
-## Shared TypeScript Configuration
+## Shared TypeScript configuration
 
 The package exports a base `tsconfig.json` for GitHub Action projects:
 
@@ -159,9 +154,7 @@ The package exports a base `tsconfig.json` for GitHub Action projects:
 }
 ```
 
-This provides sensible defaults for Node.js 24 ESM actions including strict
-mode, ES2022 target, and bundler module resolution. Override or extend as
-needed in your project's `tsconfig.json`.
+It sets up Node.js 24 ESM actions with strict mode, an ES2022 target and bundler module resolution. Override any of it in your own `tsconfig.json`.
 
 ## Requirements
 

package/bin/github-action-builder.js

@@ -74,7 +74,7 @@ const actionNameArg = Args.text({
     name: "action-name"
 }).pipe(Args.withDescription("Name of the GitHub Action (also the output directory)"));
 const forceOption = Options.boolean("force").pipe(Options.withAlias("f"), Options.withDescription("Overwrite existing files"), Options.withDefault(false));
-const getPackageVersion = ()=>"0.6.4";
+const getPackageVersion = ()=>"0.7.1";
 const generatePackageJson = (name)=>{
     const version = getPackageVersion();
     const pkg = {
@@ -306,7 +306,7 @@ const rootCommand = Command.make("github-action-builder").pipe(Command.withSubco
 ]));
 const cli = Command.run(rootCommand, {
     name: "github-action-builder",
-    version: "0.6.4"
+    version: "0.7.1"
 });
 const CliLayer = Layer.merge(AppLayer, NodeContext.layer);
 const main = Effect.suspend(()=>cli(process.argv)).pipe(Effect.provide(CliLayer), Effect.catchAllCause((cause)=>{

package/index.d.ts

@@ -343,6 +343,10 @@ export declare const BuildOptionsSchema: Schema.Struct<{
     externals: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
         default: () => never[];
     }>;
+    /** 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$<typeof Schema.String>, {
+        default: () => never[];
+    }>;
 }>;
 
 /**
@@ -637,6 +641,7 @@ export declare const ConfigInputSchema: Schema.Struct<{
         minify: Schema.optional<typeof Schema.Boolean>;
         sourceMap: Schema.optional<typeof Schema.Boolean>;
         externals: Schema.optional<Schema.Array$<typeof Schema.String>>;
+        ignore: Schema.optional<Schema.Array$<typeof Schema.String>>;
     }>>;
     validation: Schema.optional<Schema.Struct<{
         requireActionYml: Schema.optional<typeof Schema.Boolean>;
@@ -782,6 +787,10 @@ export declare const ConfigSchema: Schema.Struct<{
         externals: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
             default: () => never[];
         }>;
+        /** 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$<typeof Schema.String>, {
+            default: () => never[];
+        }>;
     }>;
     validation: Schema.Struct<{
         /** Require action.yml to exist and be valid. Defaults to true. */
@@ -910,6 +919,7 @@ export declare const ConfigService: Context.Tag<ConfigService, ConfigService>;
  *     minify: true,
  *     sourceMap: true,
  *     externals: ["@aws-sdk/client-s3"],
+ *     ignore: ["libxmljs2"],
  *   },
  *   validation: {
  *     requireActionYml: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvy-web/github-action-builder",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "private": false,
   "description": "A zero-config build tool for creating GitHub Actions from TypeScript. Bundles with rsbuild, validates action.yml against GitHub's schema, and outputs production-ready Node.js 24 actions.",
   "keywords": [