container-superposition 0.1.9 → 0.1.10

package/overlays/argocd/README.md

@@ -0,0 +1,158 @@
+# Argo CD CLI Overlay
+
+Adds the [`argocd`](https://argo-cd.readthedocs.io/) CLI for managing GitOps workflows with an Argo CD server — log in, inspect apps, trigger syncs, and manage rollouts without leaving your devcontainer.
+
+## Features
+
+- **Argo CD CLI** — `argocd` client for login, app sync, rollback, and lifecycle operations
+- **Release install** — binary downloaded from official Argo CD GitHub releases
+- **Architecture-aware** — installs `amd64` or `arm64` automatically
+
+## How It Works
+
+The `argocd` binary is downloaded from the official Argo CD GitHub releases page (`github.com/argoproj/argo-cd`) during devcontainer creation via `setup.sh`.
+
+- Detects host architecture (`amd64` / `arm64`) automatically
+- Downloads the matching pre-built binary and places it in `/usr/local/bin/argocd`
+- No Argo CD server is run inside the devcontainer — the CLI connects to an external (or locally port-forwarded) Argo CD server
+
+**Dependencies:** None required. Pair with `kubectl-helm` for full cluster access, and `k3d` or `kind` for local Kubernetes clusters where you can deploy Argo CD for testing.
+
+## Common Commands
+
+### Authentication
+
+```bash
+# Login to an Argo CD server
+argocd login argocd.example.com
+
+# Login with TLS disabled (for local/dev servers)
+argocd login localhost:8080 --insecure
+
+# Login and save context (avoids re-entering credentials)
+argocd login argocd.example.com --grpc-web
+
+# Check current logged-in context
+argocd context
+
+# Switch context
+argocd context my-cluster
+
+# Logout
+argocd logout argocd.example.com
+```
+
+### Application Management
+
+```bash
+# List all applications
+argocd app list
+
+# Get detailed status of an app
+argocd app get my-app
+
+# Create an app (GitOps source)
+argocd app create my-app \
+  --repo https://github.com/myorg/my-manifests.git \
+  --path k8s/overlays/dev \
+  --dest-server https://kubernetes.default.svc \
+  --dest-namespace my-app
+
+# Sync (deploy) an app
+argocd app sync my-app
+
+# Wait for sync to complete
+argocd app wait my-app --sync
+
+# Delete an app (without deleting cluster resources)
+argocd app delete my-app
+
+# Delete an app and all managed cluster resources
+argocd app delete my-app --cascade
+```
+
+### Sync Operations
+
+```bash
+# Sync only specific resources
+argocd app sync my-app --resource apps:Deployment:my-app
+
+# Force sync (ignores resource health)
+argocd app sync my-app --force
+
+# Dry-run sync (show diff without applying)
+argocd app diff my-app
+
+# Rollback to a previous revision
+argocd app rollback my-app 3
+
+# View app history
+argocd app history my-app
+```
+
+### Projects & RBAC
+
+```bash
+# List projects
+argocd proj list
+
+# Create a project
+argocd proj create my-project \
+  --description "My project" \
+  --src https://github.com/myorg/my-manifests.git \
+  --dest https://kubernetes.default.svc,my-namespace
+
+# List project roles
+argocd proj role list my-project
+```
+
+## Local Port-Forward Workflow
+
+When testing Argo CD in a local cluster (k3d / kind):
+
+```bash
+# Install Argo CD in the cluster
+kubectl create namespace argocd
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+
+# Wait for pods to be ready
+kubectl -n argocd wait --for=condition=ready pod -l app.kubernetes.io/name=argocd-server --timeout=120s
+
+# Port-forward the API server
+kubectl -n argocd port-forward svc/argocd-server 8080:443 &
+
+# Get the initial admin password
+argocd admin initial-password -n argocd
+
+# Login
+argocd login localhost:8080 --insecure
+```
+
+## Use Cases
+
+- **GitOps deployments** — Sync Kubernetes manifests from Git to a cluster via Argo CD
+- **Multi-environment promotion** — Manage dev/staging/production app variants with app-of-apps patterns
+- **Rollback workflows** — Inspect history and revert to a previous known-good revision
+- **Local GitOps testing** — Deploy Argo CD to a local `k3d` or `kind` cluster to test GitOps pipelines without a cloud environment
+- **Drift detection** — Use `argocd app diff` to detect config drift before syncing
+
+**Integrates well with:**
+
+- `kubectl-helm` — Kubernetes CLI and Helm for inspecting or patching resources managed by Argo CD
+- `k3d` — Lightweight local clusters for GitOps development and testing
+- `kind` — Full-conformance local clusters for Argo CD testing
+- `terraform` — Provision the cluster and bootstrap Argo CD with Terraform, then manage apps with the CLI
+
+## References
+
+- [Argo CD Documentation](https://argo-cd.readthedocs.io/)
+- [Argo CD CLI Reference](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd/)
+- [Argo CD GitHub Releases](https://github.com/argoproj/argo-cd/releases)
+- [Argo CD Getting Started](https://argo-cd.readthedocs.io/en/stable/getting_started/)
+- [App of Apps Pattern](https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/)
+
+**Related Overlays:**
+
+- [`kubectl-helm`](../kubectl-helm/README.md) — Kubernetes CLI and Helm package manager
+- [`k3d`](../k3d/README.md) — Lightweight local Kubernetes clusters
+- [`kind`](../kind/README.md) — Full-conformance local Kubernetes clusters

package/overlays/argocd/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "postCreateCommand": {
+        "setup-argocd": "bash .devcontainer/scripts/setup-argocd.sh"
+    },
+    "postStartCommand": {
+        "verify-argocd": "bash .devcontainer/scripts/verify-argocd.sh"
+    }
+}

package/overlays/argocd/overlay.yml

@@ -0,0 +1,17 @@
+id: argocd
+name: Argo CD CLI
+description: GitOps CLI for managing Argo CD applications and sync workflows
+category: cloud
+supports: []
+requires: []
+suggests:
+    - kubectl-helm
+    - k3d
+    - kind
+conflicts: []
+tags:
+    - cloud
+    - kubernetes
+    - gitops
+    - argocd
+ports: []

package/overlays/argocd/setup.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Setup script for Argo CD CLI
+
+set -e
+
+echo "🔧 Setting up Argo CD CLI..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
+
+ARGOCD_VERSION="${ARGOCD_VERSION:-v2.14.12}"
+echo "📦 Installing argocd ${ARGOCD_VERSION}..."
+
+install_binary \
+    "https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-${CS_ARCH}" \
+    "argocd"
+
+if command -v argocd >/dev/null 2>&1; then
+    echo "✅ Argo CD CLI installed successfully"
+    argocd version --client --short || argocd version --client
+else
+    echo "❌ Argo CD CLI installation failed"
+    exit 1
+fi
+
+echo "✅ Argo CD CLI setup complete"

package/overlays/argocd/verify.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Verification script for Argo CD CLI overlay
+
+set -e
+
+echo "🔍 Verifying Argo CD CLI overlay..."
+
+if command -v argocd >/dev/null 2>&1; then
+    argocd version --client --short || argocd version --client
+    echo "✅ Argo CD CLI is installed"
+else
+    echo "❌ Argo CD CLI is not installed"
+    exit 1
+fi

package/overlays/task/README.md

@@ -0,0 +1,47 @@
+# Taskfile (task) Overlay
+
+Adds [Task](https://taskfile.dev/) (`task`) to run project automation via `Taskfile.yml`.
+
+## Features
+
+- **Task CLI** — fast, modern task runner (`task`)
+- **Taskfile workflows** — declarative task definitions with dependencies and variables
+- **Architecture-aware install** — installs amd64 or arm64 binary automatically
+
+## Quick Start
+
+```bash
+task --version
+task --list
+```
+
+Create a basic `Taskfile.yml`:
+
+```yaml
+version: '3'
+
+tasks:
+    default:
+        cmds:
+            - task --list
+
+    lint:
+        cmds:
+            - npm run lint
+
+    test:
+        cmds:
+            - npm test
+```
+
+Run tasks:
+
+```bash
+task lint
+task test
+```
+
+## Suggested Pairings
+
+- `modern-cli-tools` — useful companion CLIs for day-to-day development
+- `kubectl-helm` — pair task automation with Kubernetes workflows

package/overlays/task/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "postCreateCommand": {
+        "setup-task": "bash .devcontainer/scripts/setup-task.sh"
+    },
+    "postStartCommand": {
+        "verify-task": "bash .devcontainer/scripts/verify-task.sh"
+    }
+}

package/overlays/task/overlay.yml

@@ -0,0 +1,16 @@
+id: task
+name: Taskfile (task)
+description: Modern task runner and build tool using Taskfiles
+category: dev
+supports: []
+requires: []
+suggests:
+    - modern-cli-tools
+    - kubectl-helm
+conflicts: []
+tags:
+    - dev
+    - automation
+    - taskfile
+    - build
+ports: []

package/overlays/task/setup.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Setup script for Taskfile (task)
+
+set -e
+
+echo "🔧 Setting up Taskfile (task)..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
+
+TASK_VERSION="${TASK_VERSION:-v3.45.4}"
+echo "📦 Installing task ${TASK_VERSION}..."
+
+install_binary_from_tar \
+    "https://github.com/go-task/task/releases/download/${TASK_VERSION}/task_linux_${CS_ARCH}.tar.gz" \
+    "task"
+
+if command -v task >/dev/null 2>&1; then
+    echo "✅ task installed successfully"
+    task --version
+else
+    echo "❌ task installation failed"
+    exit 1
+fi
+
+echo "✅ Taskfile setup complete"

package/overlays/task/verify.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Verification script for Taskfile (task) overlay
+
+set -e
+
+echo "🔍 Verifying Taskfile overlay..."
+
+if command -v task >/dev/null 2>&1; then
+    task --version
+    echo "✅ task is installed"
+else
+    echo "❌ task is not installed"
+    exit 1
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.9",
+    "version": "0.1.10",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",

package/tool/schema/config.schema.json

@@ -272,6 +272,41 @@
                 ]
             }
         },
+        "mounts": {
+            "description": "Project-level mount specs routed to devcontainer.json mounts or docker-compose volumes based on stack/target",
+            "oneOf": [
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/projectMountEntry"
+                    }
+                },
+                {
+                    "type": "object",
+                    "description": "Named mount map form",
+                    "additionalProperties": {
+                        "$ref": "#/$defs/projectMountObject"
+                    }
+                }
+            ]
+        },
+        "shell": {
+            "type": "object",
+            "description": "Shell profile customizations written via a managed shell-init hook",
+            "properties": {
+                "aliases": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" },
+                    "description": "Alias name -> command map (e.g. k: kubectl)"
+                },
+                "snippets": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Raw shell snippets appended to generated shell-init"
+                }
+            },
+            "additionalProperties": false
+        },
         "customizations": {
             "type": "object",
             "properties": {
@@ -328,5 +363,43 @@
         }
     },
     "required": [],
-    "additionalProperties": false
+    "additionalProperties": false,
+    "$defs": {
+        "projectMountTarget": {
+            "type": "string",
+            "enum": ["auto", "devcontainerMount", "composeVolume"]
+        },
+        "projectMountObject": {
+            "type": "object",
+            "properties": {
+                "value": {
+                    "type": "string",
+                    "description": "Raw mount spec string (escape hatch)"
+                },
+                "source": { "type": "string", "description": "Mount source path or volume name" },
+                "destination": { "type": "string", "description": "Container destination path" },
+                "type": { "type": "string", "enum": ["bind", "volume", "tmpfs"] },
+                "consistency": { "type": "string", "enum": ["consistent", "cached", "delegated"] },
+                "cached": {
+                    "type": "boolean",
+                    "description": "Convenience alias for consistency: cached"
+                },
+                "readOnly": { "type": "boolean" },
+                "target": { "$ref": "#/$defs/projectMountTarget" }
+            },
+            "additionalProperties": false,
+            "oneOf": [{ "required": ["value"] }, { "required": ["source", "destination"] }]
+        },
+        "projectMountEntry": {
+            "oneOf": [
+                {
+                    "type": "string",
+                    "description": "Raw mount spec string"
+                },
+                {
+                    "$ref": "#/$defs/projectMountObject"
+                }
+            ]
+        }
+    }
 }