@simple-software/simplebuild/README.md

A build system for JS/TS that simply builds your project in the fastest way possible, with zero effort from you.

# Simple build

A build system for JS/TS that simply builds your project.
In the fastest way possible, with zero effort from you.

## Installation

### Global Installation (Recommended)

```bash
npm install -g @simple-software/simplebuild
```

### Local Installation

```bash
npm install @simple-software/simplebuild
```

## Usage

### Command Line

After global installation, you can use `simplebuild` from anywhere:

```bash
# Build current directory
simplebuild

# Build specific directory
simplebuild --working-dir=/path/to/your/project

# Use custom build directory name
simplebuild --working-dir=/path/to/project --simplebuild-dir=build
```

### Programmatic API

You can also use Simple Build programmatically in your Node.js applications:

```javascript
const { runSimpleBuild } = require('@simple-software/simplebuild');

async function buildProject() {
  try {
    const result = await runSimpleBuild({
      workingDir: '/path/to/your/project',
      simpleBuildDir: '.simplebuild' // optional, defaults to '.simplebuild'
    });
    
    console.log('Build completed with exit code:', result.exitCode);
    console.log('Output:', result.output);
  } catch (error) {
    console.error('Build failed:', error.message);
  }
}

buildProject();
```

## Phases

Simple Build runs through five distinct phases:

1. **Mirror** – symlink your sources into a hidden directory
2. **Analyze** – inspect the mirrored files for dependencies
3. **Generate** – create Bazel build files from the analysis
4. **Build** – execute the Bazel build
5. **Report** – parse the build output and present the result

## Prerequisites

- **Node.js** – version 23 or higher
- **Bazel** – builds the files mirrored into `.simplebuild`

## Development

### Prerequisites for Development

- **JDK** – required for running the Kotlin CLI via the Gradle wrapper
- **pnpm** – used for installing dependencies, running tests and linting
- **Bazel** – builds the files mirrored into `.simplebuild`

### Running the CLI from Source

Use the Gradle wrapper to run the application and pass the working directory you want to mirror. You can optionally choose the name of the mirrored directory:

```bash
./gradlew run --args="--working-dir=<path> [--simplebuild-dir=<dir>]"
```

This creates a directory (by default `.simplebuild`) inside `<path>` containing symlinks of your source files. Stub `MODULE.bazel`, `BUILD.bazel` and `.bazelversion` files are also generated so you can invoke Bazel inside that directory.

### Testing and linting

Install your JavaScript dependencies with pnpm and then run tests and linters with pnpm as well:

```bash
pnpm install
pnpm test
pnpm lint
```

### Building the npm package

```bash
npm run build
```

### End‑to‑end examples

Four example projects live under `e2e/`:

```bash
# Typescript example
cd e2e/typescript
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

# Vite example
cd ../vite
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

# JavaScript example
cd ../javascript
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"

# JavaScript multiple files example
cd ../javascript-multiple-files
pnpm install
../../gradlew run --args="--working-dir=$(pwd)"
```

After running, inspect `<project>/<dir>` (defaults to `.simplebuild`) and use Bazel commands there.

## Publishing

### Automated Publishing (Recommended)

Use the semantic versioning commands for automated publishing:

```bash
# Patch version (0.0.6 → 0.0.7) - for bug fixes
npm run publish:patch

# Minor version (0.0.6 → 0.1.0) - for new features  
npm run publish:minor

# Major version (0.0.6 → 1.0.0) - for breaking changes
npm run publish:major
```

These commands will:
- Check for uncommitted changes
- Bump the version in `package.json`
- Commit the version change
- Build and test the package
- Create a git tag
- Push to GitHub
- Trigger GitHub Actions to publish to npm

### Manual Publishing

For manual publishing with a specific version:

```bash
./scripts/publish.sh 0.0.7
```

## License

MIT License - see [LICENSE](LICENSE) file for details.