kist
Version:
Package Pipeline Processor
304 lines (203 loc) • 9.54 kB
Markdown
<p align="center">
<img src="https://raw.githubusercontent.com/getkist/brand/master/src/logo/kist.png" width="20%" height="20%" alt="kist logo"></p>
<h1 align="center" style='border-bottom: none;'>kist</h1>
<h3 align="center">Package Pipeline Processor</h3>
<br/>
<div align="center">
[
](https://www.kist)
[](https://www.npmjs.com/package/kist)
[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/getkist/kist)
[](https://stackblitz.com/github/getkist/kist/tree/main?file=src%2Findex.html)
[](https://github.com/getkist/kist/blob/main/LICENSE)
</div>
<div align="center">
[](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=bug_report.yml)
[](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=feature_request.yml)
[](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=question.yml)
[](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=suggestion.yml)
[](https://github.com/getkist/kist/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected&projects=&template=discussion.yml)
</div>
<br/>
kist is a highly customizable and efficient package builder designed to streamline software development workflows. It provides a modular framework for managing build pipelines with support for live reload functionality.
`kist` is a package builder designed to enhance the efficiency and organization of software development projects. Key to its design philosophy is the adaptability to various development workflows, making it an ideal companion for a range of projects from small-scale personal endeavors to large, complex enterprise applications. `kist` stands not just as a tool but as a partner in the software development journey, enhancing productivity, reducing overhead, and bringing clarity and ease to the package management process.
## Features
- Modular pipeline system with stages and steps.
- Live reload functionality for enhanced developer experience.
- Plugin-based architecture to extend functionality.
- TypeScript support for a modern development workflow.
- Robust error handling and logging.
## Quickstart
To install `kist`, use npm or yarn:
### NPM
```bash
npm install kist --save-dev
```
### Yarn
```bash
yarn add kist --dev
```
## Installation
1. Clone the Repository:
```sh
git clone <https://github.com/getkist/kist.git>
cd kist
```
2. Install Dependencies:
```sh
npm install
```
3. Build the Project:
```sh
npm run build
```
4. Link the CLI Globally:
```sh
npm link
```
## Usage
### Run the Pipeline
Run the pipeline defined in your pack.yaml file:
```sh
pack
```
### Enable Live Reload
Run the pipeline with live reload enabled:
```sh
pack --live
```
## Configuration
The pipeline configuration is defined in a pack.yaml file located in the root of your project. Here’s an example:
```sh
stages:
- name: build
steps:
- name: compile
action: build
options:
source: src/
output: dist/
- name: test
dependsOn: [build]
steps:
- name: run-tests
action: test
```
Stage and Step Structure
- Stages: Define a group of steps to be executed.
- Steps: Individual tasks within a stage (e.g., compiling, testing).
- Dependencies: Stages can depend on other stages to enforce execution order.
## Development
### Build
Compile the TypeScript files into JavaScript:
```sh
npm run build-tsc
```
### Lint
Run ESLint to check for code issues:
```sh
npm run lint
```
### Run Tests
Run all tests in the src/tests directory:
```sh
npm run test
```
### Live Reload
To enable live reload during development, add the --live flag:
```sh
pack --live
```
## Folder Structure
```sh
kist/
├── src/
│ ├── core/ # Core pipeline logic
│ ├── live/ # Live reload server and related components
│ ├── actions/ # Built-in step actions (e.g., build, test)
│ ├── tests/ # Unit tests
│ └── pack.ts # Entry point for the CLI
├── dist/ # Compiled JavaScript output
├── pack.yaml # Example configuration file
├── package.json # Project metadata and dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Project documentation
```
## Key Components
### Pipeline
The Pipeline class manages the execution of stages and steps defined in the pack.yaml file.
### LiveReloadServer
The LiveReloadServer provides live reload functionality by watching files for changes and notifying connected clients.
### ConfigLoader
The ConfigLoader reads and validates the pipeline configuration from the pack.yaml file.
### Actions
kist supports plugin-based actions. Default actions include:
- build: Compiles source files.
- test: Runs tests.
- lint: Lints the codebase.
Custom actions can be implemented and registered as plugins.
```mermaid
graph TD
subgraph Pipeline
Stage1[Stage 1]
Stage2[Stage 2]
Stage3[Stage 3]
end
subgraph Stage1
Step1_1[Step 1.1]
Step1_2[Step 1.2]
end
subgraph Stage2
Step2_1[Step 2.1]
Step2_2[Step 2.2]
end
subgraph Stage3
Step3_1[Step 3.1]
Step3_2[Step 3.2]
end
Step1_1 --> Action1_1[Action: DirectoryCleanAction]
Step1_2 --> Action1_2[Action: DirectoryCopyAction]
Step2_1 --> Action2_1[Action: FileCopyAction]
Step2_2 --> Action2_2[Action: StyleProcessingAction]
Step3_1 --> Action3_1[Action: PackageManagerAction]
Step3_2 --> Action3_2[Action: VersionWriteAction]
Stage1 --> Stage2
Stage2 --> Stage3
```
## Colophon
### Authors
**kist** is an open-source project by **[Scape Agency](https://www.scape.agency "Scape Agency website")**.
#### Scape Agency
Scape Agency is a spatial innovation collective that dreams, discovers and designs the everyday of tomorrow. We blend design thinking with emerging technologies to create a brighter perspective for people and planet. Our products and services naturalise technology in liveable and sustainable –scapes that spark the imagination and inspire future generations.
- website: [scape.agency](https://www.scape.agency "Scape Agency website")
- github: [github.com/getkist](https://github.com/getkist "Scape Agency GitHub")
### Development Resources
#### Contributing
We'd love for you to contribute and to make this project even better than it is today!
Please refer to the [contribution guidelines](.github/CONTRIBUTING.md) for information.
Contributions are welcome! Follow these steps to contribute:
1. Fork the repository.
2. Create a new feature branch.
3. Make your changes and write tests.
4. Submit a pull request.
### Legal Information
#### Copyright
Copyright © 2024 [Scape Agency BV](https://www.scape.agency/ "Scape Agency website"). All Rights Reserved.
#### License
Except as otherwise noted, the code in this repository is licensed under the MIT License. Also see [LICENSE](https://github.com/getkist/community/blob/master/src/LICENSE). The documentation is licensed under the [Creative Commons Attribution 4.0 International (CC BY 4.0) License](https://creativecommons.org/licenses/by/4.0/).
#### Disclaimer
**THIS SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**
<p align="center">
<b>Made with ❤️ by <a href="https://www.scape.agency" target="_blank">Scape Agency</a></b>
</p>