Metadata-Version: 2.4
Name: koci
Version: 0.1.0
Summary: Kodo CI
Home-page: https://github.com/johndoe/myapp/
Author: Ryan Flynn
Author-email: john.doe@example.com
License: unlicensed
Description-Content-Type: text/markdown
License-File: LICENSE.md
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: summary

# 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/kodo/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
```

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

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

## 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
- [ ] CircleCI export
- [ ] Concourse export
- [ ] Azure Pipelines export
- [ ] Parallel job execution
- [ ] Remote cache support
- [ ] Plugin system

## License

MIT License - see [LICENSE.md](LICENSE.md)
