container-superposition 0.1.7 → 0.1.9

package/docs/specs/003-mkdocs2-overlay/spec.md

@@ -1,18 +1,11 @@
 # Feature Specification: MkDocs 2.x Overlay
 
-**Feature Branch**: `copilot/add-mkdocs2-overlay`
+**Spec ID**: `003-mkdocs2-overlay`
 **Created**: 2026-03-16
 **Status**: Final
 **Input**: Add a new `mkdocs2` overlay that installs MkDocs 2.x with the Material theme via direct `pip` install, keeping the existing `mkdocs` (MkDocs 1.x) overlay untouched for backward compatibility.
 
-## Review & Approval _(mandatory before implementation)_
-
-- **Spec Path**: `docs/specs/003-mkdocs2-overlay/spec.md`
-- **Commit Status**: Committed
-- **Review Status**: Approved
-- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
-
-## User Scenarios & Testing _(mandatory)_
+## User Scenarios & Testing
 
 ### User Story 1 - Use MkDocs 2.x in a devcontainer (Priority: P1)
 

package/docs/specs/004-doctor-fix/spec.md

@@ -1,17 +1,10 @@
 # Feature Specification: `doctor --fix` — Interactive Auto-Repair
 
-**Feature Branch**: `004-doctor-fix`
+**Spec ID**: `004-doctor-fix`
 **Created**: 2026-03-19
 **Status**: Final
 **Input**: GitHub issue: Implement `doctor --fix` — interactive auto-repair for environment issues
 
-## Review & Approval _(mandatory before implementation)_
-
-- **Spec Path**: `docs/specs/004-doctor-fix/spec.md`
-- **Commit Status**: Committed
-- **Review Status**: APPROVED
-- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
-
 ## Summary
 
 The `doctor` command validates the environment. The `--fix` path was a placeholder. This spec

package/docs/specs/005-cuda-overlay/spec.md

@@ -1,18 +1,11 @@
 # Feature Specification: CUDA (NVIDIA GPU) Overlay
 
-**Feature Branch**: `copilot/add-cuda-overlay-for-gpu`
+**Spec ID**: `005-cuda-overlay`
 **Created**: 2026-03-22
 **Status**: Final
 **Input**: Add a `cuda` overlay to enable NVIDIA GPU-accelerated workloads inside a dev container.
 
-## Review & Approval _(mandatory before implementation)_
-
-- **Spec Path**: `docs/specs/005-cuda-overlay/spec.md`
-- **Commit Status**: Committed
-- **Review Status**: Approved
-- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
-
-## User Scenarios & Testing _(mandatory)_
+## User Scenarios & Testing
 
 ### User Story 1 - GPU passthrough for ML/inference workloads (Priority: P1)
 

package/docs/specs/006-rocm-overlay/spec.md

@@ -1,24 +1,17 @@
 # Feature Specification: ROCm (AMD GPU) Overlay
 
-**Feature Branch**: `copilot/add-rocm-overlay`
+**Spec ID**: `006-rocm-overlay`
 **Created**: 2026-03-22
-**Status**: Accepted
+**Status**: Final
 **Input**: Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container.
 
-## Review & Approval _(mandatory before implementation)_
-
-- **Spec Path**: `docs/specs/006-rocm-overlay/spec.md`
-- **Commit Status**: Committed
-- **Review Status**: Approved
-- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
-
 ## Overview
 
 Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container using the ROCm open software platform.
 
 > **Note:** ROCm-in-container is a supported but more fragile path than CUDA. It depends heavily on the host kernel version, AMD driver stack, specific device support, and container runtime configuration. Treat this as a separate supported profile — not a drop-in equivalent of CUDA.
 
-## User Scenarios & Testing _(mandatory)_
+## User Scenarios & Testing
 
 ### User Story 1 - AMD GPU passthrough for ML/inference workloads (Priority: P1)
 

package/docs/specs/007-target-aware-generation/spec.md

@@ -0,0 +1,119 @@
+# Feature Specification: Target-Aware Generation
+
+**Spec ID**: `007-target-aware-generation`
+**Created**: 2026-03-23
+**Status**: Final
+**Input**: Issue [feat] Target-aware generation — produce workspace artifacts and guidance for codespaces, gitpod, and devpod
+
+## User Scenarios & Testing
+
+### User Story 1 — Generate codespaces artifacts (Priority: P1)
+
+A user generates with `--target codespaces` and expects to receive Codespaces-specific files and
+guidance alongside the normal devcontainer output.
+
+**Acceptance:**
+
+1. `--target codespaces` → `devcontainer.json` extended with `hostRequirements`, `CODESPACES.md` written to `.devcontainer/`.
+2. `--target local` or no `--target` → no `CODESPACES.md`, no `hostRequirements` in devcontainer.
+
+### User Story 2 — Generate gitpod artifacts (Priority: P1)
+
+A user generates with `--target gitpod` and expects a `.gitpod.yml` in the project root and
+setup guidance inside `.devcontainer/`.
+
+**Acceptance:**
+
+1. `--target gitpod` → `.gitpod.yml` at project root with tasks and port exposures from selected overlays; `GITPOD.md` written to `.devcontainer/`.
+2. `--target local` → no `.gitpod.yml`, no `GITPOD.md`.
+
+### User Story 3 — Generate devpod artifacts (Priority: P1)
+
+A user generates with `--target devpod` and expects a `devpod.yaml` at the project root and
+setup guidance inside `.devcontainer/`.
+
+**Acceptance:**
+
+1. `--target devpod` → `devpod.yaml` at project root; `DEVPOD.md` written to `.devcontainer/`.
+2. `--target local` → no `devpod.yaml`, no `DEVPOD.md`.
+
+### User Story 4 — Local generation unchanged (Priority: P1)
+
+When a user generates without specifying a target, or with `--target local`, the output must
+not contain any non-local artifacts.
+
+**Acceptance:**
+
+1. No `--target` flag → output identical to current behavior; no new files written.
+2. `--target local` (explicit) → same output as omitting `--target`.
+
+### User Story 5 — Regeneration from manifest with target (Priority: P2)
+
+A user regenerates from an existing `superposition.json` that includes `"target": "gitpod"` and
+expects the same Gitpod-specific artifacts without being prompted again.
+
+**Acceptance:**
+
+1. Manifest with `target: gitpod` → regen produces `.gitpod.yml` and `GITPOD.md`.
+2. Manifest with no `target` or `target: local` → regen produces no target-specific artifacts.
+
+### User Story 6 — Target switching cleans up stale artifacts (Priority: P2)
+
+A user regenerates with a different `--target` value and expects the previous target's
+project-root artifacts to be removed.
+
+**Acceptance:**
+
+1. Previous run was `--target gitpod` (`.gitpod.yml` exists); regeneration with `--target codespaces` → `.gitpod.yml` removed, `CODESPACES.md` written.
+2. Previous run was `--target devpod`; regeneration with `--target local` → `devpod.yaml` removed.
+
+## Technical Design
+
+### `TargetRule` interface
+
+A `TargetRule` encapsulates everything about generating artifacts for one deployment target:
+
+```typescript
+interface TargetRule {
+    target: DeploymentTarget;
+    /** Extra fields merged into devcontainer.json */
+    devcontainerPatch(context: TargetRuleContext): Partial<DevContainer>;
+    /** Files to write; keys are relative to outputPath, '../<name>' writes to project root */
+    generateFiles(context: TargetRuleContext): Map<string, string>;
+    /** All relative paths owned by this rule (for stale-cleanup on target switch) */
+    ownedFiles(): string[];
+}
+```
+
+### Per-target rules
+
+| Target       | devcontainer.json change | Files in `.devcontainer/` | Files at project root |
+| ------------ | ------------------------ | ------------------------- | --------------------- |
+| `local`      | none                     | none                      | none                  |
+| `codespaces` | `hostRequirements`       | `CODESPACES.md`           | none                  |
+| `gitpod`     | none                     | `GITPOD.md`               | `.gitpod.yml`         |
+| `devpod`     | none                     | `DEVPOD.md`               | `devpod.yaml`         |
+
+### `SuperpositionManifest` update
+
+Add `target?: DeploymentTarget` so regeneration reproduces the correct artifacts without
+re-prompting.
+
+### Stale-artifact cleanup
+
+On each generation, before writing new target artifacts:
+
+1. Read existing `superposition.json` from `outputPath` (if it exists).
+2. If `manifest.target !== answers.target`, identify previous target's owned project-root
+   files (e.g., `.gitpod.yml`) and remove them from the project root.
+
+The `.devcontainer/`-local files are already handled by `cleanupStaleFiles` via `FileRegistry`.
+
+## Functional Requirements (from issue)
+
+- **FR-001**: Target is a real generation input that changes produced artifacts.
+- **FR-002**: `codespaces`, `gitpod`, `devpod` produce target-specific workspace artifacts.
+- **FR-003**: `local` (explicit or default) produces no additional artifacts.
+- **FR-009**: Regeneration from manifest reproduces target-aware output automatically.
+- **FR-010**: Target switch between runs removes stale artifacts from the previous target.
+- **FR-011**: Backward compatible — manifests without `target` or with `target: local` unchanged.

package/docs/specs/008-project-file-canonical/spec.md

@@ -0,0 +1,82 @@
+# Feature Specification: Make superposition.yml the Canonical Input
+
+**Spec ID**: `008-project-file-canonical`
+**Created**: 2026-03-26
+**Author**: PM Agent
+**Status**: Approved
+**Input**: GitHub issue #134 — make `superposition.yml` the required canonical input for all generation flows
+
+## Overview
+
+Make `superposition.yml` (the project config file) the required, canonical input for all
+generation and regeneration flows. `superposition.json` (the manifest) becomes an output-only
+artifact — a generated receipt, not an input source.
+
+## Motivation
+
+Three entry points currently disagree on which file is authoritative, creating user confusion
+and dead code paths. The newest code path (`generate`) already writes `superposition.yml`
+first. This spec promotes that pattern to all entry points.
+
+## Behavioral Changes
+
+### `init` — Always writes `superposition.yml`
+
+- Remove `--project-file` flag; writing the project config is now the default.
+- Add `--no-scaffold` flag to skip generating `.devcontainer/` (for project-file-only runs).
+- Scaffold (`.devcontainer/` generation) remains the default for backward compatibility.
+- The project file is written before scaffolding; a scaffold failure does not lose the config.
+
+### `regen` — Reads `superposition.yml` only
+
+- Default input: the project config file auto-discovered in the repository root.
+- `--from-manifest <path>` is retained as a **deprecated hidden flag** that emits a warning
+  pointing toward `cs migrate`. Existing CI scripts that rely on it will still work but
+  receive a deprecation notice.
+- If no project file exists and `superposition.json` is present: error with actionable
+  migration guidance: `Run 'cs migrate' to create a project file from your existing manifest.`
+- If neither file exists: error with creation guidance.
+
+### `superposition.json` — Output only
+
+- Still written by `composeDevContainer` / `generateManifestOnly` as before.
+- No longer read as a generation input in the standard flow.
+- Still read by `doctor` for diagnostics and drift detection.
+
+## New Commands
+
+### `cs migrate`
+
+One-time migration from manifest-only repositories:
+
+1. Discovers or accepts `--from-manifest <path>` to locate `superposition.json`.
+2. Loads and validates the manifest (with auto-migration for old versions).
+3. Converts manifest to `ProjectConfigSelection` via the existing
+   `buildAnswersFromManifest → mergeAnswers → buildProjectConfigSelectionFromAnswers` pipeline.
+4. Discovers the output path for the project file (uses existing file if present, otherwise
+   defaults to `.superposition.yml`); `--force` to overwrite.
+5. Writes the project config YAML.
+6. Prints a success message with next-step guidance (`regen` to regenerate).
+
+## `doctor` Drift Detection
+
+Once the project file is canonical, `doctor` can compare the two files:
+
+- Load project file overlays (via `loadProjectConfig`).
+- Load last-generated manifest overlays (via existing manifest loading).
+- Report a new `project-file-drift` finding when the overlay sets differ.
+- Suggest `regen` to reconcile.
+
+## Migration Considerations
+
+| Repo state                    | Impact                            | Action                           |
+| ----------------------------- | --------------------------------- | -------------------------------- |
+| Has `superposition.yml` only  | None — already correct            | —                                |
+| Has `superposition.json` only | `regen` errors                    | Run `cs migrate` once            |
+| Has both (consistent)         | None — regen prefers project file | —                                |
+| CI using `--from-manifest`    | Warning on each run               | Switch to `cs migrate` + `regen` |
+
+## Notes
+
+Implementation proceeds with this spec committed. No further approval required for the
+behavioral changes listed above.

package/docs/specs/009-project-env/spec.md

@@ -0,0 +1,140 @@
+# Feature Specification: Unified Project-Level Environment Variables
+
+**Spec ID**: `009-project-env`
+**Created**: 2026-03-29
+**Status**: Approved
+**Input**: User request
+
+## User Scenarios & Testing
+
+### User Story 1 — Define environment variables once for plain stack (Priority: P1)
+
+A developer adds an `env:` block to `superposition.yml` on a `plain` stack and expects the
+variables to appear in `devcontainer.json → remoteEnv` after regeneration.
+
+**Why this priority**: The most common use case is a plain-stack project needing a handful of
+environment variables visible inside the devcontainer without manually editing JSON files.
+
+**Independent Test**: Create a `superposition.yml` with `stack: plain` and `env: {APP_NAME: my-app}`,
+run `regen`, and confirm that `devcontainer.json` contains `"remoteEnv": {"APP_NAME": "my-app"}`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `superposition.yml` has `env: {APP_NAME: my-app}`, **When** generation runs with `stack: plain`, **Then** `devcontainer.json` includes `remoteEnv.APP_NAME: my-app`.
+2. **Given** `env:` uses the long form (`{value: "foo", target: auto}` — an object with a required `value` string and optional `target` routing hint), **When** generation runs with `stack: plain`, **Then** the variable is written to `remoteEnv` identical to the string shorthand.
+
+---
+
+### User Story 2 — Define environment variables once for compose stack (Priority: P1)
+
+A developer adds an `env:` block to `superposition.yml` on a `compose` stack and expects the
+variables to appear in `docker-compose.yml → services.devcontainer.environment` after regeneration.
+
+**Why this priority**: Compose-stack users currently must split env configuration across
+`customizations.devcontainerPatch.remoteEnv` and `customizations.dockerComposePatch`, which is
+error-prone and hard to discover.
+
+**Independent Test**: Create a `superposition.yml` with `stack: compose` and
+`env: {DB_HOST: postgres}`, run `regen`, and confirm the variable appears under
+`services.devcontainer.environment` in the generated `docker-compose.yml`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `superposition.yml` has `env: {DB_HOST: postgres}` on a compose stack, **When** generation runs, **Then** `docker-compose.yml` contains `services.devcontainer.environment.DB_HOST: postgres`.
+2. **Given** `target: composeEnv` is specified, **When** generation runs with `stack: plain`, **Then** generation errors with a clear message about compose-only targets.
+
+---
+
+### User Story 3 — Explicit target overrides auto-routing (Priority: P2)
+
+A developer uses `target: remoteEnv` on a compose-stack project to force a variable into
+`devcontainer.json` instead of `docker-compose.yml`.
+
+**Why this priority**: Power users occasionally need fine-grained control over where a variable
+lands, especially for VS Code-specific settings that must be in `remoteEnv`.
+
+**Independent Test**: Set `target: remoteEnv` on a variable in a compose-stack project, run
+`regen`, and confirm the variable is in `devcontainer.json → remoteEnv` (not in
+`docker-compose.yml → services.devcontainer.environment`).
+
+**Acceptance Scenarios**:
+
+1. **Given** `{value: "bar", target: remoteEnv}` in `env:` on a compose stack, **When** generation runs, **Then** the variable is written to `devcontainer.json → remoteEnv` only.
+
+---
+
+## Overview
+
+Add a first-class `env` field to `superposition.yml` so a project can define
+environment variables once and have them land in the correct generated output:
+
+- `remoteEnv` for `plain` stacks
+- `services.devcontainer.environment` in `docker-compose.yml` for `compose` stacks
+
+This removes the need to split simple container environment variables across
+`customizations.devcontainerPatch.remoteEnv` and
+`customizations.dockerComposePatch`.
+
+## Project File Shape
+
+```yaml
+env:
+    APP_NAME: my-app
+    API_BASE_URL:
+        value: ${API_BASE_URL:-http://localhost:3000}
+        target: auto
+```
+
+Rules:
+
+- `env` is a map keyed by variable name.
+- A value may be:
+    - a string shorthand, equivalent to `{ value: "<string>", target: auto }`
+    - an object with:
+        - `value: string` required
+        - `target: auto | remoteEnv | composeEnv` optional, default `auto`
+
+## Generation Behavior
+
+### `target: auto`
+
+- `plain` stack: write the variable to `devcontainer.json -> remoteEnv`
+- `compose` stack: write the variable to
+  `docker-compose.yml -> services.devcontainer.environment`
+
+### Explicit targets
+
+- `remoteEnv`: always write to `devcontainer.json -> remoteEnv`
+- `composeEnv`: write to `docker-compose.yml -> services.devcontainer.environment`
+  and error on non-compose stacks
+
+### Precedence
+
+- Project-level `env` is applied before `customizations.devcontainerPatch` and
+  `customizations.dockerComposePatch`.
+- Custom patch files remain the escape hatch and may override project-level env.
+
+## Root `.env` Expansion Bridge
+
+When a compose-targeted project env value references `${NAME}` or
+`${NAME:-default}`, generation should preserve that expression in
+`docker-compose.yml` and also mirror matching keys from the project root `.env`
+into `.devcontainer/.env`.
+
+This allows:
+
+1. the repository root `.env` to remain the human-edited source of truth
+2. Docker Compose to resolve variables from `.devcontainer/.env`
+3. generated `docker-compose.yml` to avoid embedding resolved secret values
+
+Bridge rules:
+
+- only referenced variable names are copied
+- existing unrelated entries in `.devcontainer/.env` are preserved
+- missing root variables are not invented; Docker Compose defaults still work
+
+## Non-Goals
+
+- No new syntax for targeting arbitrary non-devcontainer services
+- No replacement for advanced compose patches; those remain under
+  `customizations.dockerComposePatch`

package/docs/specs/010-compose-env-materialization/spec.md

@@ -0,0 +1,123 @@
+# Feature Specification: Compose Env Materialization and Env Template Naming
+
+**Spec ID**: `010-compose-env-materialization`
+**Created**: 2026-03-29
+**Status**: Approved
+**Input**: User request
+
+## User Scenarios & Testing
+
+### User Story 1 — Compose env values materialize into .devcontainer/.env (Priority: P1)
+
+A developer sets concrete env values in `superposition.yml` on a `compose` stack and expects
+them to be written to `.devcontainer/.env` (not embedded in `docker-compose.yml`) so that
+secrets are not committed to source control inside generated YAML.
+
+**Why this priority**: Embedding resolved values directly in `docker-compose.yml` would expose
+secrets or host-specific values in generated files that are typically committed to source control.
+Materializing them into `.devcontainer/.env` keeps generated config template-only.
+
+**Independent Test**: Set `env: {SECRET_KEY: supersecret}` on a compose-stack project, run
+`regen`, and confirm: (a) `docker-compose.yml` contains
+`services.devcontainer.environment.SECRET_KEY: ${SECRET_KEY}`, (b) `.devcontainer/.env` contains
+`SECRET_KEY=supersecret`, and (c) the literal value `supersecret` does not appear in
+`docker-compose.yml`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `env: {API_KEY: abc123}` on a compose stack, **When** generation runs, **Then** `docker-compose.yml` has `API_KEY: ${API_KEY}` and `.devcontainer/.env` has `API_KEY=abc123`.
+2. **Given** `env: {NAME: ${NAME:-default}}`, **When** generation runs with a root `.env` that sets `NAME=prod`, **Then** `.devcontainer/.env` receives `NAME=prod`.
+3. **Given** `env: {NAME: ${NAME}}` and no root `.env` entry for `NAME`, **When** generation runs, **Then** `.devcontainer/.env` does not include `NAME=` and Docker Compose shell fallback still works.
+
+---
+
+### User Story 2 — Configure env template entries with clearly named project-file field (Priority: P1)
+
+A developer updates their `superposition.yml` to use `customizations.envTemplate` (instead of
+the previously named `customizations.environment`) and expects the generated `.env.example`
+content to be identical to what the old field produced.
+
+**Why this priority**: The existing `environment` key is misleading — it writes to `.env.example`
+(a template), not to the runtime container environment. Renaming it clarifies intent and prevents
+confusion with the new `env:` field.
+
+**Independent Test**: Replace `customizations.environment` with `customizations.envTemplate` in a
+project file, run `regen`, and confirm the generated `.env.example` is byte-for-byte identical to
+the output produced with the old key.
+
+**Acceptance Scenarios**:
+
+1. **Given** `customizations.envTemplate: {FOO: bar}`, **When** generation runs, **Then** `.devcontainer/.env.example` contains `FOO=bar`.
+2. **Given** `customizations.environment: {FOO: bar}` (deprecated alias), **When** generation runs, **Then** `.devcontainer/.env.example` still contains `FOO=bar` (backward-compatible).
+3. **Given** a project file using `environment`, **When** it is read by the project loader, **Then** a deprecation warning is emitted directing users to rename the key.
+
+---
+
+### User Story 3 — remoteEnv wiring for compose env entries (Priority: P2)
+
+A developer on a compose stack expects that compose-targeted env variables are also accessible
+via `${containerEnv:KEY}` in `devcontainer.json → remoteEnv` so VS Code settings and
+extensions can reference them.
+
+**Why this priority**: Without a `remoteEnv` entry, VS Code extensions that read `process.env`
+at startup may not see the variable, even though the container process will.
+
+**Independent Test**: Set a compose-stack env variable, run `regen`, and confirm
+`devcontainer.json → remoteEnv` includes `KEY: ${containerEnv:KEY}` alongside the
+`docker-compose.yml` entry.
+
+**Acceptance Scenarios**:
+
+1. **Given** `env: {DB_URL: postgres://localhost/dev}` on a compose stack, **When** generation runs, **Then** `devcontainer.json` contains `remoteEnv.DB_URL: ${containerEnv:DB_URL}`.
+
+---
+
+## Overview
+
+Refine project-file environment semantics so compose-based projects do not
+embed resolved env values directly in generated `docker-compose.yml` or
+`devcontainer.json`.
+
+At the same time, rename the project-file field
+`customizations.environment` to `customizations.envTemplate` to make its
+purpose explicit: it writes template variables to `.env.example`, not runtime
+container environment.
+
+## Behavior
+
+### `env:` on `stack: compose`
+
+For compose-targeted project env entries:
+
+1. Materialize concrete values into `.devcontainer/.env`
+2. Write `docker-compose.yml -> services.devcontainer.environment.KEY: ${KEY}`
+3. Write `devcontainer.json -> remoteEnv.KEY: ${containerEnv:KEY}`
+
+This keeps generated config free of resolved secret values while still making
+the variables available inside the devcontainer.
+
+### Value Resolution
+
+- literals are written as-is to `.devcontainer/.env`
+- `${NAME}` resolves from the repository root `.env` when present
+- `${NAME:-default}` resolves from the repository root `.env`, otherwise uses
+  the inline default
+- unresolved `${NAME}` values are omitted from `.devcontainer/.env` so shell
+  environment fallback remains possible
+
+### `env:` on `stack: plain`
+
+No change: values still land directly in `devcontainer.json -> remoteEnv`.
+
+## `customizations.envTemplate`
+
+- `customizations.envTemplate` is the canonical project-file field for values
+  that should be written to `.env.example`
+- `customizations.environment` is retained as a deprecated backward-compatible
+  alias
+- serializers should emit `envTemplate`
+
+## Non-Goals
+
+- no change to `.devcontainer/custom/environment.env`
+- no support for targeting arbitrary compose sidecar services from `env:`