simplify dual build (#6)

Author: tiberius-s

CHANGELOG.md

@@ -2,76 +2,80 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1] - 2025-12-09
+
+### Changed
+
+- **Build Process Simplification**: Removed wrapper script complexity in favor of direct SWC compilation
+- **Postbuild Script**: Replaced `insert-shebang.sh` with lightweight `add-shebang.js` Node script
+- **CJS Package Generation**: Now generated inline in build script instead of via wrapper
+- **README**: Updated "How It Works" section to reflect simplified build architecture
+
+### Technical Details
+
+**Build Process (Simplified):**
+
+1. Prebuild: format:fix → lint → typecheck → clean
+2. Compile: SWC compiles source to both `build/esm/src/` and `build/cjs/src/`
+3. Path Resolution: `tsc-alias` transforms `@/` imports to relative paths
+4. Executables: `add-shebang.js` adds shebangs and sets executable permissions
+5. CJS Marker: `package.json` with `"type":"commonjs"` created in `build/cjs/`
+
+**Entry Points:**
+
+- ESM: `build/esm/src/cli.js` (executable)
+- CJS: `build/cjs/src/cli.js` (executable)
+
 ## [0.3.0] - 2025-12-09
 
 ### Added
 
-- **Dual Build System**: Project now compiles to both ESM (`build/esm/`) and CommonJS (`build/cjs/`) formats with proper module format markers
-- **Path Aliases**: TypeScript path aliases (`@/*`) now work throughout the codebase and are resolved to relative paths in compiled output
-- **Build Validation**: Code quality checks (format, lint, typecheck) run automatically in the prebuild step before compilation
+- **Dual Build System**: Project compiles to both ESM (`build/esm/`) and CommonJS (`build/cjs/`) with proper module format markers
+- **Path Aliases**: TypeScript path aliases (`@/*`) work throughout codebase and resolve to relative paths in output
+- **Build Validation**: Code quality checks (format, lint, typecheck) run automatically in prebuild step
 - **Source Maps**: Both ESM and CJS builds include source maps for debugging
-- **Dynamic Executables**: Shebangs dynamically wrapped for both module formats via `insert-shebang.sh`
 - **ESM dirname Utility**: New `getDirname()` utility for ES module-compatible directory resolution
-- **Comprehensive Tests**:
-  - 5 unit tests for CLI and command logic
-  - 2 unit tests for dirname utility
-  - 9 integration tests for build outputs (ESM and CJS execution)
-  - 9 integration tests for module format verification and structure
-  - Total: 25+ tests with 100% code coverage
-- **Integration Test Suite**: Dedicated `tests/integration/` directory with build output and module format validation
-- **JSDoc Comments**: Added documentation to all functions for better IDE support and clarity
-- **Improved README**: Comprehensive documentation with features list, usage examples, and technical architecture explanation
+- **Comprehensive Tests**: 27 total tests (9 unit + 18 integration) with 100% code coverage
+- **Integration Test Suite**: Dedicated `tests/integration/` with build output and module format validation
+- **JSDoc Comments**: All functions documented for IDE support and clarity
+- **Improved README**: Comprehensive documentation with features, usage, and architecture explanation
 
 ### Changed
 
-- **Tooling Migration**: Replaced ESLint + Prettier with Biome for unified linting and formatting
-- **Node Version Requirement**: Updated from Node 16+ to Node 20+ for stable ESM support
-- **Build Scripts**: Restructured build pipeline with separate configurations for ESM and CJS
-- **CLI Implementation**: Enhanced with better error handling, version management, and command validation
-- **Testing Framework**: Updated from Vite's test to dedicated Vitest with coverage integration
-- **Project Structure**: Reorganized to include utilities folder and proper test file placement
+- **Tooling Migration**: Replaced ESLint + Prettier with Biome for unified linting/formatting
+- **Node Version**: Updated from 16+ to 20+ for stable ESM support without flags
+- **Build Scripts**: Restructured with separate SWC configurations for ESM and CJS
+- **CLI Implementation**: Enhanced with better error handling and version management
+- **Testing Framework**: Upgraded from Vite test to dedicated Vitest with coverage
+- **Project Structure**: Added utilities folder and proper test file organization
 
 ### Removed
 
 - ESLint configuration and plugins
 - Prettier configuration
 - Old single build configuration (`.swcrc`)
-- Version check code that couldn't be reached in ESM environment
+- Unreachable Node version check code
 
 ### Fixed
 
-- Test file exclusion from production builds (prevents `.test.js` in output)
+- Test file exclusion from production builds
 - Path alias transformation for both module formats
 - Vitest configuration to prevent test discovery in build directory
-- CJS module format declaration via `build/cjs/package.json`
-
-### Technical Details
-
-**Build Process:**
-
-1. `npm run build` triggers prebuild (format:fix → lint → typecheck)
-2. Parallel compilation: `.swcrc-esm` and `.swcrc-cjs` compile source
-3. Post-compile: `tsc-alias` transforms `@/` imports to relative paths
-4. Postbuild: `insert-shebang.sh` creates executable wrappers for both formats
-
-**Module Format Support:**
-
-- ESM: Uses `import()`/`export`, targets modern Node.js
-- CJS: Uses `require()`/`exports`, includes `type: "commonjs"` marker for compatibility
+- CJS module format declaration
 
-**Dependencies Updated:**
+### Dependencies Updated
 
 - TypeScript: 4.9.5 → 5.9.3
 - SWC: 1.3.35 → 1.15.3
 - Commander: 10.0.0 → 14.0.2
 - Vitest: 0.28.5 → 4.0.15
-- Biome: Added as replacement for ESLint + Prettier
-- tsc-alias: Added for path alias transformation
-- @vitest/coverage-v8: Added for coverage reporting
+- Biome: 2.3.8 (new)
+- tsc-alias: 1.8.16 (new)
+- @vitest/coverage-v8: 4.0.15 (new)
 
 ### Breaking Changes
 
 - Requires Node.js 20+ (was 16+)
-- Single build output replaced with dual ESM/CJS structure
-- Package exports field now specifies import/require conditions
+- Dual ESM/CJS structure replaces single build output
+- Package exports field specifies import/require conditions
 - CLI now uses Biome instead of ESLint/Prettier

README.md

@@ -56,11 +56,13 @@ Run `npm run clean` to remove build artifacts and node_modules.
 
 ## How It Works
 
-The dual build system uses SWC with two separate configurations: `.swcrc-esm` compiles source code to ES modules in `build/esm/`, while `.swcrc-cjs` compiles the same source to CommonJS in `build/cjs/`. Both configs reference `@/` path aliases defined in `tsconfig.json`.
+The dual build system compiles source code once, then generates both ESM and CommonJS outputs. SWC reads the same TypeScript source but uses two separate configurations: `.swcrc-esm` produces ES modules in `build/esm/`, while `.swcrc-cjs` produces CommonJS in `build/cjs/`. Both preserve the directory structure and include source maps.
 
-After SWC compiles, `tsc-alias` transforms those `@/` imports to relative paths in both output directories so they resolve correctly without TypeScript at runtime. Finally, `insert-shebang.sh` wraps both compiled `cli.js` files with executable shebangs—the ESM version uses dynamic `import()`, the CJS version uses `require()` and generates a `package.json` marker.
+Path aliases (`@/*`) are configured in both SWC configs and resolved to relative imports at compile time via `tsc-alias`, so they work without TypeScript at runtime.
 
-The build validates code quality first: `npm run build` runs the prebuild step (type checking, linting, formatting) before compilation, ensuring only clean code makes it to the output.
+The entry points (`build/esm/src/cli.js` and `build/cjs/src/cli.js`) get shebangs added via a simple Node script in the postbuild step. For CJS, a `package.json` file is generated in the output to explicitly declare the module format.
+
+Quality checks run before any compilation: `npm run build` executes the prebuild step (format, lint, typecheck) to ensure only clean code makes it to the output.
 
 ## Technologies
 

add-shebang.js

@@ -0,0 +1,17 @@
+import { readFileSync, writeFileSync, chmodSync } from "node:fs";
+
+const shebang = "#!/usr/bin/env node\n";
+const files = ["build/esm/src/cli.js", "build/cjs/src/cli.js"];
+
+for (const file of files) {
+  try {
+    const content = readFileSync(file, "utf-8");
+    if (!content.startsWith("#!")) {
+      writeFileSync(file, shebang + content);
+      chmodSync(file, 0o755);
+      console.log(`✓ Added shebang to ${file}`);
+    }
+  } catch (err) {
+    console.error(`Error processing ${file}:`, err.message);
+  }
+}

insert-shebang.sh

@@ -1,13 +1,13 @@
 {
   "name": "hello-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A basic CLI written in TypeScript meant to be used as an example or project starter",
   "type": "module",
-  "bin": "./build/esm/cli.js",
+  "bin": "./build/esm/src/cli.js",
   "exports": {
     ".": {
-      "import": "./build/esm/cli.js",
-      "require": "./build/cjs/cli.js"
+      "import": "./build/esm/src/cli.js",
+      "require": "./build/cjs/src/cli.js"
     }
   },
   "files": [
@@ -31,11 +31,10 @@
   },
   "scripts": {
     "prebuild": "npm run format:fix && npm run lint && npm run typecheck && rm -rf ./build",
-    "build:esm": "swc --config-file .swcrc-esm -D src -d build/esm --ignore '**/*.test.ts' && tsc-alias -p tsconfig.json --outDir build/esm --resolve-full-paths",
-    "build:cjs": "swc --config-file .swcrc-cjs -D src -d build/cjs --ignore '**/*.test.ts' && tsc-alias -p tsconfig.json --outDir build/cjs --resolve-full-paths",
-    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "swc src --config-file .swcrc-esm -d build/esm --ignore '**/*.test.ts' && tsc-alias -p tsconfig.json --outDir build/esm --resolve-full-paths",
+    "build:cjs": "swc src --config-file .swcrc-cjs -d build/cjs --ignore '**/*.test.ts' && tsc-alias -p tsconfig.json --outDir build/cjs --resolve-full-paths && echo '{\"type\":\"commonjs\"}' > build/cjs/package.json",
+    "build": "npm run build:esm && npm run build:cjs && node ./add-shebang.js",
     "build:debug": "swc --config-file .swcrc-esm -s true -D src -d build/esm",
-    "postbuild": "./insert-shebang.sh",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build",
     "clean": "rm -rf ./node_modules ./build; rm package-lock.json; echo 'cleared project artifacts!'",

package.json

@@ -3,29 +3,29 @@ import { execSync } from "node:child_process";
 
 describe("ESM Build Output", () => {
   test("should execute ESM CLI successfully", () => {
-    const output = execSync("./build/esm/cli.js hello World", {
+    const output = execSync("./build/esm/src/cli.js hello World", {
       encoding: "utf-8",
     });
     expect(output.trim()).toBe("Hello, World.");
   });
 
   test("should support --version flag", () => {
-    const output = execSync("./build/esm/cli.js --version", {
+    const output = execSync("./build/esm/src/cli.js --version", {
       encoding: "utf-8",
     });
     expect(output.trim()).toMatch(/^\d+\.\d+\.\d+$/);
   });
 
   test("should support --help flag", () => {
-    const output = execSync("./build/esm/cli.js --help", {
+    const output = execSync("./build/esm/src/cli.js --help", {
       encoding: "utf-8",
     });
     expect(output).toContain("Usage: hello-cli");
     expect(output).toContain("Commands:");
   });
 
   test("should support --yell option", () => {
-    const output = execSync("./build/esm/cli.js hello world --yell", {
+    const output = execSync("./build/esm/src/cli.js hello world --yell", {
       encoding: "utf-8",
     });
     expect(output.trim()).toBe("HELLO, WORLD.");
@@ -34,21 +34,21 @@ describe("ESM Build Output", () => {
 
 describe("CJS Build Output", () => {
   test("should execute CJS CLI successfully", () => {
-    const output = execSync("./build/cjs/cli.js hello World", {
+    const output = execSync("./build/cjs/src/cli.js hello World", {
       encoding: "utf-8",
     });
     expect(output.trim()).toBe("Hello, World.");
   });
 
   test("should support --version flag", () => {
-    const output = execSync("./build/cjs/cli.js --version", {
+    const output = execSync("./build/cjs/src/cli.js --version", {
       encoding: "utf-8",
     });
     expect(output.trim()).toMatch(/^\d+\.\d+\.\d+$/);
   });
 
   test("should support --help flag", () => {
-    const output = execSync("./build/cjs/cli.js --help", {
+    const output = execSync("./build/cjs/src/cli.js --help", {
       encoding: "utf-8",
     });
     expect(output).toContain("Usage: hello-cli");
@@ -62,7 +62,7 @@ describe("CJS Build Output", () => {
   });
 
   test("should support --yell option", () => {
-    const output = execSync("./build/cjs/cli.js hello world --yell", {
+    const output = execSync("./build/cjs/src/cli.js hello world --yell", {
       encoding: "utf-8",
     });
     expect(output.trim()).toBe("HELLO, WORLD.");

tests/integration/build-outputs.test.ts

@@ -56,8 +56,8 @@ describe("Module Format Verification", () => {
 
   describe("Build Structure", () => {
     test("should have executables with shebangs", () => {
-      const esmCli = readFileSync("./build/esm/cli.js", "utf-8");
-      const cjsCli = readFileSync("./build/cjs/cli.js", "utf-8");
+      const esmCli = readFileSync("./build/esm/src/cli.js", "utf-8");
+      const cjsCli = readFileSync("./build/cjs/src/cli.js", "utf-8");
 
       expect(esmCli).toMatch(/^#!\/usr\/bin\/env node/);
       expect(cjsCli).toMatch(/^#!\/usr\/bin\/env node/);