gitops-ai 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 everythings-gonna-be-alright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,20 +1,23 @@
-# GitOps AI Bootstrapper
+# GitOps AI - Bootstrapper
 
-GitOps-managed Kubernetes infrastructure for AI-powered applications powered by the [Flux Operator](https://fluxoperator.dev/) and [Flux CD](https://fluxcd.io/). A single bootstrap script provisions a Kubernetes cluster, installs all infrastructure components, and enables continuous delivery from Git.
+[![Website](https://img.shields.io/badge/website-gitops--ai.vercel.app-blue)](https://gitops-ai.vercel.app) [![Docs](https://img.shields.io/badge/docs-gitops--ai.vercel.app-orange)](https://gitops-ai.vercel.app/#docs/prerequisites)
+
+GitOps-managed Kubernetes infrastructure for AI-powered applications powered by the [Flux Operator](https://fluxoperator.dev/) and [Flux CD](https://fluxcd.io/). A single bootstrap application provisions a Kubernetes cluster, installs all infrastructure components, and enables continuous delivery from Git.
 
 ## Why GitOps for your infrastructure
 
 **💾 Infrastructure as Code** -- your entire cluster is defined in Git. Every change is versioned, reviewable, and reversible. You can modify infrastructure with AI coding assistants (Cursor, Copilot, Claude) that understand YAML and Helm values -- describe what you want in natural language and commit the result.
 
-**Security by default** -- containers run as non-root with read-only filesystems and dropped capabilities. Network policies isolate workloads so pods can only communicate with explicitly allowed services. Secrets are encrypted at rest with SOPS/Age before they ever reach Git. SSL certificates are automatically managed by cert-manager.
+**🔒 Security by default** -- containers run as non-root with read-only filesystems and dropped capabilities. Network policies isolate workloads so pods can only communicate with explicitly allowed services. Secrets are encrypted at rest with SOPS/Age before they ever reach Git. SSL certificates are automatically managed by cert-manager.
 
-**Reproducible deployments** -- the same bootstrap script produces an identical cluster every time, on any supported machine. Drift is automatically corrected by Flux reconciliation -- if someone manually changes a resource, Flux reverts it to match Git within minutes.
+**🔄 Reproducible deployments** -- the same bootstrap script produces an identical cluster every time, on any supported machine. Drift is automatically corrected by Flux reconciliation -- if someone manually changes a resource, Flux reverts it to match Git within minutes.
 
-**Scalable and flexible** -- powered by Kubernetes, you can add worker nodes to grow capacity or drop in new components like Lego blocks. Need a database, a message queue, or another AI model? Add a HelmRelease to the repo and push -- Flux deploys it automatically.
+**🔌 Scalable and flexible** -- powered by Kubernetes, you can add worker nodes to grow capacity or drop in new components like Lego blocks. Need a database, a message queue, or another AI model? Add a HelmRelease to the repo and push -- Flux deploys it automatically.
 
 ## Quick Start
 
-Run on our macOS machine:
+On your Mac or Linux machine:
+
 ```bash
 npx gitops-ai bootstrap
 ```
@@ -31,17 +34,17 @@ Or, if you already have Node.js >= 18:
 npx gitops-ai bootstrap
 ```
 
-The interactive wizard will prompt for your GitLab PAT, fork the template into your namespace, and run the full bootstrap.
+The interactive wizard will prompt for your Git provider (GitHub or GitLab), create or use a repository from the [GitOps AI Template](https://gitlab.com/everythings-gonna-be-alright/gitops_ai_template), and run the full bootstrap.
 
 ## Requirements
 
-| Resource       | Minimum                |
-|----------------|------------------------|
-| **CPU**        | 2+ cores               |
-| **Memory**     | 4+ GB                  |
-| **Disk**       | 20+ GB free            |
-| **OS**         | Ubuntu 25.04+ or macOS |
-| **Node.js**    | 18+ (installed automatically by `install.sh`) |
+| Resource    | Minimum                                       |
+|-------------|-----------------------------------------------|
+| **CPU**     | 2+ cores                                      |
+| **Memory**  | 4+ GB                                         |
+| **Disk**    | 20+ GB free                                   |
+| **OS**      | Ubuntu 25.04+ or macOS                        |
+| **Node.js** | 18+ (installed automatically by `install.sh`) |
 
 You will also need a [GitLab PAT](docs/prerequisites.md#1-gitlab-personal-access-token), a [Cloudflare API Token](docs/prerequisites.md#2-cloudflare-api-token) (if using automatic DNS/TLS), and an [OpenAI API Key](docs/prerequisites.md#3-openai-api-key) (if using OpenClaw). See [Prerequisites](docs/prerequisites.md) for full details.
 
@@ -67,9 +70,21 @@ Keeping the template in a separate repository means:
 - **Clean separation** -- the bootstrapper CLI handles provisioning logic; the template holds pure infrastructure declarations. Each can be versioned and tested independently.
 - **Customisation without lock-in** -- after the fork you own the repo. Add namespaces, swap Helm charts, or restructure directories to fit your needs.
 
+### Repository layout (template → your repo)
+
+The upstream template (and your bootstrapped repo) is organised roughly as:
+
+| Path                     | Role                                                                                                                                                                                        |
+|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `templates/<category>/…` | Shared Helm bases and component manifests (e.g. `templates/system/`, `templates/ai/`, `templates/monitoring/`). |
+| `clusters/_template/`    | Prototype cluster layout; the CLI copies this to `clusters/<your-cluster-name>/` during bootstrap.            |
+| `clusters/<name>/`       | Your live cluster overlay (`cluster-sync.yaml`, `components/`, encrypted secrets).                                                                                                          |
+
+See [Architecture](docs/architecture.md) for diagrams and a fuller tree.
+
 ## CLI Commands
 
-The CLI provides three commands:
+The CLI provides these commands:
 
 ### `bootstrap` (alias: `install`)
 
@@ -89,16 +104,16 @@ SOPS secret encryption management. Run without arguments for an interactive menu
 npx gitops-ai sops [subcommand] [file]
 ```
 
-| Subcommand       | Description                                              |
-|------------------|----------------------------------------------------------|
+| Subcommand       | Description                                                            |
+|------------------|------------------------------------------------------------------------|
 | `init`           | First-time setup: generate age key, create `.sops.yaml` and K8s secret |
-| `encrypt`        | Encrypt all unencrypted secret files                     |
-| `encrypt <file>` | Encrypt a specific file                                  |
-| `decrypt <file>` | Decrypt a file for viewing (re-encrypt before commit)    |
-| `edit <file>`    | Open encrypted file in `$EDITOR` (auto re-encrypts on save) |
-| `status`         | Show encryption status of all secret files               |
-| `import`         | Import an existing age key into a new cluster            |
-| `rotate`         | Rotate to a new age key and re-encrypt everything        |
+| `encrypt`        | Encrypt all unencrypted secret files                                   |
+| `encrypt <file>` | Encrypt a specific file                                                |
+| `decrypt <file>` | Decrypt a file for viewing (re-encrypt before commit)                  |
+| `edit <file>`    | Open encrypted file in `$EDITOR` (auto re-encrypts on save)            |
+| `status`         | Show encryption status of all secret files                             |
+| `import`         | Import an existing age key into a new cluster                          |
+| `rotate`         | Rotate to a new age key and re-encrypt everything                      |
 
 ### `openclaw-pair`
 
@@ -108,41 +123,59 @@ Pair an OpenClaw device with the cluster after bootstrap:
 npx gitops-ai openclaw-pair
 ```
 
+### `template sync`
+
+Fetch the upstream GitOps template and merge changes into your current branch. Run without flags for an **interactive wizard** (tag picker, diff preview with risk classification, merge/dry-run/cancel), or pass flags for non-interactive use:
+
+```bash
+npx gitops-ai template sync                        # interactive wizard
+npx gitops-ai template sync --ref v1.0.0           # non-interactive merge
+npx gitops-ai template sync --ref main --dry-run   # non-interactive preview
+```
+
+See [Template synchronization](docs/template-sync.md).
+
 ## Components
 
 The bootstrap wizard lets you select which components to install:
 
-| Component                   | Required | Description                                  |
-|-----------------------------|----------|----------------------------------------------|
-| Helm Repositories           | Yes      | Shared Helm chart repos                      |
-| Ingress Nginx (external)    | Yes      | External HTTP/HTTPS ingress controller       |
-| Prometheus CRDs             | Yes      | Monitoring custom resource definitions       |
-| Cert Manager                | DNS/TLS  | Automatic TLS certificates via Let's Encrypt |
-| External DNS                | DNS/TLS  | Automatic DNS records in Cloudflare          |
-| Flux Web UI                 | No       | Web dashboard for Flux status                |
-| OpenClaw                    | No       | AI assistant gateway (requires OpenAI key)   |
+| Component                   | Required | Description                                        |
+|-----------------------------|----------|----------------------------------------------------|
+| Helm Repositories           | Yes      | Shared Helm chart repos                            |
+| Ingress Nginx (external)    | Yes      | External HTTP/HTTPS ingress controller             |
+| Prometheus CRDs             | Yes      | Monitoring custom resource definitions             |
+| Cert Manager                | DNS/TLS  | Automatic TLS certificates via Let's Encrypt       |
+| External DNS                | DNS/TLS  | Automatic DNS records in Cloudflare                |
+| Grafana Operator            | No       | Grafana dashboards and datasources via CRDs        |
+| Victoria Metrics Stack      | No       | Metrics collection, alerting and long-term storage |
+| Flux Web UI                 | No       | Web dashboard for Flux status                      |
+| OpenClaw                    | No       | AI assistant gateway (requires OpenAI key)         |
 
 Components marked **DNS/TLS** are automatically enabled when you opt into automatic DNS and TLS management during the wizard.
 
 ## Documentation
 
-| Document | Description |
-|----------|-------------|
-| [Prerequisites](docs/prerequisites.md) | API tokens, Docker runtime, network requirements |
-| [Bootstrap](docs/bootstrap.md) | What the bootstrap does, wizard walkthrough, resume capability |
-| [Architecture](docs/architecture.md) | Repository structure, Flux Operator, GitOps workflow |
-| [Configuration](docs/configuration.md) | Cluster variables, environment variables, post-bootstrap changes |
+| Document                                          | Description                                                         |
+|---------------------------------------------------|---------------------------------------------------------------------|
+| [Prerequisites](docs/prerequisites.md)            | Node.js, Docker (macOS), Git provider, optional Cloudflare / OpenAI |
+| [Bootstrap](docs/bootstrap.md)                    | What the bootstrap does, wizard walkthrough, resume capability      |
+| [Architecture](docs/architecture.md)              | Repositories, bootstrap flow, Flux Operator & Instance, repo tree   |
+| [Configuration](docs/configuration.md)            | Cluster variables, SOPS defaults, post-bootstrap changes            |
+| [Template synchronization](docs/template-sync.md) | Upstream merges, `template sync`, CI parity, risk tiers             |
+| [Scaling](docs/scaling.md)                        | Adding k3s worker and server nodes (Linux)                          |
+| [Security](docs/security.md)                      | SOPS, Git auth, hardening, network                                  |
 
 ## Development
 
 ```bash
-git clone <repo-url> && cd gitops-ai
+git clone https://gitlab.com/everythings-gonna-be-alright/gitops_ai_bootstrapper.git
+cd gitops_ai_bootstrapper
 npm install
 
 npm run dev              # Run CLI locally via tsx
 npm run build            # Compile TypeScript to dist/
 npm run typecheck        # Type-check without emitting
-npm run test:validate    # Validate Flux build against template
+npm run test:sync        # Unit tests for template sync logic
 npm run test:integration # Full k3d + Flux integration test (requires Docker)
 ```