docs: full docs about CI / CD, semantic-release, versioning and run…

…time - client WIP 🥷

docs/.vitepress/sidebar.config.mts

@@ -7,6 +7,10 @@ export const SIDEBAR: DefaultTheme.Sidebar = [
         link: '../quick-start',
         collapsed: false,
         items: [
+            {
+                text: 'Node.js Runtime 🚀',
+                link: 'runtime-explain',
+            },
             {
                 text: 'Bundler Options 🏗️',
                 link: 'bundler-options',
@@ -21,6 +25,26 @@ export const SIDEBAR: DefaultTheme.Sidebar = [
             },
         ],
     },
+    {
+        text: 'CI / CD 🐙',
+        base: '/app/ci/',
+        collapsed: false,
+        items: [
+            {
+                text: 'GitHub Actions 🤖',
+                link: 'github-actions',
+            },
+            {
+                text: 'Semantic Release 🚀',
+                link: 'semantic-release',
+            },
+        ],
+    },
+    {
+        text: 'Client',
+        base: '/app/client/',
+        link: 'client',
+    },
     {
         text: 'Troubleshooting',
         base: '/app/troubleshooting/',

docs/app/ci/github-actions.md

@@ -0,0 +1,184 @@
+---
+prev: false
+next: true
+---
+
+# GitHub Actions :octopus:
+
+### Description
+
+`fast-alfred` CI / CD template recommends you work with [GitHub Actions](https://docs.github.com/en/actions).
+
+At the end of this process, you'd be able to publish your Workflow into GitHub Releases.
+
+::: warning Note :warning:
+The following example uses `semantic-release` mechanism and all related packages.
+Please follow the [Semantic Release](./semantic-release) guide to set up your project.
+
+:::
+
+## Setup
+
+::: tip Note :zap:
+Copy these files into your `.github/workflows` folder, at the root of your project.
+You can modify them to fit your needs. The current structure is a suggestion to reduce the maintenance of your CI / CD.
+:::
+
+::: code-group
+
+```yaml [.github/workflows/release-master.yaml]
+---
+name: '📦 Create New Release'
+
+on:
+    push:
+        branches:
+            - master
+
+permissions:
+    contents: write
+    pull-requests: write
+    issues: write
+    deployments: write
+
+concurrency:
+    group: release-master-${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    checks:
+        name: ✅ Check for Release
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+
+        env:
+            HUSKY: 0
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 1
+
+            - name: 🧪 Check out repository code
+              uses: ./.github/workflows/health-check
+              with:
+                  run-tests: 'false'
+
+    release:
+        name: 📦 Release Version
+        runs-on: ubuntu-latest
+        timeout-minutes: 60
+        needs:
+            - checks
+
+        env:
+            HUSKY: 0
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+                  persist-credentials: false
+
+            - name: Git Config
+              run: |
+                  git config --global user.name "github-bot"
+                  git config --global user.email "[email protected]"
+
+            - name: 🖥️ Setup Env
+              uses: ./.github/workflows/install
+
+            - name: Release
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+                  GIT_AUTHOR_NAME: github-bot
+                  GIT_AUTHOR_EMAIL: [email protected]
+                  GIT_COMMITTER_NAME: github-bot
+                  GIT_COMMITTER_EMAIL: [email protected]
+              run: |
+                  npx semantic-release
+```
+
+```yaml [.github/workflows/health-check/action.yaml]
+---
+name: '☑️ Checks Pipeline'
+description: 'Checks the codebase health'
+
+inputs:
+    run-tests-command:
+        description: 'Run tests command, default is `npm test`'
+        default: 'npm test'
+        required: false
+
+    run-tests:
+        description: 'Run tests'
+        default: 'true'
+        required: false
+
+    run-lint-command:
+        description: 'Run linter command, default is `npm run lint`'
+        default: 'npm run lint'
+        required: false
+
+    run-lint:
+        description: 'Run lint'
+        default: 'true'
+        required: false
+
+    run-build-command:
+        description: 'Run build command, default is `npm run build`'
+        default: 'npm run build'
+        required: false
+
+    run-build:
+        description: 'Run build'
+        default: 'true'
+        required: false
+
+runs:
+    using: composite
+    steps:
+        - name: 🖥️ Setup Env
+          uses: ./.github/workflows/install
+
+        - name: 🧪 Test
+          if: ${{ inputs.run-tests == 'true' }}
+          shell: bash
+          run: |
+              ${{ inputs.run-tests-command }}
+
+        - name: 🔨 Build
+          if: ${{ inputs.run-build == 'true' }}
+          shell: bash
+          run: |
+              ${{ inputs.run-build-command }}
+
+        - name: ✅ Lint
+          if: ${{ inputs.run-lint == 'true' }}
+          shell: bash
+          run: |
+              ${{ inputs.run-lint-command }}
+```
+
+```yaml [.github/workflows/install/action.yaml]
+---
+name: '☑️ Install deps'
+description: 'Install dependencies and setup node'
+
+runs:
+    using: composite
+    steps:
+        - name: 🖥️ Setup Node
+          uses: actions/setup-node@v4
+          with:
+              node-version: 20
+
+        - name: 🔗 Install Dependencies
+          shell: bash
+          run: |
+              npm ci --no-fund --no-audit --no-progress --ignore-scripts
+```
+
+:::

docs/app/ci/semantic-release.md

@@ -0,0 +1,85 @@
+---
+prev: true
+next: false
+---
+
+# Semantic Release :rocket:
+
+### Description
+
+`fast-alfred` CI / CD template recommends you work with [`semantic-release`](https://github.com/semantic-release/semantic-release).
+
+## Installation
+
+```bash
+npm install semantic-release @semantic-release/{changelog,commit-analyzer,exec,git,github,release-notes-generator}
+```
+
+## Setup
+
+::: warning Note :warning:
+Fill in the upper case placeholders with your own values, such as `REPO_NAME`, `WORKFLOW_NAME`, etc.
+:::
+
+Create a `.releaserc` file in the root of your project and add the following configuration:
+
+::: code-group
+
+```json [.releaserc]
+{
+    "$schema": "https://json.schemastore.org/semantic-release.json",
+    "repositoryUrl": "https://github.com/REPO_NAME.git",
+    "branches": [
+        "+([0-9])?(.{+([0-9]),x}).x",
+        "master",
+        "next",
+        "next-major",
+        {
+            "name": "beta",
+            "prerelease": true
+        },
+        {
+            "name": "alpha",
+            "prerelease": true
+        }
+    ],
+    "tagFormat": "v${version}",
+    "plugins": [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        [
+            "@semantic-release/changelog",
+            {
+                "changelogFile": "CHANGELOG.md"
+            }
+        ],
+        [
+            "@semantic-release/exec",
+            {
+                "prepareCmd": "npx fast-alfred -t ${nextRelease.version}"
+            }
+        ],
+        [
+            "@semantic-release/git",
+            {
+                "assets": ["package.json", "package-lock.json", "info.plist", "CHANGELOG.md"],
+                "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+            }
+        ],
+        [
+            "@semantic-release/github",
+            {
+                "assets": [
+                    {
+                        "path": "./esbuild/WORKFLOW_NAME.alfredworkflow",
+                        "label": "WORKFLOW_NAME.alfredworkflow",
+                        "name": "WORKFLOW_NAME.alfredworkflow"
+                    }
+                ]
+            }
+        ]
+    ]
+}
+```
+
+:::

docs/app/client/client.md

@@ -0,0 +1,8 @@
+---
+prev: false
+next: false
+---
+
+# `fast-alfred` Client
+
+<!-- TODO - add explain about the client -->

docs/app/quick-start.md

@@ -1,8 +1,8 @@
 ---
 prev: false
 next:
-    text: 'Install Command'
-    link: '/app/commands/install'
+    text: 'Node.js Runtime 🚀'
+    link: '/app/setup/runtime-explain'
 ---
 
 # Quick Start
@@ -13,7 +13,30 @@ next:
 npm install fast-alfred
 ```
 
-## The Reason
+### Configuration
+
+Create a `.fast-alfred.config.cjs` file in the root of your project and add the following configuration:
+
+```javascript
+/**
+ * @type {import('fast-alfred').FastAlfredConfig}
+ */
+module.exports = {}
+```
+
+### Build Your First Workflow
+
+1. Create a Workflow via Alfred UI, or use an existing one
+1. Open the Workflow directory, copy relevant files
+1. Create a new directory for your Workflow
+ <!-- TODO link -->
+1. Use `fast-alfred` client utilities to manage your Workflow
+1. Call your scripts using [`fast-alfred` runtime](./setup/runtime-explain)
+
+<br>
+<hr>
+
+# The Reason
 
 `fast-alfred` lets you think about the functionality, rather than the boilerplate.
 

docs/app/setup/bundler-options.md

@@ -14,7 +14,7 @@ named `.fast-alfred.config.cjs`.
 
 # Available Options
 
-::: tip Note :bulb:
+::: tip Note :zap:
 `fast-alfred` has a default configuration that should work for most of the workflows.
 :::
 
@@ -80,12 +80,10 @@ module.exports = {
 By default, `fast-alfred` would place all the output files under the `esbuild` directory.
 You can change that by setting the `targetDir` property.
 
-<!-- TODO - add a link to CI CD -->
-
 ::: warning CI / CD Usage :rotating_light:
 
-If you're using the `fast-alfred` CI / CD template, updating the `targetDir` property should be handled automatically.
-Make sure `pack` script works correctly.
+If you're using the [`fast-alfred` CI / CD template](/app/ci/github-actions), updating the `targetDir` property should be handled automatically.
+Make sure `npx fast-alfred pack` script works correctly.
 :::
 
 ##### Example