- update and document all examples

- update readme with getting started & usage guide
- add examples validation on CI

.github/workflows/examples.yml

@@ -0,0 +1,23 @@
+on: [ push, pull_request ]
+name: Test
+jobs:
+  CheckExamples:
+    strategy:
+      matrix:
+        go-version: [ 1.17.x ]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Build
+        run: go build
+
+      - name: Check examples
+        run: ./ci/check_examples.sh

README.md

@@ -4,10 +4,11 @@
 
 Allows you to create local aliases withing directory/repository with proper assertions upon executions.
 
-**The idea behind is to:**
+**Motivation:**
 
-- simplify executing scoped repetitive commands
-- avoid executing commands on wrong environment (e.g. _kubectl_, _terraform_, _helm_, _etc._)
+- Simplify executing scoped repetitive commands
+- Avoid executing commands on wrong environment (e.g. _kubectl_, _terraform_, _helm_, _etc._)
+- Automatically generate OpsDoc from available goals. No need to read through whole README file to start operating on your infrastructure.
 
 ## Install
 
@@ -21,66 +22,9 @@ brew install aaabramov/goal/goal
 
 ## Usage
 
-Create `goal.yaml` file in directory where aliases will be used:
+Run `goal init` in directory where aliases will be used. This will generate example `goal.yaml` file. Use it as a reference to define your own aliases. 
 
-```yaml
-workspace:
-  desc: Current terraform workspace
-  cmd: terraform
-  args:
-    - workspace
-    - show
-
-tf-plan:
-  envs:
-    dev:
-      desc: Terraform plan on dev
-      assert:
-        desc: Check if on dev workspace
-        ref: workspace # References goal above
-        expect: dev    # Checks whether trimmed output from 'ref' goal is equal to "dev"
-      cmd: terraform
-      args:
-        - plan
-        - -var-file
-        - vars/dev.tfvars
-    stage:
-      desc: Terraform plan on stage
-      assert:
-        desc: Check if on stage workspace
-        ref: workspace # References goal above
-        expect: stage  # Checks whether trimmed output from 'ref' goal is equal to "stage"
-      cmd: terraform
-      args:
-        - plan
-        - -var-file
-        - vars/stage.tfvars
-
-tf-apply:
-  envs:
-    dev:
-      desc: Terraform apply on dev
-      assert:
-        desc: Check if on dev workspace
-        ref: workspace # References goal above
-        expect: dev    # Checks whether trimmed output from 'ref' goal is equal to "dev"
-      cmd: terraform
-      args:
-        - apply
-        - -var-file
-        - vars/dev.tfvars
-    stage:
-      desc: Terraform apply on stage
-      assert:
-        desc: Check if on stage workspace
-        ref: workspace # References goal above
-        expect: stage  # Checks whether trimmed output from 'ref' goal is equal to "stage"
-      cmd: terraform
-      args:
-        - apply
-        - -var-file
-        - vars/stage.tfvars
-```
+### List goals
 
 Simply type `goal` to see list of available goals and their dependencies:
 
@@ -106,28 +50,62 @@ Available goals:
 +-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
 ```
 
-Let's see if _goal_ would allow us to apply terraform configuration on wrong environment:
+### Define simple local aliases
 
-```shell
-$ terraform workspace show
-dev
-$ goal tf-apply --on stage
-⚙️ Exec tf-apply-stage
-⌛ Check precondition: Check if on stage workspace
-❗ Precondition failed: workspace
-	Output:   "dev"
-	Expected: "stage"
-	CLI: terraform workspace show
+```yaml
+pods:
+  desc: Get nginx pods
+  cmd: kubectl
+  args:
+    - get
+    - pods
+    - -l
+    - app=nginx
+svc:
+  desc: Get nginx services
+  cmd: kubectl
+  args:
+    - get
+    - svc
+    - -l
+    - app=nginx
+```
+
+### Define goal with assertions
+
+```yaml
+# This example demonstrates how to use custom assertions upon executions.
+
+my-assertion:
+  desc: Get nginx pods
+  cmd: echo
+  args:
+    - -n
+    - $((40 + 2))
+
+my-goal:
+  desc: The Answer to the Ultimate Question of Life
+  assert:
+    - desc: If answer is 42..
+      ref: my-assertion # reference another goal here
+      expect: '42'
+      fix: # CLI on how to fix
+  cmd: echo
+  args:
+    - The Answer to the Ultimate Question of Life, the Universe, and Everything is 42
 ```
 
-## Idea behind
+### Built-in assertions
 
-1. Local alias management  
-   To avoid typing repeatable commands
-2. AssD - Aliases as a Documentation :D  
-   No need to read through whole README file to start operating on you infrastructure
+| Tool      | Example                                  |
+|-----------|------------------------------------------|
+| kubectl   | [examples/kubectl](examples/kubectl)     |
+| helm      | [examples/helm](examples/helm)           |
+| terraform | [examples/terraform](examples/terraform) |
+| gcloud    | [examples/gcloud](examples/gcloud)       |
 
 ## goal vs Makefile
+_TODO_
 
 ## Project plan
 
@@ -159,3 +137,4 @@ $ goal tf-apply --on stage
 - [ ] `goal add GOAL_NAME` -- check if already exists
 - [ ] rework `Fatal` with `err`
 - [ ] suggest `fix?` when precondition failed with `yes/no` prompt
+- [ ] shared description from `goal.name` if there is no specific for env goal

ci/check_examples.sh

@@ -0,0 +1,8 @@
+echo "Checking examples..."
+
+for example_directory in examples/*/; do
+  echo "⌛ Checking $example_directory..."
+  ./goal -c "$example_directory/goal.yaml"
+  echo "✅ $example_directory ok"
+  echo
+done

examples/gcloud/goal.yaml

@@ -0,0 +1,32 @@
+# This example combines two `goal` features:
+# 1. Environmental executions: `goal run ssh --on dev`
+# 2. Built-in `gcloud_project` assertions upon execution
+#    to prevent accidental runs on wrong environment.
+#
+# NOTE: list your projects with `gcloud projects list`
+#
+# Usage:
+#   goal run ssh --on dev
+#   goal run ssh --on stage
+ssh:
+  envs:
+    dev:
+      desc: SSH to dev
+      cmd: gcloud
+      args:
+        - compute
+        - ssh
+        - dev-vm
+        - --zone=us-central1-c
+      assert:
+        - gcloud_project: dev-project
+    stage:
+      desc: SSH to stage
+      cmd: gcloud
+      args:
+        - compute
+        - ssh
+        - stage-vm
+        - --zone=us-central1-c
+      assert:
+        - gcloud_project: stage-project

examples/helm/goal.yaml

@@ -4,8 +4,15 @@
 #    to prevent accidental runs on wrong environment.
 #
 # NOTE: Your can list available `kubectl` contexts with `kubectl config get-contexts`
+#
+# Usage:
+#   goal run dry-run --on dev
+#   goal run dry-run --on stage
+#
+#   goal run upgrade --on dev
+#   goal run upgrade --on stage
 
-helm-dry-run:
+dry-run:
   envs:
     dev:
       desc: Dry run upgrade on dev
@@ -36,7 +43,7 @@ helm-dry-run:
         - .
         - --dry-run
 
-helm-upgrade:
+upgrade:
   envs:
     dev:
       desc: Run upgrade on dev

examples/kubectl/goal.yaml

@@ -0,0 +1,57 @@
+# This example combines two `goal` features:
+# 1. Environmental executions: `goal run apply --on dev`
+# 2. Built-in `kubectl_context` assertions upon execution
+#    to prevent accidental runs on wrong environment.
+#
+# NOTE: list your contexts with `kubectl config get-contexts`
+#
+# Usage:
+#   goal run pods --on dev
+#   goal run pods --on stage
+#
+#   goal run apply --on dev
+#   goal run apply --on stage
+
+pods:
+  envs:
+    dev:
+      desc: Kubectl get app pods on dev
+      cmd: kubectl
+      args:
+        - get
+        - pods
+        - -l
+        - app=nginx
+      assert:
+        - kubectl_context: gke_project_region_dev
+    stage:
+      desc: Kubectl get app pods on stage
+      cmd: kubectl
+      args:
+        - get
+        - pods
+        - -l
+        - app=nginx
+      assert:
+        - kubectl_context: gke_project_region_stage
+
+apply:
+  envs:
+    dev:
+      desc: Kubectl apply on dev
+      cmd: kubectl
+      args:
+        - apply
+        - -f
+        - deployment.yaml
+      assert:
+        - kubectl_context: gke_project_region_dev
+    stage:
+      desc: Kubectl apply on stage
+      cmd: kubectl
+      args:
+        - apply
+        - -f
+        - deployment.yaml
+      assert:
+        - kubectl_context: gke_project_region_stage

examples/simple/goal.yaml

@@ -0,0 +1,25 @@
+# This example demonstrates simply local alias management.
+# Goals(aliases) defined in this file would be available only in
+# project directory.
+#
+# Usage:
+#   goal run pods
+#
+#   goal run svc
+
+pods:
+  desc: Get nginx pods
+  cmd: kubectl
+  args:
+    - get
+    - pods
+    - -l
+    - app=nginx
+svc:
+  desc: Get nginx svc
+  cmd: kubectl
+  args:
+    - get
+    - svc
+    - -l
+    - app=nginx

examples/terraform/README.md

@@ -2,28 +2,29 @@
 
 ```shell
 $ terraform workspace new dev
+Created and switched to workspace "dev"!
+
 $ terraform workspace new stage
+Created and switched to workspace "stage"!
+
 $ goal
 Available goals:
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
-|   GOAL    | ENVIRONMENT |              CLI               |         DESCRIPTION         |           ASSERTIONS           |
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
-| tf-plan   | dev         | terraform plan -var-file       | Terraform plan on dev       | [workspace] Check if on dev    |
-|           |             | vars/dev.tfvars                |                             | workspace                      |
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
-| tf-plan   | stage       | terraform plan -var-file       | Terraform plan on stage     | [workspace] Check if on stage  |
-|           |             | vars/stage.tfvars              |                             | workspace                      |
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
-| tf-apply  | dev         | terraform apply -var-file      | Terraform apply on dev      | [workspace] Check if on dev    |
-|           |             | vars/dev.tfvars                |                             | workspace                      |
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
-| tf-apply  | stage       | terraform apply -var-file      | Terraform apply on stage    | [workspace] Check if on stage  |
-|           |             | vars/stage.tfvars              |                             | workspace                      |
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
-| workspace |             | terraform workspace show       | Current terraform workspace |                                |
-+-----------+-------------+--------------------------------+-----------------------------+--------------------------------+
++-------+-------------+---------------------------------------------+--------------------------+--------------------------------------------------+
+| GOAL  | ENVIRONMENT |                     CLI                     |       DESCRIPTION        |                    ASSERTIONS                    |
++-------+-------------+---------------------------------------------+--------------------------+--------------------------------------------------+
+| apply | dev         | terraform apply -var-file vars/dev.tfvars   | Terraform apply on dev   | Check if selected terraform workspace is "dev"   |
++       +-------------+---------------------------------------------+--------------------------+--------------------------------------------------+
+|       | stage       | terraform apply -var-file vars/stage.tfvars | Terraform apply on stage | Check if selected terraform workspace is "stage" |
++-------+-------------+---------------------------------------------+--------------------------+--------------------------------------------------+
+| plan  | dev         | terraform plan -var-file vars/dev.tfvars    | Terraform plan on dev    | Check if selected terraform workspace is "dev"   |
++       +-------------+---------------------------------------------+--------------------------+--------------------------------------------------+
+|       | stage       | terraform plan -var-file vars/stage.tfvars  | Terraform plan on stage  | Check if selected terraform workspace is "stage" |
++-------+-------------+---------------------------------------------+--------------------------+--------------------------------------------------+
+
 $ terraform workspace show
 stage
+
+# Let's see if goal would allow us to apply terraform configuration on wrong environment:
 $ goal tf-plan --on dev
 Running on dev
 ⚙️  Exec tf-plan