container-superposition 0.1.4 → 0.1.6

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` |
+
+### Pandoc PDF (`pandoc`)
+
+Pandoc with XeLaTeX, Mermaid diagrams, and quality fonts for Markdown-to-PDF export
+
+| Property     | Value                                                          |
+| ------------ | -------------------------------------------------------------- |
+| **Category** | dev                                                            |
+| **Suggests** | `nodejs`                                                       |
+| **Tags**     | `dev`, `pandoc`, `pdf`, `latex`, `markdown`, `docs`, `mermaid` |
+
+### 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
@@ -502,6 +542,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
@@ -582,6 +632,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
@@ -614,6 +674,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.

package/docs/specs/001-verbose-plan-graph/contracts/plan-verbose-output.md

@@ -0,0 +1,96 @@
+# Contract: Plan Verbose Output
+
+## Scope
+
+This contract defines the user-visible behavior of the `plan` command when `--verbose` is requested. It covers terminal output and structured JSON output for the normal planning path.
+
+## Command Surface
+
+### New Option
+
+- `--verbose`: Include dependency-resolution narration that explains why each overlay appears in the final plan.
+
+### Existing Manifest Input
+
+- Manifest-driven planning must support the existing manifest workflow and apply `--verbose` when overlays are loaded from `superposition.json`.
+
+### Compatibility Rules
+
+- `plan` without `--verbose` keeps the existing concise output contract.
+- `plan --json --verbose` returns the standard plan data plus structured explanation data.
+- `plan` run from an existing manifest with `--verbose` uses the same explanation structure as overlay-list-driven planning.
+- `plan --diff` remains a separate mode; verbose planning must not silently change diff semantics.
+
+## Text Output Contract
+
+When `--verbose` is present and the command completes normal planning:
+
+1. The standard summary remains visible:
+    - stack
+    - overlays selected
+    - auto-added dependencies
+    - conflicts, if any
+    - port mappings
+    - files to create/modify
+2. A dedicated explanation section appears after the overlay summary.
+3. The explanation section must:
+    - identify each included overlay exactly once
+    - state whether it was selected directly or added automatically
+    - treat manifest-defined overlays as the explicit root configuration when planning is loaded from a manifest
+    - name the parent overlay or overlays that required it
+    - show transitive chains in request-to-dependency order
+    - call out failure boundaries when conflicts or invalid selections prevent successful completion
+
+### Example Shape
+
+```text
+Dependency Resolution:
+  nodejs
+    selected directly by the user
+  grafana
+    selected directly by the user
+  prometheus
+    required by grafana
+    path: grafana -> prometheus
+```
+
+The wording may vary, but the content requirements above are mandatory.
+
+## JSON Output Contract
+
+When `--json --verbose` is present, the result must include:
+
+- the existing standard plan fields
+- an additional explanation payload that:
+    - records whether the plan input came from explicit overlays or a manifest
+    - lists each included overlay once
+    - distinguishes direct selections from dependency-driven inclusions
+    - records one or more parent reasons for dependencies with shared ancestry
+    - includes ordered dependency paths for transitive inclusions
+    - optionally records failure context when planning cannot complete normally
+
+### Minimum Field Expectations
+
+The verbose payload must support these questions without requiring text parsing:
+
+- Was this overlay selected by the user or added automatically?
+- Which overlay or overlays caused this inclusion?
+- What dependency path led to this overlay?
+- Did resolution stop or skip anything, and why?
+
+## Error and Failure Contract
+
+- Unknown overlay IDs remain hard failures.
+- Missing or invalid manifests remain hard failures for manifest-driven planning.
+- Conflicts remain visible in both concise and verbose modes.
+- Verbose mode adds context about the dependency path and failure boundary; it does not suppress or soften existing error behavior.
+
+## Documentation Contract
+
+The command reference and examples must show:
+
+- one direct-selection example
+- one manifest-driven verbose example
+- one auto-added dependency example
+- one transitive or multi-parent explanation example
+- one note confirming that default `plan` output stays concise without `--verbose`