container-superposition 0.1.4 → 0.1.5

package/docs/overlays.md

@@ -442,6 +442,36 @@ 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
@@ -502,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
@@ -582,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
@@ -614,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.

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`

package/docs/specs/001-verbose-plan-graph/data-model.md

@@ -0,0 +1,111 @@
+# Data Model: Verbose Plan Graph
+
+## Entity: PlanRequest
+
+**Purpose**: Describes a single `plan` invocation and the presentation options that shape the response.
+
+**Fields**:
+
+- `stack`: requested base template type
+- `selectedOverlayIds`: user-provided overlay IDs after trimming and de-duplication
+- `manifestPath`: optional path to an existing `superposition.json` manifest
+- `manifestOverlayIds`: overlays loaded from a manifest when manifest-driven planning is used
+- `portOffset`: optional numeric port offset
+- `jsonRequested`: whether structured output is requested
+- `diffRequested`: whether diff mode is requested
+- `verboseRequested`: whether dependency narration is requested
+- `outputPath`: optional comparison target for diff mode
+
+**Validation rules**:
+
+- `stack` must be present and valid for the command
+- `selectedOverlayIds` must contain only known overlay IDs
+- duplicate overlay IDs are normalized before planning
+- manifest-driven requests must resolve to a valid manifest before explanation data is generated
+- `verboseRequested` must not change resolution behavior, only presentation and additional metadata
+
+## Entity: IncludedOverlay
+
+**Purpose**: Represents one overlay that appears in the resolved final plan.
+
+**Fields**:
+
+- `id`: stable overlay identifier
+- `displayName`: human-readable overlay name if available
+- `selectionKind`: `direct` or `dependency` based on how the overlay first entered the resolved set
+- `selectionSource`: `command-line`, `manifest`, or `dependency`
+- `reasons`: one or more inclusion reasons attached to this overlay
+- `dependencyPaths`: one or more ordered paths from a direct selection to this overlay
+- `compatibleWithStack`: whether the overlay remains in the final stack-specific plan
+
+**Validation rules**:
+
+- each included overlay appears only once in the final resolved set
+- `reasons` must contain at least one entry
+- `dependencyPaths` may have multiple entries when multiple parents lead to the same overlay
+- if `selectionKind` is `direct`, at least one reason must identify the user request as the source
+- if `selectionSource` is `manifest`, at least one reason must identify the manifest-defined root set as the source
+
+## Entity: InclusionReason
+
+**Purpose**: Explains why a single overlay was kept in the plan.
+
+**Fields**:
+
+- `kind`: `selected`, `required`, `transitive`, or `skipped`
+- `origin`: `command-line` or `manifest`
+- `sourceOverlayId`: the overlay that directly caused this reason, if applicable
+- `rootOverlayId`: the original user-selected overlay at the start of the path
+- `message`: user-facing explanation text
+- `depth`: number of dependency edges between the root selection and the included overlay
+
+**Validation rules**:
+
+- direct selections use `kind: selected` and `depth: 0`
+- manifest-defined root overlays also use `kind: selected` and `depth: 0`
+- dependency-driven inclusions must include `sourceOverlayId`
+- transitive reasons must include both `sourceOverlayId` and `rootOverlayId`
+- failure or skip reasons must remain attached to the affected overlay or attempted overlay so users can identify the boundary condition
+
+## Entity: DependencyPath
+
+**Purpose**: Captures the ordered chain from a requested overlay to an included dependency.
+
+**Fields**:
+
+- `rootOverlayId`: directly selected starting overlay
+- `segments`: ordered overlay IDs showing the path from root to final overlay
+- `finalOverlayId`: included overlay reached by the path
+
+**Validation rules**:
+
+- `segments[0]` must match `rootOverlayId`
+- `segments[segments.length - 1]` must match `finalOverlayId`
+- repeated paths for the same overlay should be de-duplicated before output
+
+## Entity: VerbosePlanOutput
+
+**Purpose**: Extends the standard plan result with explanation data when verbose mode is requested.
+
+**Fields**:
+
+- `standardPlan`: the existing plan summary data
+- `includedOverlays`: ordered list of `IncludedOverlay` records for human and JSON rendering
+- `resolutionSummary`: concise summary of how many overlays were selected directly vs added automatically
+- `failureContext`: optional description of the point where planning stopped or skipped overlays
+- `inputMode`: `overlay-list` or `manifest`
+
+**Relationships**:
+
+- one `PlanRequest` produces one `VerbosePlanOutput`
+- one `PlanRequest` may be sourced from explicit overlay flags or a manifest
+- one `VerbosePlanOutput` contains many `IncludedOverlay` records
+- one `IncludedOverlay` contains many `InclusionReason` records and zero or more `DependencyPath` records
+
+## State Notes
+
+- Resolution begins with the user-selected overlays.
+- Resolution begins with either the user-selected overlays or the manifest-defined overlay roots.
+- Dependencies are added recursively as required relationships are traversed.
+- Stack compatibility filtering may remove overlays from the final renderable set after dependency discovery.
+- Conflict detection runs against the resolved compatible set and may attach failure context to the verbose result.

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

@@ -0,0 +1,127 @@
+# Implementation Plan: Verbose Plan Graph
+
+**Branch**: `001-verbose-plan-graph` | **Date**: 2026-03-10 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/docs/specs/001-verbose-plan-graph/spec.md`
+
+## Summary
+
+Extend the `plan` command so `--verbose` explains dependency resolution for both direct overlay selection and manifest-driven planning from an existing `superposition.json`. The design must keep one shared resolution and explanation model so text output, JSON output, and manifest-based workflows stay consistent.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.3.3 on Node.js 20+  
+**Primary Dependencies**: Commander, chalk, boxen, js-yaml, ora, Inquirer  
+**Storage**: Filesystem-based overlay manifests, project `superposition.json` manifests, templates, and generated devcontainer artifacts  
+**Testing**: Vitest unit and command tests, shell-based smoke tests, TypeScript compile checks  
+**Target Platform**: Node.js CLI on Linux, macOS, and Windows developer environments  
+**Project Type**: CLI scaffolding tool  
+**Performance Goals**: Preserve the current fast interactive feel of the `plan` command for typical overlay selections and avoid introducing noticeable delay when verbose explanation is enabled  
+**Constraints**: Preserve current concise output unless `--verbose` is requested; preserve source/dist path compatibility patterns; keep manifest-driven and overlay-list-driven planning aligned to one resolved overlay set; keep JSON and text views consistent  
+**Scale/Scope**: Single command enhancement affecting `scripts/init.ts`, `tool/commands/plan.ts`, command tests, user-facing docs, and manifest-driven planning behavior
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design and before implementation._
+
+- [x] Spec exists at `docs/specs/001-verbose-plan-graph/spec.md`.
+- [x] Spec is committed and reviewed before implementation tasks or code begin.
+- [x] Plan scope, compatibility impact, and complexity notes match the approved spec.
+- [x] Verification scope covers tests, smoke checks, and documentation updates needed for the change.
+- [x] User-visible changes include documentation updates and an `[Unreleased]` `CHANGELOG.md` entry.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+docs/specs/001-verbose-plan-graph/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── plan-verbose-output.md
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+scripts/
+└── init.ts
+
+tool/
+├── commands/
+│   └── plan.ts
+├── __tests__/
+│   └── commands.test.ts
+├── schema/
+└── utils/
+
+docs/
+├── discovery-commands.md
+└── specs/
+
+README.md
+CHANGELOG.md
+```
+
+**Structure Decision**: Keep the existing CLI structure centered on `scripts/init.ts` for command options and manifest-loading hooks, and `tool/commands/plan.ts` for shared planning logic. Keep verification concentrated in `tool/__tests__/commands.test.ts`, with documentation updates in `README.md` and `docs/discovery-commands.md`.
+
+## Phase 0: Research
+
+### Research Goals
+
+- Confirm the simplest way to reuse the verbose explanation model for manifest-driven planning.
+- Decide how manifest-loaded overlays should appear in explanation data relative to directly requested overlays.
+- Confirm failure behavior for missing or invalid manifests in verbose mode.
+
+### Research Outputs
+
+- [research.md](research.md)
+
+## Phase 1: Design
+
+### Data Model
+
+- [data-model.md](data-model.md)
+
+### Contracts
+
+- [plan-verbose-output.md](contracts/plan-verbose-output.md)
+
+### Quickstart
+
+- [quickstart.md](quickstart.md)
+
+## Implementation Approach
+
+1. Extend `plan` input handling so it can build the same verbose explanation model whether overlays come from explicit flags or an existing manifest.
+2. Reuse one dependency-resolution and explanation path inside `tool/commands/plan.ts` for concise, verbose, JSON, and manifest-driven planning.
+3. Define manifest-aware explanation semantics so manifest-defined overlays remain distinguishable from auto-added dependencies without inventing a separate output format.
+4. Add regression tests for manifest-driven verbose text output, verbose JSON output, and manifest failure paths.
+5. Update README, discovery docs, quickstart guidance, and changelog entries to document manifest-driven verbose planning.
+
+## Verification Strategy
+
+- Add or update command tests in `tool/__tests__/commands.test.ts` for:
+    - verbose text output from direct overlay selection
+    - verbose text output from an existing manifest
+    - verbose JSON output from an existing manifest
+    - manifest failure behavior when the manifest is missing, invalid, or contains invalid overlays
+    - non-verbose output remaining unchanged
+- Run `npm test` for automated coverage.
+- Run `npm run lint` to verify TypeScript and formatting constraints.
+- Perform targeted manual validation using the commands documented in `quickstart.md`, including manifest-driven scenarios.
+
+## Post-Design Constitution Check
+
+- [x] Design still preserves spec-first workflow and traces directly to the approved spec.
+- [x] The planned change preserves overlay contract integrity by extending the existing planning model rather than creating a parallel manifest-only explanation path.
+- [x] Verification remains proportional to risk: command tests plus documentation updates are planned before merge.
+- [x] Documentation synchronization is explicitly included: `README.md`, `docs/discovery-commands.md`, `quickstart.md`, and `CHANGELOG.md`.
+- [x] Simplicity and compatibility remain intact: verbose mode stays opt-in and manifest-driven planning uses the same reasoning model as direct selection.
+
+## Complexity Tracking
+
+No constitution violations require a design exception.