container-superposition 0.1.9 → 0.1.11

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/pi/README.md

@@ -0,0 +1,141 @@
+# Pi Overlay
+
+Adds the [Pi](https://pi.dev) terminal coding agent (`pi`) — a minimal, open-source, self-extensible AI coding harness that lets you use LLMs directly in your terminal to read, write, edit, and run code.
+
+## What is Pi?
+
+Pi is a deliberately minimal terminal coding agent. Unlike heavier AI coding tools, Pi keeps its core tiny and pushes everything extra (MCP, sub-agents, themes, prompt templates) to a TypeScript extension and package system. It supports a wide range of LLM providers, including Anthropic Claude, OpenAI GPT, Google Gemini, DeepSeek, Mistral, Groq, and many more.
+
+## Features
+
+- **Interactive TUI** — Four-panel terminal UI with file reference (`@`), inline shell commands (`!cmd`), and message queueing
+- **Multi-provider LLM support** — Anthropic, OpenAI, Google Gemini, DeepSeek, Mistral, Groq, xAI, OpenRouter, Azure OpenAI, Amazon Bedrock, GitHub Copilot, and more
+- **Built-in tools** — `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
+- **Session management** — Auto-saved sessions with branching, forking, compaction, and resumption
+- **Non-interactive mode** — `pi -p "prompt"` for scripted use or CI pipelines
+- **Extensible** — TypeScript extensions, Skills (SKILL.md), prompt templates, and pi packages
+
+## Installation
+
+This overlay installs Pi via npm (`@earendil-works/pi-coding-agent`), which is the same package installed by the official installer at [pi.dev/install.sh](https://pi.dev/install.sh).
+
+## How It Works
+
+This overlay installs `@earendil-works/pi-coding-agent` globally via npm, making the `pi` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session in the current project
+pi
+
+# One-shot non-interactive prompt
+pi -p "Summarize this codebase"
+
+# Pipe content to Pi
+cat README.md | pi -p "Summarize this"
+
+# Resume the last session
+pi /resume
+
+# Check version
+pi --version
+```
+
+## Use Cases
+
+- **Terminal-first coding assistant** — Use Pi interactively while editing and debugging from the CLI
+- **Automated one-shot tasks** — Run `pi -p "..."` in scripts or CI pipelines
+- **Multi-provider flexibility** — Switch between Anthropic, OpenAI, Gemini, and other supported providers
+
+## Authentication
+
+Set one or more provider API keys as environment variables:
+
+```bash
+# Anthropic Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+
+# Google Gemini
+export GEMINI_API_KEY=...
+```
+
+Alternatively, use the interactive login command inside Pi:
+
+```bash
+/login
+```
+
+## Configuration
+
+Settings are stored in `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project-local):
+
+```json
+{
+    "defaultProvider": "anthropic",
+    "defaultModel": "claude-sonnet-4-20250514",
+    "compaction": { "enabled": true }
+}
+```
+
+| Environment Variable    | Description                                        |
+| ----------------------- | -------------------------------------------------- |
+| `ANTHROPIC_API_KEY`     | Anthropic Claude API key                           |
+| `OPENAI_API_KEY`        | OpenAI API key                                     |
+| `GEMINI_API_KEY`        | Google Gemini API key                              |
+| `PI_OFFLINE`            | Disable startup network operations                 |
+| `PI_SKIP_VERSION_CHECK` | Skip automatic version update check                |
+| `PI_CODING_AGENT_DIR`   | Override config directory (default: `~/.pi/agent`) |
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-pi.sh
+```
+
+## Usage
+
+### Interactive session
+
+Run `pi` in any project directory to start an interactive TUI session. Use `@` to reference files, `!cmd` to run a shell command and send its output to the LLM, and `/help` to list available slash commands.
+
+### Non-interactive / CI mode
+
+```bash
+# Print response and exit
+pi -p "What tests should I write for this function?"
+
+# Output all events as JSONL (for scripting or piping)
+pi --mode json -p "List TODOs in this repo"
+```
+
+### Extending Pi
+
+Pi supports TypeScript extensions, Skills, and npm/git packages:
+
+```bash
+# Install a pi package
+pi install <package-name>
+
+# List installed packages
+pi /packages
+```
+
+## References
+
+- [Pi Website](https://pi.dev)
+- [GitHub Repository](https://github.com/earendil-works/pi)
+- [Usage Documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)
+- [Provider Documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
+- [Extensions Documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md)
+
+**Related Overlays:**
+
+- `nodejs` — Required for npm-based installation
+- `claude-code` — Anthropic Claude Code CLI (alternative AI assistant)
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `gemini-cli` — Google Gemini CLI (alternative AI assistant)
+- `opencode` — opencode AI coding agent (alternative)

package/overlays/pi/devcontainer.patch.json

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

package/overlays/pi/overlay.yml

@@ -0,0 +1,15 @@
+id: pi
+name: Pi
+description: Minimal terminal coding agent with multi-provider LLM support
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - coding-agent
+    - llm
+ports: []

package/overlays/pi/setup.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# pi setup script - Install Pi terminal coding agent
+
+set -e
+
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
+echo "📦 Installing Pi terminal coding agent..."
+
+# Install @earendil-works/pi-coding-agent globally via npm
+# (same package installed by curl -fsSL https://pi.dev/install.sh | sh)
+npm install -g @earendil-works/pi-coding-agent
+
+# Verify installation
+if command -v pi &>/dev/null; then
+    echo "✓ Pi installed successfully: $(pi --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ Pi installation failed"
+    exit 1
+fi
+
+echo "✓ pi setup complete"
+echo "ℹ️  Pi terminal coding agent: https://pi.dev"
+echo "ℹ️  GitHub: https://github.com/earendil-works/pi"
+echo "ℹ️  Run 'pi --help' to get started"

package/overlays/pi/verify.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# pi overlay verification script
+
+set -e
+
+echo "🔍 Verifying pi overlay setup..."
+
+# Check if pi CLI is installed
+if ! command -v pi &>/dev/null; then
+    echo "✗ pi is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ pi is installed: $(pi --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ pi overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'pi' in any project directory to start an interactive session"
+echo "  - Run 'pi --help' to see available commands"
+echo "  - Run 'pi -p \"<prompt>\"' for a non-interactive one-shot prompt"
+echo "  - Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY to authenticate"

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.11",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",
@@ -17,6 +17,7 @@
         "test:integration": "INTEGRATION=true vitest run tool/__tests__/overlay-features-integration.test.ts",
         "test:smoke": "bash scripts/test.sh",
         "docs:generate": "tsx docs/generate-docs.ts && prettier --write docs/overlays.md",
+        "schema:generate": "tsx scripts/generate-schema.ts && prettier --write tool/schema/superposition.schema.json",
         "lint": "tsc --noEmit && npm run format:check",
         "lint:fix": "npm run format",
         "format": "prettier --write \"**/*.{ts,js,json,md,yaml,yml}\"",