container-superposition 0.1.9 → 0.1.11

package/docs/specs/019-project-mounts/spec.md

@@ -0,0 +1,176 @@
+# Feature Specification: First-Class Mounts Support
+
+**Spec ID**: `019-project-mounts`
+**Created**: 2026-05-03
+**Status**: Approved
+**Input**: User request
+
+## Overview
+
+Add a top-level `mounts` field to `superposition.yml` that lets users declare filesystem mounts
+once and have the generation pipeline route them to the correct devcontainer artifact based on
+the active stack.
+
+This feature is modeled after the existing first-class `env` behavior.
+
+---
+
+## User Scenarios & Testing
+
+### User Story 1 — Declare a mount on a plain stack (Priority: P1)
+
+A developer adds a `mounts:` list to `superposition.yml` on a `plain` stack and expects each
+entry to appear in `devcontainer.json → mounts[]` after regeneration.
+
+**Why this priority**: Plain-stack users who need bind mounts (e.g. a shared workspace folder)
+currently must write custom `devcontainerPatch` JSON, which is difficult to discover and
+error-prone.
+
+**Independent Test**: Create a `superposition.yml` with `stack: plain` and a `mounts:` entry.
+Run `regen` and confirm the raw string appears in `devcontainer.json mounts`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `mounts: ["source=${localWorkspaceFolder}/../libs,target=/workspace/libs,type=bind"]`
+   with `stack: plain`, **When** generation runs, **Then** the string is present in
+   `devcontainer.json mounts[]`.
+2. **Given** a long-form entry `{value: "...", target: devcontainerMount}` with `stack: plain`,
+   **When** generation runs, **Then** the mount value is present in `devcontainer.json mounts[]`.
+3. **Given** a long-form entry with `target: auto` on `stack: plain`, **When** generation runs,
+   **Then** the mount routes to `devcontainer.json mounts[]` (same as default).
+
+---
+
+### User Story 2 — Declare a mount on a compose stack (Priority: P1)
+
+A developer adds a `mounts:` list to `superposition.yml` on a `compose` stack and expects each
+entry (with `target: auto` or string shorthand) to appear in `devcontainer.json mounts[]` —
+the same as it would on a plain stack — so the project file is **stack-agnostic**.
+
+**Why this priority**: Users should be able to swap `stack: plain` ↔ `stack: compose` without
+needing to touch the `mounts:` block.
+
+**Independent Test**: Create a `superposition.yml` with `stack: compose` and a `mounts:` entry.
+Run `regen` and confirm the entry appears in `devcontainer.json mounts[]` (not in compose
+volumes, unless `composeVolume` is explicitly requested).
+
+**Acceptance Scenarios**:
+
+1. **Given** `mounts: ["./data:/workspace/data"]` with `stack: compose`, **When** generation runs,
+   **Then** `./data:/workspace/data` appears in `devcontainer.json mounts[]`.
+2. **Given** `target: auto` on `stack: compose`, **When** generation runs, **Then** the mount
+   routes to `devcontainer.json mounts[]` (same as plain — stack-agnostic).
+
+---
+
+### User Story 3 — Explicit `composeVolume` target for Docker Compose volumes (Priority: P2)
+
+A developer who specifically wants a mount wired as a Docker Compose service volume (e.g. to
+leverage named volumes or compose-specific semantics) sets `target: composeVolume`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `{value: "...", target: composeVolume}` on `stack: compose`, **When** generation
+   runs, **Then** the value appears in `docker-compose.yml services.devcontainer.volumes[]`.
+2. **Given** `{value: "...", target: composeVolume}` on `stack: plain`, **When** generation runs,
+   **Then** generation errors with a clear message about compose-only targets.
+
+---
+
+### User Story 4 — Mounts coexist with customizations patches (Priority: P1)
+
+Mounts declared in the top-level `mounts:` field are applied before
+`customizations.devcontainerPatch` and `customizations.dockerComposePatch`, so patch overrides
+are still respected.
+
+**Acceptance Scenarios**:
+
+1. **Given** a `mounts:` entry and a `customizations.devcontainerPatch` that adds an additional
+   mount, **When** generation runs, **Then** both mounts appear in `devcontainer.json` (union merge).
+2. **Given** a compose-stack `mounts:` entry and a `customizations.dockerComposePatch` that adds
+   extra volumes, **When** generation runs, **Then** both sets appear in
+   `services.devcontainer.volumes`.
+
+---
+
+### User Story 5 — Validation (Priority: P1)
+
+The parser rejects clearly invalid mount declarations.
+
+**Acceptance Scenarios**:
+
+1. `target: composeVolume` on `stack: plain` → error at compose/devcontainer generation time.
+2. An entry with an empty `value` string → `ProjectConfigError` at parse time.
+3. An entry that is neither a string nor an object with `value` → `ProjectConfigError`.
+
+---
+
+## Schema Design
+
+### `superposition.yml`
+
+```yaml
+mounts:
+    # string shorthand — raw mount spec
+    - 'source=${localWorkspaceFolder}/../libs,target=/workspace/libs,type=bind'
+    # long form — explicit target routing
+    - value: './data:/workspace/data'
+      target: auto # default; always devcontainer.json mounts[] regardless of stack
+    - value: 'source=certs,target=/certs,type=volume'
+      target: devcontainerMount # always devcontainer.json
+    - value: './logs:/workspace/logs'
+      target: composeVolume # always docker-compose volumes (compose only)
+```
+
+### Routing table
+
+| `target`            | `stack: plain`             | `stack: compose`                                   |
+| ------------------- | -------------------------- | -------------------------------------------------- |
+| `auto` (default)    | `devcontainer.json mounts` | `devcontainer.json mounts`                         |
+| `devcontainerMount` | `devcontainer.json mounts` | `devcontainer.json mounts`                         |
+| `composeVolume`     | ❌ Error                   | `docker-compose.yml services.devcontainer.volumes` |
+
+`auto` and `devcontainerMount` are stack-agnostic: they always route to `devcontainer.json
+mounts[]` so that the same `superposition.yml` works without modification when swapping
+`stack: plain` ↔ `stack: compose`.
+
+---
+
+## Implementation Plan
+
+### Types (`tool/schema/types.ts`)
+
+- `ProjectMountTarget = 'auto' | 'devcontainerMount' | 'composeVolume'`
+- `ProjectMount = { value: string; target?: ProjectMountTarget }`
+- `QuestionnaireAnswers.projectMounts?: ProjectMount[]`
+- `ProjectConfigSelection.mounts?: Array<string | ProjectMount>`
+
+### Schema (`tool/schema/config.schema.json`)
+
+Add `mounts` as an array of `string | {value, target?}` (oneOf), matching the `env` pattern.
+
+### Parser (`tool/schema/project-config.ts`)
+
+- `parseMounts(value): ProjectMount[] | undefined` — normalize strings to `{value}` objects
+- Add `'mounts'` to the supported-keys set
+- Thread `mounts` through `loadProjectConfig`, `buildAnswersFromProjectConfig`,
+  `buildProjectConfigSelectionFromAnswers`, and `buildProjectConfigDocument`
+
+### Composer (`tool/questionnaire/composer.ts`)
+
+- `resolveProjectMountTarget(mount, stack)` — maps `ProjectMountTarget` to resolved destination
+- `applyProjectMountsToDevcontainer(config, mounts, stack)` — deepMerge devcontainerMount entries
+  into `config.mounts`
+- Thread compose-volume mounts into `mergeDockerComposeFiles` (analogous to `projectEnv`)
+- Apply before custom patches
+
+### Application order
+
+1. Base template loaded
+2. Overlays applied
+3. Port offsets applied
+4. Project env applied to devcontainer + compose
+5. **Project mounts applied to devcontainer + compose** ← new
+6. Custom patches applied (devcontainerPatch, dockerComposePatch)
+7. Target patches applied
+8. Files written

package/docs/specs/020-superposition-yml-schema.md

@@ -0,0 +1,83 @@
+# Spec 020: JSON Schema for `superposition.yml`
+
+## Overview
+
+Introduce a JSON Schema for `superposition.yml` / `.superposition.yml` project files. The schema
+enables editor auto-complete, inline validation, and tooling integration via the `$schema`
+property. It is generated automatically from source and kept in sync as part of the
+Definition of Done.
+
+## Goals
+
+1. **Authoring guidance** — editors that support JSON Schema (VS Code, JetBrains, etc.) can
+   provide completions and inline error highlighting when editing `superposition.yml`.
+2. **Generated automatically** — the schema is produced by `npm run schema:generate` from the
+   TypeScript types and live overlay registry, so it never goes stale.
+3. **Static referrable URL** — a stable URL pointing to the `main`-branch schema can be
+   added to any project's `superposition.yml` once and just works across versions.
+4. **Published with each release** — the schema file is uploaded as a release asset so
+   versioned pinning is also possible.
+5. **Embedded in generated files** — the tool injects a `$schema` line into every
+   `superposition.yml` it writes so users get validation for free without manual setup.
+
+## Schema URL
+
+| Purpose             | URL                                                                                                                   |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Static / latest     | `https://raw.githubusercontent.com/veggerby/container-superposition/main/tool/schema/superposition.schema.json`       |
+| Versioned (per tag) | `https://raw.githubusercontent.com/veggerby/container-superposition/v{VERSION}/tool/schema/superposition.schema.json` |
+| Release asset       | Attached to each GitHub release as `superposition.schema.json`                                                        |
+
+The static URL is always current and is the one written into generated `superposition.yml` files.
+
+## Schema file location
+
+`tool/schema/superposition.schema.json` — committed to the repository and updated by
+`npm run schema:generate`. Do not edit manually.
+
+## Generator script
+
+`scripts/generate-schema.ts` — run via `tsx` with `npm run schema:generate`.
+
+The generator:
+
+1. Imports the enum constant arrays (`STACK_VALUES`, `BASE_IMAGE_VALUES`, `TARGET_VALUES`,
+   `EDITOR_VALUES`, `PROJECT_ENV_TARGET_VALUES`, `PROJECT_MOUNT_TARGET_VALUES`) directly from
+   `tool/schema/project-config.ts`. These are the same arrays used at runtime for validation,
+   so the schema and the parser are always in agreement.
+2. Loads the live overlay registry (same path-resolution logic as `docs/generate-docs.ts`).
+3. Extracts overlay IDs by category, matching the `buildCategoryLookup()` rules (incl.
+   `database` + `messaging` both mapping to the `database` legacy field).
+4. Builds a JSON Schema (draft-07) describing `ProjectConfigSelection`, including:
+    - Enum values for `stack`, `baseImage`, `target`, `editor` derived from exported constants
+    - Dynamic `enum` for `overlays` items — non-preset overlay IDs only (presets are restricted
+      to the `preset` field)
+    - Per-category `enum` values for the legacy arrays (`language`, `database`, etc.) using the
+      same category rules as `buildCategoryLookup()`
+    - All compound types (`env`, `mounts`, `shell`, `customizations`, `parameters`)
+5. Writes the result to `tool/schema/superposition.schema.json`.
+
+## Definition of Done additions
+
+- `npm run schema:generate` must be run (and its output committed) whenever:
+    - A new overlay is added or removed
+    - The `ProjectConfigSelection` type changes (new/renamed/removed fields)
+    - Enum values for `stack`, `baseImage`, `target`, `editor` change
+- The CI validation workflow (`generate-docs.yml`) checks that the committed schema matches
+  a freshly generated one (same as the docs-sync check).
+
+## Serialization and round-trip
+
+`buildProjectConfigDocument` in `tool/schema/project-config.ts` places `$schema` as the
+first key in the YAML output. The value is taken from `selection.$schema` (the value that was
+in the file when it was loaded) with `SUPERPOSITION_SCHEMA_URL` as the fallback for new files.
+This means any user-pinned schema URL (e.g. a versioned release URL) is preserved on `regen`.
+
+## Release workflow
+
+The `publish.yml` workflow gains two steps after build:
+
+1. `npm run schema:generate` — regenerates the schema using the published version's overlay
+   set.
+2. `gh release upload` — uploads `tool/schema/superposition.schema.json` as a release asset
+   to the current GitHub release.

package/docs/specs/021-deterministic-generated-readme/spec.md

@@ -0,0 +1,70 @@
+# Feature Specification: Deterministic Generated README Header
+
+**Spec ID**: `021-deterministic-generated-readme`
+**Taxonomy**: `CLI-UX`
+**Created**: 2026-05-06
+**Author**: Codex
+**Status**: Approved
+**Input**: Bug report — `cs doctor` reproducibility checks can fail on a clean project because generated `README.md` content includes the current date in its header.
+
+## Problem Statement
+
+The consolidated generated `README.md` currently includes a line of the form
+`Generated by Container Superposition on YYYY-MM-DD`. That timestamp changes every day even when
+the project file, overlays, and generated devcontainer output are otherwise identical.
+
+This breaks the reproducibility contract behind `cs regen` and `cs doctor`: a no-op regeneration
+should produce byte-for-byte stable output when the effective configuration has not changed.
+
+## Goals
+
+- Make generated `README.md` output deterministic across repeated `cs regen` runs.
+- Preserve the provenance signal that the file is generated by Container Superposition.
+- Prevent future regressions with explicit test coverage.
+
+## Non-Goals
+
+- Removing timestamps from manifest metadata or other files not involved in this failure.
+- Redesigning the generated README structure or content beyond the unstable timestamp line.
+
+## Design
+
+### Header format
+
+Replace the current header line:
+
+```md
+> Generated by Container Superposition on YYYY-MM-DD
+```
+
+with a stable line:
+
+```md
+> Generated by Container Superposition
+```
+
+The template/base-image/preset metadata line remains unchanged.
+
+### Test coverage
+
+Add or update README generation tests to assert:
+
+1. The generated README still includes the provenance line.
+2. The provenance line does not include `on ` followed by a date fragment.
+
+## Requirements
+
+- **FR-001**: Generated `README.md` headers MUST NOT include the current date or time.
+- **FR-002**: Generated `README.md` headers MUST continue to indicate that the file was generated by Container Superposition.
+- **FR-003**: Automated tests MUST cover the deterministic header format.
+
+## Dependencies & Impact
+
+- **Affected Areas**: `tool/readme/readme-generator.ts`, `tool/__tests__/readme-generation.test.ts`, `CHANGELOG.md`
+- **Compatibility Impact**: Low. Existing generated READMEs will change by one line on the next `regen`.
+- **Required Documentation Updates**: `CHANGELOG.md`
+
+## Success Criteria
+
+- `cs regen` run twice on the same project produces the same `README.md` bytes.
+- `cs doctor` no longer flags README drift caused solely by the header date.