container-superposition 0.1.7 → 0.1.9

package/docs/specs/011-overlay-parameters/spec.md

@@ -0,0 +1,228 @@
+# Feature Specification: Overlay Parameters with Safe Substitution
+
+**Spec ID**: `011-overlay-parameters`
+**Created**: 2026-03-30
+**Status**: Final
+**Input**: Issue — Introduce overlay parameters with safe, namespaced substitution — no conflicts with Docker/shell/VS Code
+
+## Summary
+
+Add first-class **parameters** to overlays so users can configure environment-specific values
+(credentials, database names, ports, paths) without forking overlays or hand-editing generated
+files.
+
+Parameters use the `{{cs.PARAM_NAME}}` substitution syntax, which does not collide with Docker
+Compose (`${VAR}`), shell (`$VAR`, `${VAR}`), VS Code (`${localWorkspaceFolder}`), or GitHub
+Actions (`${{ }}`).
+
+This is **parameter substitution only** — no loops, no conditionals, no embedded logic.
+If `string.replace()` can't do it, it doesn't belong here.
+
+---
+
+## Design
+
+### Syntax
+
+```
+{{cs.PARAM_NAME}}
+```
+
+- **Safe**: does not collide with `${VAR}` (Docker/shell), `${env:VAR}` (VS Code), or `${{ }}` (GitHub Actions)
+- **Consistent**: extends the existing `{{parameters.<key>.id}}` preset convention
+- **Explicit**: clearly owned by container-superposition
+- **Simple**: resolved by a single `string.replace()` regex, no parser needed
+
+### Overlay parameter declarations (`overlay.yml`)
+
+Overlays declare parameters in `overlay.yml`:
+
+```yaml
+id: postgres
+name: PostgreSQL
+category: database
+parameters:
+    POSTGRES_DB:
+        description: Database name
+        default: app
+    POSTGRES_USER:
+        description: Database user
+        default: postgres
+    POSTGRES_PASSWORD:
+        description: Database password
+        default: postgres
+        sensitive: true
+    POSTGRES_PORT:
+        description: Host-mapped port
+        default: '5432'
+```
+
+Fields:
+
+- `description` (required) — human-readable explanation shown in interactive prompts
+- `default` (optional) — default value; absence marks the parameter as _required_
+- `sensitive` (optional, boolean) — indicates secrets; hidden in interactive prompts and redacted from plan output
+
+### Usage in overlay files
+
+Overlay patches and compose files reference parameters using `{{cs.PARAM_NAME}}`:
+
+```json
+{
+    "remoteEnv": {
+        "DATABASE_URL": "postgres://{{cs.POSTGRES_USER}}:{{cs.POSTGRES_PASSWORD}}@postgres:5432/{{cs.POSTGRES_DB}}"
+    }
+}
+```
+
+```yaml
+# docker-compose.yml — generation-time substitution coexists with Docker runtime substitution
+services:
+    postgres:
+        environment:
+            POSTGRES_DB: '{{cs.POSTGRES_DB}}'
+            POSTGRES_USER: '{{cs.POSTGRES_USER}}'
+            POSTGRES_PASSWORD: '{{cs.POSTGRES_PASSWORD}}'
+        ports:
+            - '${POSTGRES_PORT:-{{cs.POSTGRES_PORT}}}:5432'
+```
+
+### Parameters in `superposition.yml`
+
+```yaml
+overlays:
+    - postgres
+    - redis
+
+parameters:
+    POSTGRES_DB: myapp
+    POSTGRES_USER: veggerby
+    REDIS_PORT: '6380'
+```
+
+### Resolution order (highest wins)
+
+1. CLI overrides (`--param POSTGRES_DB=foo`)
+2. Project file (`superposition.yml` `parameters:` section)
+3. Overlay defaults (`overlay.yml` `parameters[KEY].default`)
+
+### Validation rules
+
+| Condition                                                  | Behaviour                             |
+| ---------------------------------------------------------- | ------------------------------------- |
+| Missing required parameter (no default, no value supplied) | **Hard error** before generation      |
+| Unknown parameter (not declared by any selected overlay)   | **Warning** (proceed)                 |
+| Unresolved `{{cs.*}}` in final output                      | **Hard error** (catch-all safety net) |
+
+### Pass-through guarantee
+
+The substitution engine MUST NOT touch:
+
+- Docker Compose expressions: `${VAR}`, `${VAR:-default}`, `$VAR`
+- VS Code/devcontainer variables: `${localWorkspaceFolder}`, `${containerWorkspaceFolder}`, `${env:VAR}`
+- GitHub Actions expressions: `${{ github.* }}`
+- Shell variables in scripts: `$FOO`, `${FOO}`, `${FOO:-default}`
+
+Only tokens matching exactly `{{cs.[A-Z0-9_]+}}` are substituted.
+
+---
+
+## Implementation Scope
+
+### Types (`tool/schema/types.ts`)
+
+```typescript
+export interface OverlayParameterDefinition {
+    description: string;
+    default?: string;
+    sensitive?: boolean;
+}
+```
+
+Add to `OverlayMetadata`:
+
+```typescript
+parameters?: Record<string, OverlayParameterDefinition>;
+```
+
+Add to `ProjectConfigSelection`:
+
+```typescript
+parameters?: Record<string, string>;
+```
+
+Add to `QuestionnaireAnswers`:
+
+```typescript
+overlayParameters?: Record<string, string>;
+```
+
+### Parameter engine (`tool/utils/parameters.ts`)
+
+- `collectOverlayParameters(overlayIds, allOverlayDefs)` — collect all declared parameters from selected overlays with their defaults
+- `resolveParameters(declared, supplied)` — apply resolution order, return resolved map and errors
+- `substituteParameters(content, resolved)` — replace `{{cs.KEY}}` tokens in a string
+- `validateFinalContent(content)` — error if any `{{cs.*}}` remain after substitution
+
+### Composer (`tool/questionnaire/composer.ts`)
+
+After all overlay files are read and before they are written to disk:
+
+1. Collect parameter declarations from selected overlays
+2. Merge with `answers.overlayParameters` values
+3. Validate — error on missing required parameters
+4. Apply substitution to all file content strings (devcontainer.json, docker-compose.yml, .env.example, scripts)
+5. Validate — error on any unresolved `{{cs.*}}` tokens remaining in output
+
+### Project config (`tool/schema/project-config.ts`)
+
+Parse `parameters:` YAML map as `Record<string, string>` (string values only).
+Propagate to `selection.parameters` → `answers.overlayParameters`.
+
+### Init (`scripts/init.ts`)
+
+When overlay declares parameters, interactive questionnaire prompts for values.
+Sensitive parameters use masked input. Pre-filled with defaults.
+
+---
+
+## Non-goals
+
+- Conditional logic (`{{if ...}}`)
+- Loops or iteration
+- Programmable overlays or JS execution
+- Dynamic file generation
+- Templating engine integration (Handlebars, Jinja, EJS, etc.)
+
+---
+
+## User Scenarios & Testing
+
+### User Story 1 — Postgres with custom database name (P1)
+
+A user scaffolds a compose stack with the postgres overlay and wants their database named `myapp`
+instead of the default `devdb`.
+
+**Acceptance scenarios**:
+
+1. **Given** a `superposition.yml` with `parameters: { POSTGRES_DB: myapp }`, **When** generation runs, **Then** the generated `.devcontainer/docker-compose.yml` and `remoteEnv` in `devcontainer.json` reference `myapp` instead of `devdb`.
+2. **Given** an overlay with a required parameter (no default), **When** generation is run without providing the parameter value, **Then** the tool exits with a clear error message before writing any files.
+3. **Given** generated files contain no `{{cs.*}}` tokens, **When** output is validated, **Then** no error is raised and Docker Compose `${VAR}` expressions are preserved unmodified.
+4. **Given** a user runs `init` interactively with the postgres overlay, **When** the questionnaire reaches parameters, **Then** the user is prompted for each declared parameter with the default pre-filled.
+
+### User Story 2 — Sensitive parameter (P2)
+
+A user provides a database password via parameter. The password must not appear in plan output in cleartext.
+
+**Acceptance scenarios**:
+
+1. **Given** a parameter has `sensitive: true`, **When** the plan command shows parameter values, **Then** the value is displayed as `***`.
+2. **Given** a parameter has `sensitive: true`, **When** the interactive questionnaire prompts for it, **Then** the input is masked.
+
+### User Story 3 — Unknown parameter warning (P3)
+
+A user adds a parameter in `superposition.yml` that is not declared by any selected overlay.
+
+**Acceptance scenarios**:
+
+1. **Given** `parameters: { UNKNOWN_PARAM: foo }` in `superposition.yml`, **When** generation runs, **Then** a warning is printed but generation succeeds.

package/docs/specs/012-ollama-cli-overlay/spec.md

@@ -0,0 +1,47 @@
+# Feature Specification: Split Ollama Service and CLI Overlays
+
+**Spec ID**: `012-ollama-cli-overlay`
+**Created**: 2026-04-16
+**Status**: Final
+**Input**: Requirement — split current `ollama` overlay into separate service and CLI overlays, with implicit dependency from `ollama` to `ollama-cli`
+
+## Summary
+
+Separate Ollama support into two overlays:
+
+1. `ollama` — compose-only Ollama server sidecar
+2. `ollama-cli` — CLI-only installation that works in plain and compose stacks
+
+Selecting `ollama` must automatically include `ollama-cli` via `requires` so existing behavior is preserved.
+
+## Design
+
+### Overlay split
+
+- `ollama` remains compose-only and owns service wiring (`docker-compose.yml`, API port, sidecar host env)
+- `ollama-cli` owns CLI installation and CLI verification
+- `ollama` declares `requires: [ollama-cli]`
+
+### User intent supported
+
+- Users can choose only `ollama-cli` in plain stacks when Ollama runs elsewhere (for example on host)
+- Users can still choose `ollama` and get server + CLI automatically
+
+## Implementation Scope
+
+- Add `overlays/ollama-cli/` with `overlay.yml`, `devcontainer.patch.json`, `setup.sh`, `verify.sh`, `README.md`
+- Update `overlays/ollama/overlay.yml` to require `ollama-cli`
+- Remove CLI installation from `overlays/ollama` and keep service responsibilities there
+- Update tests and changelog entries
+
+## User Scenarios & Testing
+
+### User Story 1 — Plain stack with remote Ollama
+
+1. **Given** a plain stack with `ollama-cli`, **When** generation runs, **Then** the devcontainer contains the `ollama` CLI without requiring a local compose service.
+2. **Given** `OLLAMA_HOST` is configured to a remote endpoint, **When** users run `ollama list`, **Then** requests target that remote server.
+
+### User Story 2 — Compose stack with local sidecar
+
+1. **Given** a compose stack with `ollama`, **When** generation runs, **Then** `ollama-cli` is auto-added and CLI commands are available in the devcontainer.
+2. **Given** the compose sidecar is running, **When** verification runs, **Then** the service endpoint is reachable via `http://ollama:11434`.

package/docs/specs/013-doctor-dependency-check/spec.md

@@ -0,0 +1,250 @@
+# Feature Specification: Doctor Overlay Dependency Resolution Check
+
+**Spec ID**: `013-doctor-dependency-check`
+**Taxonomy**: `CLI-UX`
+**Created**: 2026-04-24
+**Author**: PM Agent
+**Status**: Approved
+**Input**: Feature assessment — `cs doctor` does not validate that selected overlays satisfy their own dependency requirements; missing `requires:` entries are only caught at regen time.
+
+## Problem Statement
+
+`cs doctor` checks many things about an existing `.devcontainer/` setup but never validates that
+the overlay set declared in the project file is self-consistent. If a project file includes
+`grafana` but omits the required `prometheus`, the error only surfaces when `cs regen` runs or
+when the user opens the devcontainer. Doctor should catch these problems immediately, with a
+clear message and — where safe — fix them automatically.
+
+The same gap applies to `suggests:` (advisory recommendations never surfaced) and to overlays
+listed in the project file that no longer exist in the registry (typos, removed overlays).
+
+## Goals
+
+- Detect missing `requires:` overlays between the project file's overlay set and the overlay
+  registry before regen or container startup.
+- Detect overlay IDs in the project file that are not present in the overlay registry.
+- Surface `suggests:` recommendations as informational notices (not failures).
+- Allow `doctor --fix` to add missing required overlays to the project file and re-run
+  generation.
+
+## Non-Goals
+
+- Validating `conflicts:` — conflict detection already happens during composition.
+- Changing the dependency resolution logic in `composer.ts`.
+- Checking transitive suggestions (only direct `suggests:` from selected overlays).
+
+## Design
+
+### Dependency resolution check
+
+`checkDependencies(overlaysConfig, workingDir)` loads the project file via `loadProjectConfig()`
+and returns early (empty result) if none exists.
+
+For each overlay ID in `selection.overlays`:
+
+1. **Unknown overlay**: overlay ID not in `overlaysConfig.overlays` → `fail` ("Overlay `<id>`
+   not found in registry — it may have been removed or misspelled").
+2. **Missing required overlay**: for each ID in `overlay.requires`, check if the full resolved
+   set (project overlays + auto-resolved via `resolveImplicitDependencies`) covers it. If not →
+   `fail` ("Overlay `<id>` requires `<dep>` which is not in your project file").
+3. **Missing suggested overlay**: for each ID in `overlay.suggests`, check if it is present in
+   the resolved set. If not → `warn` ("Overlay `<id>` suggests `<dep>` — consider adding it for
+   better observability / functionality").
+
+The check uses the same resolution helpers used by `composer.ts` so the rules are identical.
+
+Pass check message: "`N` overlay(s) selected; all dependencies satisfied."
+
+### Fix action: `dependency-fix`
+
+Registered in `REMEDIATION_REGISTRY`:
+
+- **Safety class**: `safe-unattended`
+- **Execution kind**: `regeneration`
+- **Planned changes**:
+    - "Add missing required overlay(s) to project file"
+    - "Regenerate devcontainer configuration from updated project file"
+
+`executeDependencyFix(outputPath, overlaysConfig, overlaysDir, workingDir, silent)`:
+
+1. Load project config.
+2. Identify missing required overlays (same logic as the check).
+3. Add them to `selection.overlays`.
+4. Write updated project file with `writeProjectConfig()`.
+5. Rebuild answers from updated config and call `composeDevContainer()`.
+6. Re-check: verify no dependency failures remain.
+
+Unknown overlay IDs (not in registry) are **not** auto-fixable — marked `manual-only`.
+Suggested overlays are never auto-added — always `not-applicable`.
+
+### DoctorReport changes
+
+`DoctorReport` gains a `dependencies: CheckResult[]` field.
+`generateReport()` gains a `dependenciesChecks` parameter.
+`formatAsText()` gains a "Dependencies" section that shows failures and warnings;
+suppresses the section entirely if all pass.
+`reportToFindings()` includes `checksToFindings(report.dependencies, 'manifest', 'full')`.
+`executeFixRun()` calls `checkDependencies()` in the re-check pass.
+
+### Affected files
+
+| File                              | Change                                                                                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `tool/commands/doctor.ts`         | Add `checkDependencies()`, `executeDependencyFix()`, wire into report infrastructure, `REMEDIATION_REGISTRY`, `PRIORITY` map |
+| `tool/__tests__/commands.test.ts` | Tests for unknown overlay, missing required, suggestion warn, fix action                                                     |
+| `CHANGELOG.md`                    | Entry under `### Added`                                                                                                      |
+
+### User-visible behaviour
+
+```
+Dependencies:
+  ✗ Overlay grafana requires prometheus which is not in your project file
+    → Add prometheus to the overlays: list in .superposition.yml
+    → Fixable with --fix flag
+  ⚠ Overlay postgres suggests grafana — consider adding it for observability
+  ✓ All other overlay dependencies satisfied
+```
+
+### Backward compatibility
+
+No changes to existing generated files or project file format. Purely additive check.
+
+## User Scenarios & Testing
+
+### User Story 1 — Missing required overlay detected and fixed (P1)
+
+A developer has `grafana` in their project file but forgot to add `prometheus` (which grafana
+requires). They run `cs doctor` and immediately see the problem instead of discovering it when
+the devcontainer fails to build.
+
+**Why this priority**: Missing required overlays cause silent failures at startup. This is the
+most actionable fix doctor can offer — it unblocks the user immediately.
+
+**Independent Test**: Write a `.superposition.yml` selecting `grafana` without `prometheus`.
+Run `doctorCommand`. Assert output contains dependency failure mentioning `prometheus`.
+
+**Acceptance Scenarios**:
+
+1. **Given** a project file with `overlays: [grafana]`, **When** `cs doctor` runs, **Then** a
+   `fail` finding reports "`grafana` requires `prometheus` which is not in your project file".
+2. **Given** the same setup with `--fix`, **When** doctor runs, **Then** `prometheus` is added
+   to the project file and `cs regen` is run automatically; the final check passes.
+3. **Given** a project file with `overlays: [grafana, prometheus]`, **When** `cs doctor` runs,
+   **Then** the dependencies section shows a pass with no failures.
+
+---
+
+### User Story 2 — Unknown overlay ID caught (P2)
+
+A developer misspells an overlay ID (`nodjs` instead of `nodejs`) in their project file. Doctor
+catches it immediately rather than letting it silently be ignored during generation.
+
+**Why this priority**: Typos in the project file produce no error today — the overlay is simply
+not applied. Doctor should surface this.
+
+**Independent Test**: Write a `.superposition.yml` with `overlays: [nodjs]`. Run
+`doctorCommand`. Assert a `fail` finding mentioning `nodjs` not found in registry.
+
+**Acceptance Scenarios**:
+
+1. **Given** `overlays: [nodjs]` in project file, **When** `cs doctor` runs, **Then** a `fail`
+   finding reports "`nodjs` not found in overlay registry — check for typos".
+2. **Given** `overlays: [nodejs]`, **When** `cs doctor` runs, **Then** no unknown-overlay
+   failure appears.
+
+---
+
+### User Story 3 — Suggestions surfaced as informational (P3)
+
+A user has `postgres` selected. The postgres overlay suggests `prometheus` and `grafana` for
+observability. Doctor shows these as soft recommendations, not failures.
+
+**Why this priority**: Suggestions are optional by definition; showing them as warnings without
+blocking is a quality-of-life improvement.
+
+**Independent Test**: Write a `.superposition.yml` with `overlays: [postgres]` (postgres
+suggests `prometheus`, `grafana`). Run `doctorCommand`. Assert warn-level findings for each
+suggestion, no failures.
+
+**Acceptance Scenarios**:
+
+1. **Given** `overlays: [postgres]` (postgres suggests prometheus, grafana), **When** `cs doctor`
+   runs, **Then** two `warn` findings appear suggesting prometheus and grafana; no failure.
+2. **Given** `overlays: [postgres, prometheus, grafana]`, **When** `cs doctor` runs, **Then** no
+   suggestion warnings appear for postgres.
+
+---
+
+### Edge Cases
+
+- Project file with no overlays: return a single pass ("no overlays selected").
+- Overlay that requires itself: guard against infinite recursion (not expected but safe to handle).
+- `requires:` chain (A requires B which requires C, project has A and C but not B): each missing
+  level reported individually.
+- Auto-resolved dependencies already in the manifest but not in the project file: not flagged
+  (the resolver adds them automatically; this mirrors drift-check behaviour).
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: `checkDependencies()` MUST return `fail` for each overlay in the project file that
+  references a non-existent registry ID.
+- **FR-002**: `checkDependencies()` MUST return `fail` for each `requires:` entry of a selected
+  overlay that is absent from the resolved overlay set.
+- **FR-003**: `checkDependencies()` MUST return `warn` for each `suggests:` entry of a selected
+  overlay that is absent from the resolved overlay set.
+- **FR-004**: `executeDependencyFix()` MUST add missing required overlays to the project file
+  and regenerate; it MUST NOT add suggested overlays.
+- **FR-005**: Unknown overlay IDs MUST be marked `manual-only` (no auto-fix).
+- **FR-006**: The check MUST use the same dependency resolution logic as `composer.ts` (no
+  duplication; shared helpers).
+- **FR-007**: When no project file is present, the check MUST return an empty result (no noise).
+
+### Key Entities
+
+- **ResolvedOverlaySet**: the set of overlay IDs after implicit dependency resolution — used as
+  the reference for missing-dep detection.
+- **DependencyFinding**: a `CheckResult` enriched with `sourceOverlay` and `missingOverlay` for
+  accurate error messages.
+
+## Dependencies & Impact
+
+- **Affected Areas**: `tool/commands/doctor.ts`, `tool/__tests__/commands.test.ts`, `CHANGELOG.md`
+- **Compatibility Impact**: None — purely additive new check category.
+- **Required Documentation Updates**: `CHANGELOG.md`
+- **Verification Plan**: Unit tests in `commands.test.ts`; manual test with a project file that
+  has a real missing dependency.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: `cs doctor` on a project file missing a `requires:` dependency reports a `fail`
+  within the Dependencies section within the existing doctor runtime (no perceptible extra
+  latency).
+- **SC-002**: `cs doctor --fix` on the same setup produces a project file with the missing overlay
+  added and a passing re-check.
+- **SC-003**: `npm test` passes with at least 3 new test cases covering: unknown ID, missing
+  required, suggestion warn.
+- **SC-004**: No existing doctor tests regress.
+
+## Open Questions
+
+| #   | Question                                                                        | Owner | Resolution                                       |
+| --- | ------------------------------------------------------------------------------- | ----- | ------------------------------------------------ |
+| 1   | Should transitive `suggests` (suggests of suggests) be surfaced or only direct? | PM    | Pending — lean toward direct only to avoid noise |
+| 2   | Should `dependency-fix` add suggested overlays when user passes `--suggest`?    | PM    | Pending                                          |
+
+## Out of Scope
+
+- Changing the dependency resolver in `composer.ts`.
+- Validating that `conflicts:` declarations are bidirectional (already covered by `overlay-consistency` agent).
+- Surfacing overlay version constraints (overlays don't have versions today).
+
+## Implementation Notes
+
+- `checkDependencies` reads raw YAML as a fallback when `loadProjectConfig` throws for unknown overlay IDs, allowing the check to detect the unknown ID itself.
+- Comparison is against `projectFileSet` (the overlay IDs explicitly listed in the project file), not the resolved set — otherwise transitive auto-resolved dependencies would always appear satisfied.
+- `suggests` mismatches are surfaced as `warn`; `requires` mismatches as `fail` with `fixable: true` and remediation key `dependency-fix`.
+- The Dependencies section in `formatAsText` shows the pass summary alongside any suggestion warnings (i.e., the pass line is shown when there are no `fail` results, even if `warn` results exist).