HapperCI

HapperCI is a local-first CI application that lets you define CI/CD workflows using TypeScript instead of YAML. Run the same build process locally as you would on a hosted CI service.

Features

• TypeScript Workflows: Define your CI/CD pipelines in TypeScript with full IDE support
• Type Safety: Catch configuration errors at compile time
• Programmable: Use loops, conditionals, functions, and npm packages in your workflows
• Local First: Run your entire CI pipeline on your local machine
• Fast Feedback: No need to push to see if your build passes

Quick Start

1. Install HapperCI

# Clone and build
git clone https://github.com/pythonandchips/happerci.git
cd happerci
go build -o bin/happerci ./cmd/happerci
# Add to PATH (optional)export PATH="$PATH:$(pwd)/bin"

2. Set Up Your Project

cd your-project
# Create package.json if needed
npm init -y
# Install the SDK
npm install @happerci/sdk
# Create tsconfig.json
cat > tsconfig.json << 'EOF'{ "compilerOptions": { "target": "ES2020", "module": "commonjs", "esModuleInterop": true }}EOF

3. Create a Workflow

Create workflow.ts:

import{step}from'@happerci/sdk';step('install','npm install');step('lint','npm run lint');step('test','npm test');step('build','npm run build');

4. Run It

happerci run workflow.ts

Output:

HapperCI - Running workflow
Step: install
Output: added 150 packages in 2s
✓ PASSED
Step: lint
Output: No linting errors
✓ PASSED
Step: test
Output: All 42 tests passed
✓ PASSED
Step: build
Output: Build completed
✓ PASSED
Build: PASSED (4/4 steps)

Why TypeScript?

Traditional CI systems use YAML for configuration:

# Hard to read, no IDE support, easy to make mistakessteps:
- name: Installrun: npm install
- name: Testrun: npm test
- name: Buildif: github.ref == 'refs/heads/main'run: npm run build

With HapperCI, you use TypeScript:

import{step}from'@happerci/sdk';step('install','npm install');step('test','npm test');// Real programming language = real powerif(process.env.BRANCH==='main'){step('build','npm run build');}

Benefits:

• Autocomplete: Your IDE knows the API
• Type checking: Catch errors before running
• Refactoring: Rename, extract, reorganize with confidence
• Testing: Write unit tests for your CI logic
• npm ecosystem: Use any package to help define workflows

Documentation

• TypeScript Guide - Comprehensive guide to writing workflows

Architecture

HapperCI uses a host-guest architecture inspired by Pulumi:

┌─────────────────────┐ ┌─────────────────────┐
│ HapperCI CLI │ gRPC │ TypeScript SDK │
│ (Go Engine) │◄────────►│ (User Workflow) │
│ │ │ │
│ - Starts server │ │ - Registers steps │
│ - Spawns ts-node │ │ - Signals complete │
│ - Executes steps │ │ │
│ - Reports results │ │ │
└─────────────────────┘ └─────────────────────┘

The Go engine handles execution while TypeScript handles workflow definition. This separation provides:

• Reliable step execution
• Language flexibility (other SDKs possible)
• Security (user code only defines, doesn't execute)

Project Structure

happerci/
├── cmd/happerci/ # CLI entry point
├── internal/
│ ├── engine/ # Workflow execution engine
│ ├── runner/ # Step command runner
│ └── proto/ # Generated gRPC code
├── proto/ # Protocol buffer definitions
├── sdk/typescript/ # TypeScript SDK
├── examples/ # Example workflows
├── docs/ # Documentation
└── test/e2e/ # End-to-end tests

Development

Prerequisites

• Go 1.21+
• Node.js 18+
• Protocol Buffers compiler (protoc)

Build

# Build CLI
go build -o bin/happerci ./cmd/happerci
# Build TypeScript SDKcd sdk/typescript
npm install
npm run build

Test

# Run Go tests
go test ./...
# Run TypeScript testscd sdk/typescript && npm test# Run E2E tests
go test ./test/e2e/...

Regenerate Proto

If you modify proto/happerci.proto:

protoc --go_out=. --go-grpc_out=. proto/happerci.proto
mv github.com/pythonandchips/happerci/internal/proto/*.go internal/proto/
rm -rf github.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Inspiration

This project is inspired by Pulumi's multi-language architecture, which demonstrates how to build developer tools that support multiple programming languages through a common engine.