# koci - Universal CI Definition Tool

**One CI file to rule them all.**

koci is a universal CI definition tool that lets you:
- 🚀 **Run CI pipelines locally** using Docker/Podman
- 🔄 **Export to any platform** - GitHub Actions, Jenkins, GitLab CI, and more
- 📦 **Start simple, scale up** - One file that grows with your project

## Why koci?

Every CI platform has its own syntax. When you switch platforms or need to run CI locally, you're stuck rewriting everything. koci solves this with a universal format that:

- Works locally with Docker containers
- Exports to major CI platforms with one command
- Validates your pipeline before you push
- Watches files and auto-runs on changes

## Installation

```bash
pip install koci
```

Or install from source:

```bash
git clone https://github.com/kodogen/koci.git
cd koci
pip install -e .
```

## Quick Start

### 1. Create a Pipeline

```bash
koci init
```

This detects your project type (Node.js, Python, Go, etc.) and creates a `koci.yml`:

```yaml
version: "1"
name: my-app

stages:
  - build
  - test

jobs:
  install:
    stage: build
    image: node:20-alpine
    steps:
      - run: npm ci
    artifacts:
      paths:
        - node_modules/

  test:
    stage: test
    image: node:20-alpine
    needs: [install]
    steps:
      - run: npm test
    artifacts:
      consume: [install]
```

### 2. Validate

```bash
koci validate
```

### 3. Run Locally

```bash
koci run
```

Run a specific stage:
```bash
koci run --stage test
```

Run jobs in parallel (jobs must have `parallel: true`):
```bash
koci run                 # Parallel jobs run together (up to 4)
koci run -p 8            # Up to 8 parallel jobs simultaneously
koci run -p 1            # Force sequential execution
```

Graceful shutdown with Ctrl+C - containers are cleaned up properly:
```bash
koci run                 # Press Ctrl+C once for graceful shutdown
# ⚠ Received SIGINT, shutting down gracefully...
#   (Press Ctrl+C again to force quit)
# Cleaning up resources...
# ✓ Cleanup complete

koci run                 # Press Ctrl+C twice to force quit (no cleanup)
# ⚠ Force quit!
```

### 4. Export to CI Platform

```bash
# GitHub Actions
koci export github-actions

# Jenkins
koci export jenkins

# GitLab CI
koci export gitlab
```

## Commands

| Command | Description |
|---------|-------------|
| `koci init` | Create a starter koci.yml |
| `koci validate` | Validate pipeline syntax |
| `koci run` | Execute pipeline locally |
| `koci run --stage <name>` | Run specific stage |
| `koci export <platform>` | Export to CI platform |
| `koci watch` | Auto-run on file changes |
| `koci visualize` | Show pipeline graph |
| `koci info` | Show pipeline summary |

## Pipeline Syntax

### Stages & Jobs

```yaml
stages:
  - build
  - test
  - deploy

jobs:
  compile:
    stage: build
    image: node:20
    steps:
      - run: npm ci
      - run: npm run build
```

### Dependencies

```yaml
jobs:
  test:
    stage: test
    needs: [compile]  # Wait for compile to finish
    steps:
      - run: npm test
```

### Artifacts

```yaml
jobs:
  build:
    stage: build
    steps:
      - run: npm run build
    artifacts:
      paths:
        - dist/

  deploy:
    stage: deploy
    needs: [build]
    artifacts:
      consume: [build]  # Get artifacts from build job
    steps:
      - run: ./deploy.sh
```

### Matrix Builds

```yaml
jobs:
  test:
    stage: test
    matrix:
      node: [18, 20, 22]
      os: [alpine, slim]
    steps:
      - run: npm test
```

### Parallel Jobs

Jobs with `parallel: true` run simultaneously (respecting `--parallel` limit):

```yaml
jobs:
  test-unit:
    stage: test
    parallel: true      # Run in parallel with other parallel jobs
    steps:
      - run: npm test

  test-integration:
    stage: test
    parallel: true      # Runs at the same time as test-unit
    steps:
      - run: npm run test:integration

  test-e2e:
    stage: test
    # No parallel: true, runs after parallel jobs complete
    steps:
      - run: npm run test:e2e
```

Matrix jobs inherit the parallel flag, so all expanded jobs run together.

### Services

```yaml
services:
  test:  # Services for the test stage
    - image: postgres:15
      env:
        POSTGRES_PASSWORD: test
    - image: redis:7

jobs:
  integration:
    stage: test
    steps:
      - run: npm run test:integration
```

### Conditions

Simple conditions:
```yaml
jobs:
  deploy:
    when: branch == 'main'
    steps:
      - run: ./deploy.sh
```

Complex conditions:
```yaml
jobs:
  deploy:
    if: ${{ success() && env.DEPLOY_ENABLED == 'true' }}
    steps:
      - run: ./deploy.sh
```

### Test Reports

Collect JUnit test results and code coverage metrics:

```yaml
jobs:
  test:
    stage: test
    image: python:3.12
    steps:
      - run: pytest --junitxml=results.xml --cov=. --cov-report=xml
    reports:
      junit: test-results/*.xml  # Supports glob patterns
      coverage:
        path: coverage.xml
        format: cobertura  # or lcov, auto
        threshold: 80      # Fail if below 80%
```

Simple form (just paths):
```yaml
reports:
  junit: results.xml
  coverage: coverage.xml
```

When running locally, koci displays a summary after job execution:
```
    ◆ Collecting test reports...
      ✓ Test Results: 42 passed, 2 failed, 1 skipped (3.2s)
      ✓ Coverage: 84.2% lines (threshold: 80%)
```

When exporting, reports are configured for each platform:
- **GitHub Actions**: Uses `dorny/test-reporter` and `codecov/codecov-action`
- **GitLab CI**: Configures `artifacts.reports.junit` and `coverage_report`
- **Jenkins**: Adds `junit` and `publishCoverage` post steps

## Export Targets

### GitHub Actions

```bash
koci export github-actions
# Creates .github/workflows/ci.yml
```

### Jenkins

```bash
koci export jenkins
# Creates Jenkinsfile
```

### GitLab CI

```bash
koci export gitlab
# Creates .gitlab-ci.yml
```

## Configuration

### Secrets

Create `.koci.secrets.yml` (gitignored):

```yaml
env:
  AWS_ACCESS_KEY: xxx
  AWS_SECRET_KEY: xxx
```

### Global Environment

```yaml
env:
  NODE_ENV: production
  CI: "true"
```

### Default Image

```yaml
defaults:
  image: node:20-alpine
  working_directory: /app
```

## Development

```bash
# Setup
make virtualenv
source env/bin/activate

# Run tests
make test

# Run koci
koci --help
```

## Roadmap

- [x] Core pipeline execution
- [x] GitHub Actions export
- [x] Jenkins export
- [x] GitLab CI export
- [x] Test reports (JUnit, Coverage)
- [x] Parallel job execution
- [x] Graceful shutdown (Ctrl+C)
- [ ] CircleCI export
- [ ] Concourse export
- [ ] Azure Pipelines export
- [ ] Remote cache support
- [ ] Plugin system

## License

**Proprietary** - see [LICENSE.md](LICENSE.md)

Copyright © 2025 Kodo / The Willum Corporation. All Rights Reserved.

- ✅ Free to use (personal, educational, internal business)
- ✅ View and study source code
- ❌ Cannot sell or commercially distribute
- 📝 Must include attribution
