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.

• 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

# 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"

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

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');

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)

Traditional CI systems use YAML for configuration:

# Hard to read, no IDE support, easy to make mistakes
steps:
  - name: Install
    run: npm install
  - name: Test
    run: npm test
  - name: Build
    if: 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 power
if (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

• TypeScript Guide - Comprehensive guide to writing workflows

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)

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

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

# Build CLI
go build -o bin/happerci ./cmd/happerci

# Build TypeScript SDK
cd sdk/typescript
npm install
npm run build

# Run Go tests
go test ./...

# Run TypeScript tests
cd sdk/typescript && npm test

# Run E2E tests
go test ./test/e2e/...

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

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

MIT

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.