container-superposition 0.1.3 → 0.1.5

package/docs/examples.md

@@ -10,6 +10,37 @@ npm run init
 
 Follow the prompts to select your stack, database, tools, and output location.
 
+## Declarative Project Config
+
+```yaml
+stack: compose
+language:
+    - nodejs
+database:
+    - postgres
+outputPath: ./.devcontainer
+customizations:
+    environment:
+        APP_ENV: development
+    devcontainerPatch:
+        features:
+            ghcr.io/devcontainers-extra/features/apt-get-packages:1:
+                packages: jq
+```
+
+```bash
+npm run init -- --no-interactive
+```
+
+Creates the same generated output you would get from equivalent clean-generation
+input, while keeping the setup intent in version control.
+
+```bash
+npm run init -- regen
+```
+
+Regenerates from the repository project file by default when one exists.
+
 ## Non-Interactive Examples
 
 ### .NET with PostgreSQL
@@ -411,11 +442,14 @@ npm run init -- --from-manifest ./superposition.json
 
 ### Non-Interactive Regeneration
 
-Regenerate exact same setup (useful for updating to latest overlay versions):
+Use `regen` when you want deterministic replay of a persisted source:
 
 ```bash
-# Regenerate with exact same selections, skip confirmation, no backup
-npm run init -- --from-manifest ./superposition.json --yes --no-backup
+# Regenerate with exact same selections from a manifest, no backup
+npm run init -- regen --from-manifest ./superposition.json --no-backup
+
+# Or let regen use the repository project file when present
+npm run init -- regen
 ```
 
 **Use cases:**
@@ -463,7 +497,7 @@ git push
 # Developer 2: Clone and regenerate from manifest
 git clone <repo>
 npm install
-npm run init -- --from-manifest ./superposition.json --yes
+npm run init -- regen --from-manifest ./superposition.json
 # Gets exact same devcontainer setup
 ```
 
@@ -481,7 +515,7 @@ The manifest stores and restores:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "generated": "2026-02-08T10:00:00Z",
     "baseTemplate": "compose",
     "baseImage": "bookworm",
@@ -572,5 +606,5 @@ mv prod/superposition.json prod-superposition.json
 
 # Now you have three manifests for different environments
 # Regenerate any environment from its manifest
-npm run init -- --from-manifest ./dev-superposition.json --yes --output ./dev
+npm run init -- regen --from-manifest ./dev-superposition.json --output ./dev
 ```

package/docs/filesystem-contract.md

@@ -0,0 +1,58 @@
+# Filesystem Contract
+
+This describes what the tool writes and which files are safe to edit.
+
+## What Gets Written
+
+```
+your-project/
+├── .devcontainer/               # Main devcontainer directory
+│   ├── devcontainer.json        # Container configuration
+│   ├── docker-compose.yml       # Services (compose stack only)
+│   ├── .env.example             # Environment variable templates
+│   ├── ports.json               # Port documentation and connection strings
+│   ├── scripts/                 # Setup and verification scripts
+│   │   ├── post-create.sh       # Runs once when container is created
+│   │   └── post-start.sh        # Runs every time container starts
+│   └── custom/                  # Your customizations (preserved across regen)
+│       ├── devcontainer.patch.json
+│       └── docker-compose.patch.yml
+├── superposition.json           # Manifest file (enables regeneration)
+└── .devcontainer.backup-*/      # Automatic backups (gitignored)
+```
+
+## Files You Should Customize
+
+- `.devcontainer/.env` or `.env` (copied from `.env.example`)
+- `.devcontainer/custom/` (your patches and scripts)
+
+## Files Safe to Edit Directly
+
+- `.devcontainer/custom/devcontainer.patch.json`
+- `.devcontainer/custom/docker-compose.patch.yml`
+- `.devcontainer/custom/environment.env`
+- `.devcontainer/custom/scripts/*`
+
+## Files Regenerated (Do Not Edit Directly)
+
+- `.devcontainer/devcontainer.json`
+- `.devcontainer/docker-compose.yml`
+- `.devcontainer/scripts/*`
+
+## Files You Should Commit
+
+- `superposition.json`
+- `.devcontainer/` (generated configuration)
+- `.devcontainer/custom/` (project-specific patches)
+- `.devcontainer/.env.example`
+
+## Files in .gitignore
+
+```
+# Environment secrets (never commit)
+.env
+.devcontainer/.env
+
+# Regeneration backups (local only)
+.devcontainer.backup-*
+```

package/docs/hash.md

@@ -0,0 +1,183 @@
+# Hash Command
+
+The `hash` command produces a stable, deterministic fingerprint for a devcontainer configuration.
+It lets you verify that two environments are equivalent, detect drift in CI, and commit a reproducible
+stamp alongside your `superposition.json` manifest.
+
+## Overview
+
+```bash
+# From CLI options
+npx container-superposition hash --stack compose --overlays dotnet,postgres,redis
+
+# Reading from an existing manifest (auto-discovers superposition.json)
+npx container-superposition hash
+
+# Machine-readable output
+npx container-superposition hash --stack compose --overlays dotnet,postgres,redis --json
+
+# Write full hash to .devcontainer/superposition.hash
+npx container-superposition hash --write
+```
+
+## What Is Hashed
+
+The fingerprint is a SHA-256 digest of a canonical JSON object with the following fields:
+
+| Field      | Source                                        | Notes                                                  |
+| ---------- | --------------------------------------------- | ------------------------------------------------------ |
+| `stack`    | `--stack` flag or manifest `baseTemplate`     | `plain` or `compose`                                   |
+| `overlays` | Resolved overlay list (alphabetically sorted) | Includes auto-resolved dependencies                    |
+| `preset`   | `--preset` flag or manifest `preset`          | `null` when no preset                                  |
+| `base`     | `--base` flag or manifest `baseImage`         | e.g. `bookworm`, `alpine`                              |
+| `tool`     | Tool version (major.minor only)               | Stable across patch releases; truncated before hashing |
+
+Keys in the canonical object are sorted alphabetically and the overlay list is sorted before hashing,
+so the result is identical regardless of the order overlays are provided.
+
+## Output
+
+### Text Output (default)
+
+```
+╭ Environment Fingerprint ──────────────────────────╮
+│                                                   │
+│   stack        compose                            │
+│   overlays     dotnet, postgres, redis            │
+│   preset       (none)                             │
+│   base         bookworm                           │
+│   tool         0.1.3                              │
+│                                                   │
+│   hash         53ed972d                           │
+│                                                   │
+╰───────────────────────────────────────────────────╯
+```
+
+Auto-resolved dependencies are shown with an `(auto)` label:
+
+```
+overlays     grafana, prometheus (auto)
+```
+
+### JSON Output (`--json`)
+
+```json
+{
+    "stack": "compose",
+    "overlays": ["dotnet", "postgres", "redis"],
+    "preset": null,
+    "base": "bookworm",
+    "tool": "0.1.3",
+    "hash": "53ed972d",
+    "hashFull": "53ed972da2ba0712ae15b4003aa46234e7eeba2e977e7a397453740202ebbea4"
+}
+```
+
+- `hash` — first 8 hex characters, suitable for display and badges
+- `hashFull` — full 64-character SHA-256 hex digest, recommended for CI comparisons
+
+## Options
+
+| Option                | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `--stack <type>`      | Base template: `plain` or `compose`                |
+| `--overlays <list>`   | Comma-separated overlay IDs                        |
+| `--preset <id>`       | Preset ID (optional, reflected in hash)            |
+| `--base <image>`      | Base image/distro (e.g. `bookworm`, `alpine`)      |
+| `--manifest <path>`   | Path to a specific `superposition.json`            |
+| `-o, --output <path>` | Directory to write hash file (used with `--write`) |
+| `--write`             | Write hash to `.devcontainer/superposition.hash`   |
+| `--json`              | Output as JSON for scripting                       |
+
+When `--stack`/`--overlays` are omitted the command searches for `superposition.json` in:
+
+1. Current directory (`superposition.json`)
+2. `.devcontainer/superposition.json`
+3. Parent directory (`../superposition.json`)
+
+## The `--write` Flag
+
+```bash
+npx container-superposition hash --write
+```
+
+Writes the **full** 64-character hash to `.devcontainer/superposition.hash` (one line, no trailing
+whitespace). Commit this file alongside `superposition.json`:
+
+```
+.devcontainer/
+├── devcontainer.json
+├── superposition.json
+└── superposition.hash   ← commit this
+```
+
+Use a custom output directory with `-o`:
+
+```bash
+npx container-superposition hash --write -o ./infra/.devcontainer
+```
+
+## CI Drift Detection
+
+Detect when the environment has changed since the last commit:
+
+```yaml
+- name: Verify environment fingerprint
+  run: |
+      EXPECTED=$(cat .devcontainer/superposition.hash)
+      ACTUAL=$(npx container-superposition hash --json | jq -r .hashFull)
+      [ "$EXPECTED" = "$ACTUAL" ] || (echo "Environment drift detected" && exit 1)
+```
+
+Or using the short hash stored in a badge/README:
+
+```yaml
+- name: Verify short fingerprint
+  run: |
+      EXPECTED="53ed972d"
+      ACTUAL=$(npx container-superposition hash --json | jq -r .hash)
+      [ "$EXPECTED" = "$ACTUAL" ] || (echo "Environment drift detected" && exit 1)
+```
+
+## Stability Guarantees
+
+- **Same inputs → same hash** — guaranteed for any given tool version series
+- **Overlay order is irrelevant** — `postgres,redis` hashes identically to `redis,postgres`
+- **Dependencies are included** — auto-resolved dependencies affect the hash (as they affect the environment)
+- **Patch versions are ignored** — `0.1.3` and `0.1.99` produce the same hash; `0.2.0` does not
+- **Hash changes when any input changes** — stack, overlays, preset, base image, or minor/major tool version
+
+## Examples
+
+### Fingerprint a Standard Web API Stack
+
+```bash
+npx container-superposition hash \
+  --stack compose \
+  --overlays nodejs,postgres,redis
+```
+
+### Read from Manifest and Write Hash File
+
+```bash
+# Run from the project root (manifest at .devcontainer/superposition.json)
+npx container-superposition hash --write
+```
+
+### Compare Two Configurations
+
+```bash
+# Project A
+HASH_A=$(npx container-superposition hash --stack compose --overlays nodejs,postgres --json | jq -r .hash)
+
+# Project B
+HASH_B=$(npx container-superposition hash --manifest ./project-b/.devcontainer/superposition.json --json | jq -r .hash)
+
+[ "$HASH_A" = "$HASH_B" ] && echo "Environments are equivalent" || echo "Environments differ"
+```
+
+## Related Commands
+
+- [`plan`](discovery-commands.md#plan-command) — Preview what will be generated
+- [`list`](discovery-commands.md#list-command) — Browse available overlays
+- [`explain`](discovery-commands.md#explain-command) — Deep dive into a specific overlay

package/docs/minimal-and-editor.md

@@ -243,7 +243,7 @@ Both settings are stored in `superposition.json`:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "generated": "2026-02-13T09:00:00.000Z",
     "minimal": true,
     "editor": "none",

package/docs/overlays.md

@@ -442,6 +442,46 @@ Infrastructure as Code with HCL (includes tflint)
 
 ## Dev Tool Overlays
 
+### Spec Kit (SDD) (`spec-kit`)
+
+Specify CLI for Spec-Driven Development with any AI coding agent
+
+| Property     | Value                                                    |
+| ------------ | -------------------------------------------------------- |
+| **Category** | dev                                                      |
+| **Suggests** | `python`, `codex`                                        |
+| **Tags**     | `dev`, `ai`, `sdd`, `spec-driven`, `specify`, `spec-kit` |
+
+### Amp (`amp`)
+
+Sourcegraph Amp CLI for AI-powered code generation and assistance
+
+| Property     | Value                             |
+| ------------ | --------------------------------- |
+| **Category** | dev                               |
+| **Requires** | `nodejs`                          |
+| **Tags**     | `dev`, `ai`, `amp`, `sourcegraph` |
+
+### Claude Code (`claude-code`)
+
+Anthropic Claude Code CLI for AI-powered development assistance
+
+| Property     | Value                              |
+| ------------ | ---------------------------------- |
+| **Category** | dev                                |
+| **Requires** | `nodejs`                           |
+| **Tags**     | `dev`, `ai`, `claude`, `anthropic` |
+
+### Cloudflared (`cloudflared`)
+
+Cloudflare Tunnel for securely exposing local services to the internet
+
+| Property      | Value                                     |
+| ------------- | ----------------------------------------- |
+| **Category**  | dev                                       |
+| **Conflicts** | `ngrok`                                   |
+| **Tags**      | `dev`, `tunneling`, `proxy`, `cloudflare` |
+
 ### Codex (`codex`)
 
 OpenAI Codex CLI for AI-powered code generation and assistance
@@ -492,6 +532,16 @@ Isolated Docker daemon inside container (portable, works in Codespaces)
 | **Conflicts** | `docker-sock`   |
 | **Tags**      | `dev`, `docker` |
 
+### Gemini CLI (`gemini-cli`)
+
+Google Gemini CLI for AI-powered development assistance
+
+| Property     | Value                           |
+| ------------ | ------------------------------- |
+| **Category** | dev                             |
+| **Requires** | `nodejs`                        |
+| **Tags**     | `dev`, `ai`, `gemini`, `google` |
+
 ### Git Helpers (`git-helpers`)
 
 Git LFS, GitHub CLI, GPG/SSH support for secure Git operations
@@ -501,6 +551,15 @@ Git LFS, GitHub CLI, GPG/SSH support for secure Git operations
 | **Category** | dev                                    |
 | **Tags**     | `dev`, `git`, `security`, `ssh`, `gpg` |
 
+### gRPC Tools (`grpc-tools`)
+
+Protocol Buffers compiler, Buf, and grpcurl for gRPC development
+
+| Property     | Value                            |
+| ------------ | -------------------------------- |
+| **Category** | dev                              |
+| **Tags**     | `dev`, `grpc`, `protobuf`, `api` |
+
 ### Just Task Runner (`just`)
 
 Fast, simple command runner (Rust-based alternative to Make)
@@ -510,6 +569,29 @@ Fast, simple command runner (Rust-based alternative to Make)
 | **Category** | dev                          |
 | **Tags**     | `dev`, `automation`, `tasks` |
 
+### Keycloak (`keycloak`)
+
+Open-source identity and access management (OIDC/OAuth2)
+
+| Property     | Value                                       |
+| ------------ | ------------------------------------------- |
+| **Category** | dev                                         |
+| **Supports** | compose                                     |
+| **Requires** | `postgres`                                  |
+| **Tags**     | `dev`, `auth`, `oidc`, `oauth2`, `identity` |
+| **Ports**    | [object Object]                             |
+
+### Mailpit (`mailpit`)
+
+Email testing tool with web UI and SMTP server
+
+| Property     | Value                             |
+| ------------ | --------------------------------- |
+| **Category** | dev                               |
+| **Supports** | compose                           |
+| **Tags**     | `dev`, `email`, `smtp`, `testing` |
+| **Ports**    | [object Object], [object Object]  |
+
 ### Modern CLI Tools (`modern-cli-tools`)
 
 jq, yq, ripgrep, fd, bat - Essential modern command-line tools
@@ -523,11 +605,12 @@ jq, yq, ripgrep, fd, bat - Essential modern command-line tools
 
 Secure tunneling for webhook testing and external access
 
-| Property     | Value                          |
-| ------------ | ------------------------------ |
-| **Category** | dev                            |
-| **Tags**     | `dev`, `tunneling`, `webhooks` |
-| **Ports**    | 4040                           |
+| Property      | Value                          |
+| ------------- | ------------------------------ |
+| **Category**  | dev                            |
+| **Conflicts** | `cloudflared`                  |
+| **Tags**      | `dev`, `tunneling`, `webhooks` |
+| **Ports**     | 4040                           |
 
 ### OpenAPI Tools (`openapi-tools`)
 
@@ -539,6 +622,16 @@ OpenAPI/Swagger tooling for API development and documentation
 | **Suggests** | `nodejs`                                            |
 | **Tags**     | `dev`, `openapi`, `swagger`, `api`, `documentation` |
 
+### opencode (`opencode`)
+
+opencode AI coding agent for terminal-based development assistance
+
+| Property     | Value                   |
+| ------------ | ----------------------- |
+| **Category** | dev                     |
+| **Requires** | `nodejs`                |
+| **Tags**     | `dev`, `ai`, `opencode` |
+
 ### Playwright (`playwright`)
 
 Browser automation and testing framework
@@ -571,6 +664,16 @@ Live update and orchestration for Kubernetes development
 | **Tags**      | `dev`, `kubernetes`, `k8s`, `development`, `live-reload` |
 | **Ports**     | 10350                                                    |
 
+### Windsurf CLI (`windsurf-cli`)
+
+Codeium Windsurf CLI for AI-powered development assistance
+
+| Property     | Value                              |
+| ------------ | ---------------------------------- |
+| **Category** | dev                                |
+| **Requires** | `nodejs`                           |
+| **Tags**     | `dev`, `ai`, `windsurf`, `codeium` |
+
 ## Dependency Model
 
 ### Dependency Types

package/docs/presets-architecture.md

@@ -213,7 +213,7 @@ async function applyGlueConfig(glueConfig: PresetGlueConfig, envPath: string, ou
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "generatedAt": "2026-02-08T10:00:00Z",
     "baseTemplate": "compose",
 

package/docs/presets.md

@@ -261,7 +261,7 @@ Presets are tracked in `superposition.json`:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "baseTemplate": "compose",
     "preset": "web-api",
     "presetChoices": {

package/docs/publishing.md

@@ -5,9 +5,9 @@ This guide explains how to publish `container-superposition` to npm, making it a
 ## Package Overview
 
 **Package Name:** `container-superposition`  
-**Current Version:** `0.1.0`  
-**Size:** ~327 KB (compressed), 1.2 MB (unpacked)  
-**Files:** 327 files  
+**Current Version:** See `package.json`  
+**Size:** Varies by release (use `npm pack --dry-run`)  
+**Files:** Varies by release  
 **Entry Point:** `dist/scripts/init.js`
 
 **Available Commands:**
@@ -23,33 +23,45 @@ Publishing is **automated via GitHub Actions** when a new release is created.
 
 ### Automated Publishing (Recommended)
 
-1. **Update version in package.json:**
+1. **Update CHANGELOG.md** with release notes
 
-    ```bash
-    npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
-    npm version minor   # 0.1.0 → 0.2.0 (new features)
-    npm version major   # 0.1.0 → 1.0.0 (breaking changes)
-    ```
-
-2. **Update CHANGELOG.md** with release notes
-
-3. **Commit and push changes:**
+2. **Commit and push changes:**
 
     ```bash
-    git add package.json package-lock.json CHANGELOG.md
-    git commit -m "chore: bump version to X.Y.Z"
+    git add CHANGELOG.md
+    git commit -m "docs: update changelog for X.Y.Z"
     git push
     ```
 
-4. **Create GitHub Release:**
+3. **Create GitHub Release:**
     - Go to https://github.com/veggerby/container-superposition/releases/new
     - Tag: `vX.Y.Z` (e.g., `v0.1.1`)
-    - Title: `vX.Y.Z`
-    - Description: Copy from CHANGELOG.md
+    - Title: `Version X.Y.Z` (e.g., `Version 0.1.1`)
+    - Description: Copy the full release section from `CHANGELOG.md`, including the header line
+        - Example (include all subsections like `### Added`, `### Changed`, `### Fixed`):
+
+            ```markdown
+            ## [0.1.5] - 2026-03-01
+
+            ### Added
+
+            - **Foo overlay** — Adds Foo service for local dev
+            - **Bar CLI helpers** — Convenience scripts for common tasks
+
+            ### Changed
+
+            - **Template defaults** — Compose stack now includes a healthcheck by default
+
+            ### Fixed
+
+            - **Port offsets** — Resolved collisions for default web ports
+            ```
+
     - Click "Publish release"
 
-5. **GitHub Actions will automatically:**
+4. **GitHub Actions will automatically:**
     - ✅ Validate semantic version format
+    - ✅ Set `package.json` version from the tag
     - ✅ Install dependencies
     - ✅ Run tests
     - ✅ Build TypeScript
@@ -181,12 +193,13 @@ npm pack --dry-run
 - Compressed: ~122 KB
 - Unpacked: ~462 KB
 
-### 4. Update Version (if needed)
+### 4. Version Source (Automated)
 
-```bash
-# First release (already at 0.1.0)
-# For subsequent releases:
+For GitHub Releases, the publish workflow sets `package.json` version from the tag (`vX.Y.Z`). You should not run `npm version` locally for automated releases.
+
+If you are doing a manual publish (outside GitHub Releases), you can use:
 
+```bash
 # Patch release (bug fixes): 0.1.0 → 0.1.1
 npm version patch
 

package/docs/security.md

@@ -0,0 +1,43 @@
+# Security Considerations
+
+Container Superposition is designed for **development environments only**. Use these guardrails to avoid common pitfalls.
+
+## Docker Socket Access (`docker-sock`)
+
+**Risk**: Mounting `/var/run/docker.sock` gives the container full control of the host Docker daemon.
+
+Recommended usage:
+
+- Use `docker-sock` only on local machines with trusted code.
+- Prefer `docker-in-docker` for isolation or cloud IDEs.
+- Never use `docker-sock` in multi-tenant or production environments.
+
+## Database Defaults
+
+Database overlays ship with **development-only defaults** (e.g., `postgres/postgres`).
+
+Recommended usage:
+
+- Rotate credentials for any shared or networked environment.
+- Keep services on private networks.
+- Put real credentials in `.env` (gitignored), not `.env.example`.
+
+## Environment Files
+
+- `.env.example` is committed and contains templates.
+- `.env` is gitignored and contains real values.
+
+Recommended usage:
+
+- Copy `.env.example` to `.env` and customize.
+- Keep `.env` out of version control.
+- Use placeholder values in `.env.example`.
+
+## General Principles
+
+- Treat generated configs as dev-only.
+- Avoid exposing devcontainer ports publicly.
+- Keep base images and overlays updated.
+- Audit dependencies in your devcontainer.
+
+For overlay-specific notes, see each overlay README (for example, `overlays/docker-sock/README.md`).

package/docs/specs/001-verbose-plan-graph/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Verbose Plan Graph
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-10
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation completed on 2026-03-10 after the manifest-driven scope update.
+- No checklist failures found during the validation pass for the revised scope.
+- Spec is ready for `/speckit.plan` after review of the updated scope.