CONFIGURATION_SERVER.md

@@ -0,0 +1 @@
+# Configuration server

README.md

@@ -0,0 +1,249 @@
+<p align="center">
+  <image src="https://git.front.kjuulh.io/kjuulh/kraken/raw/branch/feature/write-a-readme/assets/kraken.svg" width="300" height="300"/>
+</p>
+<h1 align="center">Kraken - Your cute action executor</h1>
+
+## Purpose
+
+The goal of this project is to easily do batch changes or queries a host of
+repositories. In large organisations using multi-repository strategies, it may
+be painful to change even small things, because there are so many repositories
+to go through; Kraken aims to change that.
+
+**DISCLAIMER:** It is still early days, and the api is subject to change.
+
+## Features
+
+- uses a actions repository, where you store all your pending actions or queries
+  to be performed across your fleet of repositories. (See \_examples)
+- Actions can both execute changes, open pull-requests or in some cases commit
+  directly to your preferred branch
+  - Actions natively use either shell, go or docker files to execute changes
+    (see \_examples/actions)
+- Actions can also be analytical, so you can query your fleet for whatever you
+  would like
+- Works both as a client, or as a server
+- Supports SSH/https for fetching repos
+- Supports GPG signing
+- Supports dry-run mode for easy testing when developing your actions (enabled
+  by default on the cli)
+
+## Roadmap
+
+Refer to [roadmap.md](roadmap.md)
+
+## Installation
+
+Kraken comes in two modes. Client or Client -> Server. Kraken can stand alone as
+a client, for smaller and less secure changes. However, for organisations, it
+may be useful to use Kraken in server mode, which supports more features, and
+has extra security built in.
+
+### Client (CLI)
+
+Download executable from [releases](https://github.com/kjuulh/kraken/releases)
+
+#### Or Use docker image
+
+```bash
+docker run --rm kasperhermansen/krakencli:latest version
+```
+
+#### Or Build from source
+
+```bash
+git clone https://github.com/kjuulh/kraken.git
+cd kraken
+
+go build cmd/kraken/kraken.go
+./kraken version
+```
+
+#### Or Build with cuddle
+
+```bash
+git clone https://github.com/kjuulh/kraken.git
+cd kraken
+
+cuddle_cli x build_cli
+```
+
+### Server
+
+We prefer to run the server directly as a docker image.
+
+```bash
+docker pull kasperhermansen/krakenserver:latest
+docker run -p 9090:80 --rm kasperhermansen/krakenserver:latest
+```
+
+#### Or Build from source
+
+```bash
+git clone https://github.com/kjuulh/kraken.git
+cd kraken
+
+go build cmd/server/server.go
+./server version
+```
+
+#### Or Build with cuddle
+
+```bash
+git clone https://github.com/kjuulh/kraken.git
+cd kraken
+
+cuddle_cli x build_server
+```
+
+## Usage
+
+**DISCLAIMER:** It is still early days, and the api of the CLI is subject to
+change, this provides the aim of the project, but as it is currently in flux,
+there may not be as much handholding in the actual usage.
+
+I will focus on the client here, as the server provides the same features,
+though available through the cli, but instead as configuration options (see
+[CONFIGURATION_SERVER.md](CONFIGURATION_SERVER.md))
+
+Kraken ships with autocomplete built in (courtesy of spf13/cobra). To add:
+
+- Bash: `echo 'source <(kraken completion bash)' >> ~/.bashrc`
+- Zsh: `echo 'source <(kraken completion zsh)' >> ~/.zshrc`
+
+### Creating a new action
+
+Creating a new action
+
+```bash
+git init my-actions # should only be done once
+cd my-actions
+kraken tmpl init write-a-readme --command
+cat write-a-readme/kraken.yml
+
+# Output
+# apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1
+# name: write-a-readme
+# select:
+#   repositories: []
+# actions:
+#   - type: shell
+#     entry: "main.sh"
+```
+
+Kraken also ships with yaml schema, which should help write the yaml
+configuration.
+
+#### Add upstream repositories (victims)
+
+Now add a preferred repository
+
+```
+cat << EOF > write-a-readme/kraken.yml
+apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1
+name: write-a-readme
+select:
+  providers:                           # new
+  - gitea: https://git.front.kjuulh.io # new
+    organisation: "kjuulh"             # new
+actions:
+  - type: shell
+    entry: "main.sh"
+EOF
+```
+
+This will take all your repositories under an organisation and run the script
+on.
+
+Another could be to use
+
+```bash
+cat << EOF > write-a-readme/kraken.yml
+apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1
+name: write-a-readme
+select:
+  repositories:                                       #new
+    - git@git.front.kjuulh.io:kjuulh/kraken.git       #new
+    - git@git.front.kjuulh.io:kjuulh/kraken-test.git  #new
+actions:
+  - type: shell
+    entry: "main.sh"
+EOF
+```
+
+This will just apply to those repositories instead. Both can also be combined
+for a shared effect.
+
+### Execute action
+
+To run the script use
+
+```bash
+kraken process --path "write-a-readme"
+```
+
+This will cause the kraken process to automatically apply the action on the repo
+and open a pr.
+
+### Query repositories
+
+Kraken can also be used to query.
+
+```bash
+cat << EOF > write-a-readme/kraken.yml
+apiVersion: git.front.kjuulh.io/kjuulh/kraken/blob/main/schema/v1
+name: write-a-readme
+select:
+  repositories:
+    - git@git.front.kjuulh.io:kjuulh/kraken.git
+    - git@git.front.kjuulh.io:kjuulh/kraken-test.git
+queries:
+  - type: grep
+    query: "# README"
+EOF
+```
+
+Using the same command as above, will return the lines on each repo with those
+criteria. Everything is run in docker, even locally, so no need to install fancy
+tools.
+
+Do note: All actions will be run as dry-run unless `--apply` is added. This is
+to help test locally, as well as not cause serious issues. The server
+configuration is pretty much the same, except the command would look like so:
+`kraken server process --path "write-a-readme" --apply`. Kraken will try to
+infer as much as possible, but it may be needed to apply some extra flags to
+specify upstream repositories and such. Kraken will also help you setup keys and
+such on the first run, using `kraken setup` or `kraken server setup`.
+
+## Contributing
+
+It is still early days, and as such things are moving fast, I may not be able to
+implement features, because I am focusing my energy on the API. That said PRs
+are welcome, though they are at your own risk.
+
+### Bugs & features requests
+
+Please use [issues](https://github.com/kjuulh/kraken/issues)
+
+### Development
+
+We use [cuddle](https://git.front.kjuulh.io/kjuulh/cuddle) to improve ease of
+use, it is however, not a requirement, and probably won't need to be used
+outside core maintainers.
+
+Simply:
+
+```bash
+go run cmd/kraken/kraken.go # CLI
+go run cmd/server/server.go # Server
+```
+
+We follow the `gofmt` formatting, along with optionally but recommend `golines`
+
+If using cuddle
+
+```
+cuddle_cli x run # Run both server and client, will do a quick test sweep on the cli
+cuddle_cli x watch_run # Automatically refresh both
+cuddle_cli x fmt # will format the current code
+```

assets/kraken.svg

@@ -0,0 +1,10 @@
+<svg width="1000" height="1000" viewBox="0 0 1000 1000" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M975 568C975 830.335 762.335 497 500 497C237.665 497 25 830.335 25 568C25 305.665 237.665 93 500 93C762.335 93 975 305.665 975 568Z" fill="#52DB78"/>
+<path d="M237.436 856.185C165.693 827.571 320.875 755.464 377.754 612.854C434.634 470.243 371.672 311.132 443.414 339.746C515.157 368.36 527.205 507.165 470.326 649.776C413.446 792.386 309.178 884.799 237.436 856.185Z" fill="#52DB78"/>
+<path d="M428.353 849.847C353.918 829.229 500.308 740.627 541.293 592.663C582.278 444.699 502.337 293.405 576.773 314.023C651.208 334.641 678.325 471.303 637.34 619.267C596.355 767.231 502.788 870.465 428.353 849.847Z" fill="#52DB78"/>
+<path d="M598.707 855.902C523.231 839.498 664.415 742.813 697.024 592.781C729.634 442.748 641.321 296.183 716.797 312.588C792.272 328.992 827.022 463.916 794.413 613.948C761.803 763.98 674.183 872.307 598.707 855.902Z" fill="#52DB78"/>
+<path d="M47.896 838.855C-19.3259 800.817 144.17 750.323 219.784 616.698C295.397 483.073 254.495 316.918 321.717 354.956C388.938 392.994 382.136 532.155 306.522 665.78C230.909 799.405 115.118 876.893 47.896 838.855Z" fill="#52DB78"/>
+<ellipse cx="605.35" cy="265.255" rx="57.5" ry="36.5" transform="rotate(-40.9544 605.35 265.255)" fill="white"/>
+<ellipse cx="359.35" cy="265.255" rx="57.5" ry="36.5" transform="rotate(-40.9544 359.35 265.255)" fill="white"/>
+<path d="M385.635 374C385.635 374 391.199 435.298 463.528 438.425C535.857 441.553 538.492 380.61 538.492 380.61" stroke="white" stroke-width="8"/>
+</svg>