@savvy-web/github-action-builder 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @savvy-web/github-action-builder
+
+A zero-config build tool for creating GitHub Actions from TypeScript source
+code. Bundles your action with [@vercel/ncc](https://github.com/vercel/ncc),
+validates `action.yml` against GitHub's official schema, and outputs
+production-ready Node.js 24 actions.
+
+## 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 dependencies inlined using @vercel/ncc
+- **CI-aware** - Strict validation in CI, warnings-only locally
+
+## Quick Start
+
+Create a new GitHub Action project with a single command:
+
+```bash
+npx @savvy-web/github-action-builder init my-action
+cd my-action
+npm install
+npm run build
+```
+
+That's it! Your action is built and ready. The `init` command generates a
+complete project:
+
+```text
+my-action/
+├── src/
+│   ├── main.ts      # Main action entry point
+│   ├── pre.ts       # Pre-action hook
+│   └── post.ts      # Post-action cleanup
+├── action.yml       # GitHub Action metadata
+├── action.config.ts # Build configuration
+├── package.json     # Dependencies and scripts
+└── 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.
+
+## Basic Usage
+
+### Initialize
+
+Create a new GitHub Action project:
+
+```bash
+npx @savvy-web/github-action-builder init my-action
+```
+
+### Build
+
+Bundle all entry points into `dist/`:
+
+```bash
+npm run build
+# or directly:
+npx @savvy-web/github-action-builder build
+```
+
+### Validate
+
+Check your `action.yml` and configuration without building:
+
+```bash
+npm run validate
+# or directly:
+npx @savvy-web/github-action-builder validate
+```
+
+## Project Structure
+
+The builder expects this structure:
+
+```text
+my-action/
+├── src/
+│   ├── main.ts     # Required - main action entry point
+│   ├── pre.ts      # Optional - runs before main
+│   └── post.ts     # Optional - runs after main (cleanup)
+├── action.yml      # GitHub Action metadata (runs.using: "node24")
+├── action.config.ts # Optional configuration
+└── package.json
+```
+
+## Configuration
+
+Customize `action.config.ts` for your project:
+
+```typescript
+import { GitHubAction } from "@savvy-web/github-action-builder";
+
+export default GitHubAction.create({
+  entries: {
+    main: "src/main.ts",
+    post: "src/cleanup.ts",
+  },
+  build: {
+    minify: true,
+    sourceMap: false,
+  },
+});
+```
+
+## action.yml Requirements
+
+Your `action.yml` must use Node.js 24:
+
+```yaml
+name: "My Action"
+description: "Does something useful"
+runs:
+  using: "node24"
+  main: "dist/main.js"
+  post: "dist/post.js" # Optional
+```
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) - Installation and first build
+- [Configuration](./docs/configuration.md) - All configuration options
+- [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
+
+## Programmatic API
+
+Use the builder programmatically in your scripts:
+
+```typescript
+import { GitHubAction } from "@savvy-web/github-action-builder";
+
+const action = GitHubAction.create();
+const result = await action.build();
+
+if (result.success) {
+  console.log(`Built ${result.build?.entries.length} entry points`);
+}
+```
+
+## Requirements
+
+- Node.js 24+
+- TypeScript source files
+- `action.yml` with `runs.using: "node24"`
+
+## License
+
+MIT

package/bin/github-action-builder.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+import { Args, Command, Options } from "@effect/cli";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Layer, AppLayer, BuildService, ValidationService, ConfigService, Effect, existsSync, resolve, mkdirSync, writeFileSync, Console, Option } from "../123.js";
+const configOption = Options.file("config").pipe(Options.withAlias("c"), Options.withDescription("Path to configuration file"), Options.optional);
+const quietOption = Options.boolean("quiet").pipe(Options.withAlias("q"), Options.withDescription("Suppress non-error output"), Options.withDefault(false));
+const noValidateOption = Options.boolean("no-validate").pipe(Options.withDescription("Skip validation step"), Options.withDefault(false));
+const buildHandler = ({ config, quiet, noValidate })=>Effect.gen(function*() {
+        const configService = yield* ConfigService;
+        const validationService = yield* ValidationService;
+        const buildService = yield* BuildService;
+        const cwd = process.cwd();
+        if (!quiet) yield* Console.log("Loading configuration...");
+        const loadOptions = Option.isSome(config) ? {
+            cwd,
+            configPath: config.value
+        } : {
+            cwd
+        };
+        const configResult = yield* configService.load(loadOptions);
+        if (!quiet) if (configResult.usingDefaults) yield* Console.log("  Using default configuration");
+        else yield* Console.log(`  Found ${configResult.configPath}`);
+        if (!noValidate) {
+            if (!quiet) yield* Console.log("\nValidating...");
+            const validationResult = yield* validationService.validate(configResult.config, {
+                cwd
+            });
+            if (!validationResult.valid) {
+                yield* Console.error(`\n${validationService.formatResult(validationResult)}`);
+                return yield* Effect.fail(new Error("Validation failed"));
+            }
+            if (!quiet && validationResult.warnings.length > 0) yield* Console.log(validationService.formatResult(validationResult));
+            else if (!quiet) yield* Console.log("  All checks passed");
+        }
+        if (!quiet) yield* Console.log("\nBuilding...");
+        const buildResult = yield* buildService.build(configResult.config, {
+            cwd
+        });
+        if (!buildResult.success) {
+            yield* Console.error(`\nBuild failed: ${buildResult.error}`);
+            return yield* Effect.fail(new Error("Build failed"));
+        }
+        if (!quiet) {
+            yield* Console.log(`\n${buildService.formatResult(buildResult)}`);
+            yield* Console.log("\nBuild completed successfully!");
+        }
+    });
+const buildCommand = Command.make("build", {
+    config: configOption,
+    quiet: quietOption,
+    noValidate: noValidateOption
+}, buildHandler);
+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.1.0";
+const generatePackageJson = (name)=>{
+    const version = getPackageVersion();
+    const pkg = {
+        name,
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        scripts: {
+            build: "github-action-builder build",
+            validate: "github-action-builder validate",
+            typecheck: "tsc --noEmit"
+        },
+        devDependencies: {
+            "@savvy-web/github-action-builder": `^${version}`,
+            typescript: "^5.9.3"
+        },
+        dependencies: {
+            "@actions/core": "^1.11.1",
+            "@actions/github": "^6.0.0"
+        }
+    };
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+};
+const generateTsConfig = ()=>{
+    const config = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+            declaration: false,
+            outDir: "dist",
+            rootDir: "src"
+        },
+        include: [
+            "src/**/*.ts",
+            "action.config.ts"
+        ],
+        exclude: [
+            "node_modules",
+            "dist"
+        ]
+    };
+    return `${JSON.stringify(config, null, 2)}\n`;
+};
+const generateActionYml = (name)=>`name: "${name}"
+description: "A GitHub Action built with @savvy-web/github-action-builder"
+author: ""
+
+inputs:
+  example-input:
+    description: "An example input"
+    required: false
+    default: "hello"
+
+outputs:
+  example-output:
+    description: "An example output"
+
+runs:
+  using: "node24"
+  main: "dist/main.js"
+  pre: "dist/pre.js"
+  post: "dist/post.js"
+
+branding:
+  icon: "zap"
+  color: "blue"
+`;
+const defaultConfig = `import { GitHubAction } from "@savvy-web/github-action-builder";
+
+export default GitHubAction.create({
+	// Entry points are auto-detected from src/main.ts, src/pre.ts, src/post.ts
+	// Uncomment to customize:
+	// entries: {
+	//   main: "src/main.ts",
+	//   pre: "src/pre.ts",
+	//   post: "src/post.ts",
+	// },
+
+	// Build options
+	// build: {
+	//   minify: true,
+	//   sourceMap: false,
+	//   target: "es2022",
+	// },
+
+	// Validation options
+	// validation: {
+	//   strict: undefined, // Auto-detects CI environment
+	// },
+});
+`;
+const mainTemplate = `import * as core from "@actions/core";
+
+async function run(): Promise<void> {
+	try {
+		const input = core.getInput("example-input");
+		core.info(\`Running main action with input: \${input}\`);
+
+		// Your main action logic goes here
+
+		core.setOutput("example-output", "success");
+	} catch (error) {
+		if (error instanceof Error) {
+			core.setFailed(error.message);
+		} else {
+			core.setFailed("An unexpected error occurred");
+		}
+	}
+}
+
+run();
+`;
+const preTemplate = `import * as core from "@actions/core";
+
+async function run(): Promise<void> {
+	try {
+		core.info("Running pre action...");
+
+		// Your pre-action setup logic goes here
+		// This runs before the main action
+	} catch (error) {
+		if (error instanceof Error) {
+			core.setFailed(error.message);
+		} else {
+			core.setFailed("An unexpected error occurred");
+		}
+	}
+}
+
+run();
+`;
+const postTemplate = `import * as core from "@actions/core";
+
+async function run(): Promise<void> {
+	try {
+		core.info("Running post action...");
+
+		// Your post-action cleanup logic goes here
+		// This runs after the main action, even if it fails
+	} catch (error) {
+		if (error instanceof Error) {
+			core.warning(error.message);
+		} else {
+			core.warning("An unexpected error occurred during cleanup");
+		}
+	}
+}
+
+run();
+`;
+const writeFile = (path, content, force, createdFiles, skippedFiles)=>{
+    if (existsSync(path) && !force) return void skippedFiles.push(path);
+    writeFileSync(path, content, "utf-8");
+    createdFiles.push(path);
+};
+const initHandler = ({ actionName, force })=>Effect.gen(function*() {
+        const cwd = process.cwd();
+        const projectDir = resolve(cwd, actionName);
+        const createdFiles = [];
+        const skippedFiles = [];
+        if (existsSync(projectDir) && !force) {
+            yield* Console.error(`Directory already exists: ${actionName}`);
+            yield* Console.error("Use --force to overwrite existing files.");
+            return yield* Effect.fail(new Error("Directory exists"));
+        }
+        if (!existsSync(projectDir)) mkdirSync(projectDir, {
+            recursive: true
+        });
+        const srcDir = resolve(projectDir, "src");
+        if (!existsSync(srcDir)) mkdirSync(srcDir, {
+            recursive: true
+        });
+        writeFile(resolve(projectDir, "package.json"), generatePackageJson(actionName), force, createdFiles, skippedFiles);
+        writeFile(resolve(projectDir, "tsconfig.json"), generateTsConfig(), force, createdFiles, skippedFiles);
+        writeFile(resolve(projectDir, "action.yml"), generateActionYml(actionName), force, createdFiles, skippedFiles);
+        writeFile(resolve(projectDir, "action.config.ts"), defaultConfig, force, createdFiles, skippedFiles);
+        writeFile(resolve(srcDir, "main.ts"), mainTemplate, force, createdFiles, skippedFiles);
+        writeFile(resolve(srcDir, "pre.ts"), preTemplate, force, createdFiles, skippedFiles);
+        writeFile(resolve(srcDir, "post.ts"), postTemplate, force, createdFiles, skippedFiles);
+        yield* Console.log(`Created ${actionName}/`);
+        if (createdFiles.length > 0) for (const file of createdFiles)yield* Console.log(`  ${file.replace(`${projectDir}/`, "")}`);
+        if (skippedFiles.length > 0) {
+            yield* Console.log("\nSkipped existing files (use --force to overwrite):");
+            for (const file of skippedFiles)yield* Console.log(`  ${file.replace(`${projectDir}/`, "")}`);
+        }
+        yield* Console.log("\nNext steps:");
+        yield* Console.log(`  cd ${actionName}`);
+        yield* Console.log("  npm install");
+        yield* Console.log("  npm run build");
+    });
+const initCommand = Command.make("init", {
+    actionName: actionNameArg,
+    force: forceOption
+}, initHandler);
+const validateHandler = ({ config, quiet })=>Effect.gen(function*() {
+        const configService = yield* ConfigService;
+        const validationService = yield* ValidationService;
+        const cwd = process.cwd();
+        if (!quiet) yield* Console.log("Loading configuration...");
+        const loadOptions = Option.isSome(config) ? {
+            cwd,
+            configPath: config.value
+        } : {
+            cwd
+        };
+        const configResult = yield* configService.load(loadOptions);
+        if (!quiet) if (configResult.usingDefaults) yield* Console.log("  Using default configuration");
+        else yield* Console.log(`  Found ${configResult.configPath}`);
+        if (!quiet) yield* Console.log("\nValidating...");
+        const validationResult = yield* validationService.validate(configResult.config, {
+            cwd
+        });
+        yield* Console.log(`\n${validationService.formatResult(validationResult)}`);
+        if (!validationResult.valid) return yield* Effect.fail(new Error("Validation failed"));
+        if (!quiet) yield* Console.log("\nValidation completed successfully!");
+    });
+const validateCommand = Command.make("validate", {
+    config: configOption,
+    quiet: quietOption
+}, validateHandler);
+const rootCommand = Command.make("github-action-builder").pipe(Command.withSubcommands([
+    buildCommand,
+    validateCommand,
+    initCommand
+]));
+const cli = Command.run(rootCommand, {
+    name: "github-action-builder",
+    version: "0.1.0"
+});
+const CliLayer = Layer.merge(AppLayer, NodeContext.layer);
+const main = Effect.suspend(()=>cli(process.argv)).pipe(Effect.provide(CliLayer));
+NodeRuntime.runMain(main);