From 78c86dc39aa65543e9aac764bc40aa43330070b7 Mon Sep 17 00:00:00 2001 From: kjuulh Date: Fri, 23 Aug 2024 22:48:14 +0200 Subject: [PATCH] docs: add docs --- README.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 153 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b54b734..a32193b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,154 @@ -# cuddle +# Cuddle +Cuddle aims to reduce the complexity of building code projects. It allows either +individuals or organisations to share scripts and workflows, as well as keep a +dynamic inventory of their code. + +At its most basic allows enforcing a schema for projects, further it allows the +sharing of scripts, pipelines, templates, and much more. + +```bash +cuddle init +``` + +Cuddle is meant to be used in the degree that it makes sense for you, it can be +adopted quickly to improve code sharing, and be fully bought into to provide a +full suite of project level solutions to offload requirements of developers. +Start small with scripts and plans, and gradually adopt features from there as +you need them. + +## Usage + +Cuddle is primarily a cli based tool, but ships with optional server components. +Server components helps enhance the features of cuddle, such that variables can +be enforced at runtime, actions be downloaded instead of built and much more. It +all works on a gradual adoption process, so as an operator you can gradually add +features as you mature and need them. + +A cuddle workflow is split up into: + +- Projects: A project is what most users interface with, you can think of it as + the cockpit of a car. You can use all the bells and whistles, but somebody + else has built up all the user journeys you're interacting with. +- Plans: A plan is the engine room of the car, it ties together components, + features and requirements for use in the cockpit. The plan usually faciliates + most of the infrastructure an application stands to outsource. Such as scripts + to run, build, test an application, build its templates for deployment, run + pipelines, common actions. Plans specialize in building preciely what the + projects needs, as such your organisation or yourself, should only have a + handful of them at most. To further reduce duplication of work between plans, + components can be used to abstract common features required by plans, such as + templating, individual components for templates. +- Components: Components are a slice of features not useful in of itself, but + used by plans to further their behavior, a sample component may be a template + part, which includes a list of allowed ip addresses for internal + communication, it may be how to build an ingress, ship a docker container to a + registry, basically small individual components useful for a larger whole. +- Actions: are code units that can take a variety of forms, golang, rust, bash, + what have you. All of them are accessed by `cuddle do`, individual components + can take the form of actions, if desired +- Global: Is a set of actions and features that are available anywhere a user + might need them. For example it can be a solution to easily log into + production environments, release code to production, get the menu from the + canteen, etc. +- Personal: Is a config an org can decide the users and develoeprs fill out, it + can help other tooling better enhance the experience. For example it may be + useful to always have the developers email available, if for example we want + to trigger an automatic login for them. + +### Init + +`cuddle init` will bootstrap a project either from scratch, or just adding +required `cuddle.toml` parts. + +A `cuddle.toml` is required to access project level `cuddle` commands. Such as +`cuddle do`, `cuddle get`, `cuddle validate`, etc. + +`cuddle.toml` looks something like this: + +```toml +[project] +name = "some-cuddle-project" +owner = "kjuulh" +``` + +What is generated out of the box is a _bare_ project. A bare project doesn't +share any features, or enforce any requirements on its schema from its plan. It +is most useful for projects that doesn't fit any mold, or for individual users +simply testing out the framework. + +### Actions + +`cuddle actions` are project level scripts that can take a variety of forms. +Actions are invoked via. `cuddle do` when inside of a project, most projects +won't build actions themselves, instead they will depend on what their plan +provides for them. + +Actions can be bootstrapped via. `cuddle init actions`, an action is slice of a +cli. Cuddle provides a convenient way of building them, such that they are easy +to build, maintain and operate. Most actions are written in either golang or +rust, but bash and lua is also available. + +```toml +[project] +# ... + +[project.actions.run] +type = "bash" +command = """ + cargo run -p some-cuddle-project -- $@ +""" +``` + +This action can be invoked via. + +```bash +cuddle do run +``` + +Scripts are also based on convention, so if a rust action is used: + +```bash +cuddle init action rust +``` + +Nothing will be added to the `cuddle.toml` instead you'll receive a +`actions/rust/` project where you can fill out the clis according to the +template given. + +### Plans + +Plans are a crucial component for code sharing, enforcement of values, metrics +and so on. Plans provide a predefined journey for how to work with a specific +type of application. I.e. what does our organisation think a Rust application +look like? + +Plans are maintained via. the `plan` section of the `cuddle.toml` file + +```toml +[plan] +git = "https://github.com/kjuulh/some-cuddle-plan.git" +branch = "main" + +# Alternatively +plan = "https://github.com/kjuulh/some-cuddle-plan.git" # if you want the default + +[project] +# ... +``` + +A plan itself will be maintained via. a `cuddle.plan.toml` file. + +```bash +cuddle init plan +``` + +```toml +[plan] +name = "some-cuddle-plan" + +[plan.components] +canteen = {git = "https://github.com/kjuulh/canteen"} +ingress = {git = "https://github.com/kjuulh/cuddle-ingress"} +ip-allowlist = {git = "https://github.com/kjuulh/ip-allowlist"} +```