container-superposition 0.1.4 → 0.1.5

package/docs/specs/002-superposition-config-file/contracts/init-project-config.md

@@ -0,0 +1,98 @@
+# Contract: Init Project Config
+
+## Purpose
+
+Define the user-facing contract for repository-root project config input during
+`init` and `regen` runs.
+
+## Supported Files
+
+Exactly one of these files may be used at the repository root:
+
+- `.superposition.yml`
+- `superposition.yml`
+
+If both exist, initialization fails before generation.
+
+## Supported Declaration Surface
+
+The project config file may declare every supported clean-generation input that
+materially affects generated output, including:
+
+- stack selection
+- base image and custom image selection
+- container name
+- preset selection and preset parameters
+- overlay selections by category
+- output path
+- port offset
+- target environment
+- minimal/editor settings
+- supported customization inputs such as environment-related settings, custom
+  container definitions, preset glue values, and additional generated features
+
+## Resolution Rules
+
+### Standard Initialization
+
+1. Discover a supported project config file in the repository root.
+2. Validate the file and stop on any ambiguity or invalid entries.
+3. Apply project config values as the default persisted input source.
+4. Apply any direct command input as run-specific overrides.
+5. Collect only still-missing required values through the existing flow.
+
+### Explicit Project-File Source Selection
+
+1. `--from-project` selects the repository project file as the run's persisted
+   input source.
+2. The command fails before generation if no supported project file exists.
+3. `--from-project` may not be combined with `--from-manifest` or
+   clean-generation selection flags such as stack, overlays, or preset
+   selection.
+
+### Explicit Manifest Initialization
+
+1. Load the explicit manifest as the run’s persisted input source.
+2. Apply any direct command input as run-specific overrides.
+3. Do not silently merge repository project config values into that run.
+
+### Default Regeneration Source Selection
+
+1. `regen` first uses the repository project file when one exists and no other
+   persisted-input source has been selected.
+2. If no project file exists, `regen` falls back to manifest discovery in the
+   established manifest locations.
+3. Persisted-input source selection must be explicit and unambiguous before
+   generation starts.
+
+## Parity Requirement
+
+If a generation input is supported through the existing clean-generation path
+and materially affects generated output, it must be expressible through the
+project config file and yield the same final generated output.
+
+## Error Conditions
+
+Initialization must fail before generation when any of the following occur:
+
+- both supported project config filenames exist
+- the file cannot be parsed
+- unsupported keys or values are declared
+- conflicting selections are declared
+- `--from-project` and `--from-manifest` are used together
+- a persisted-input source mode is combined with clean-generation selection
+  flags such as stack, overlays, or preset selection
+- a required value is missing in a non-interactive context
+- a declared customization input is outside the supported clean-generation
+  surface
+
+## Verification Expectations
+
+- Valid project config yields the same output as equivalent direct user
+  selections.
+- Supported customization inputs round-trip through project config without
+  losing parity.
+- Missing project config preserves current interactive and flag-driven
+  behavior.
+- `regen` supports both explicit and implicit project-file source selection.
+- Explicit manifest runs remain isolated from project-config defaults.

package/docs/specs/002-superposition-config-file/data-model.md

@@ -0,0 +1,126 @@
+# Data Model: Project Configuration File
+
+## Entity: ProjectConfigFile
+
+**Purpose**: Represents the repository-root YAML document that declares shared
+generation intent for a project.
+
+**Fields**:
+
+- `path`: Absolute path to the discovered file.
+- `fileName`: `.superposition.yml` or `superposition.yml`.
+- `declaredValues`: Parsed user-authored generation inputs.
+- `status`: `missing`, `loaded`, `invalid`, or `ambiguous`.
+
+**Validation rules**:
+
+- At most one supported config filename may exist in the repository root.
+- The file must be valid YAML.
+- The file may declare only supported clean-generation inputs.
+
+## Entity: ProjectConfigSelection
+
+**Purpose**: Represents the set of supported generation inputs declared in the
+project config file.
+
+**Fields**:
+
+- `stack`
+- `baseImage`
+- `customImage`
+- `containerName`
+- `preset`
+- `presetChoices`
+- `language`
+- `database`
+- `observability`
+- `cloudTools`
+- `devTools`
+- `playwright`
+- `outputPath`
+- `portOffset`
+- `target`
+- `minimal`
+- `editor`
+- `customizationInputs`
+- `sourceMode`
+
+**Validation rules**:
+
+- Values must follow the same supported set as equivalent direct command or
+  interactive inputs.
+- Customization-related inputs must map to supported clean-generation behavior,
+  not unmanaged arbitrary output fragments.
+- Partial definitions are allowed, but unresolved required values must remain
+  completable through the existing flow.
+
+## Entity: CustomizationInput
+
+**Purpose**: Represents a supported non-basic generation setting that changes
+the final generated output beyond simple stack or overlay selection.
+
+**Fields**:
+
+- `kind`: category of customization input
+- `name`: user-facing identifier for the customization
+- `value`: declared value
+- `source`: `project-config`, `cli`, `manifest`, or `interactive`
+
+**Examples**:
+
+- custom container definition
+- environment-related setting
+- preset glue configuration
+- editor/minimal customization
+- additional generated feature setting
+
+**Validation rules**:
+
+- The customization must already be part of the supported clean-generation
+  surface.
+- The customization must round-trip through generation without being dropped or
+  silently rewritten to a different meaning.
+
+## Entity: EffectiveGenerationRequest
+
+**Purpose**: Represents the final resolved inputs for one generation run.
+
+**Fields**:
+
+- `sourceMode`: standard init, explicit project-file init, implicit project-file
+  regen, explicit manifest init, or standard init with direct overrides
+- `resolvedValues`: final merged `QuestionnaireAnswers`-equivalent values
+- `overrideSources`: per-field record of which source won precedence
+
+**Relationships**:
+
+- May derive from one `ProjectConfigSelection`
+- May derive from one explicit manifest input
+- May include many `CustomizationInput` values
+
+## Entity: ValidationIssue
+
+**Purpose**: Represents one user-facing problem found while loading the project
+config file.
+
+**Fields**:
+
+- `scope`: `discovery`, `syntax`, `field`, `selection`, `conflict`, `ambiguity`
+- `location`: file or config entry reference
+- `message`: user-facing description
+- `suggestedFix`: corrective action
+
+**State transitions**:
+
+- `detected` -> `reported`
+- `reported` -> `resolved by config edit`
+
+## Relationship Summary
+
+- One repository has zero or one `ProjectConfigFile`.
+- One `ProjectConfigFile` may contain one `ProjectConfigSelection`.
+- One `ProjectConfigSelection` may contain many `CustomizationInput` values.
+- One `EffectiveGenerationRequest` merges values from supported sources and
+  feeds generation plus manifest output.
+- One `EffectiveGenerationRequest` must resolve exactly one persisted-input
+  source mode before generation starts.

package/docs/specs/002-superposition-config-file/plan.md

@@ -0,0 +1,208 @@
+# Implementation Plan: Project Configuration File
+
+**Branch**: `002-superposition-config-file` | **Date**: 2026-03-11 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `docs/specs/002-superposition-config-file/spec.md`
+
+**Note**: This plan follows the approved spec and constitution gates for the
+active feature branch.
+
+## Summary
+
+Add repository-root project config support so `init` and `regen` can load a
+committed `.superposition.yml` or `superposition.yml` as a persisted source of
+truth for supported generation flows, with full parity to supported generation
+inputs, including customization surfaces such as custom container definitions,
+environment-related settings, preset glue, and additional generated features.
+The design extends the existing answer-merging flow instead of creating a second
+generation pipeline, introduces an explicit `--from-project` mode, allows
+implicit project-file use for `init --no-interactive` and default `regen` when
+no conflicting source or selection flags are supplied, and keeps explicit
+manifest-based regeneration as a separate persisted-input mode.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.3.3 on Node.js 20+  
+**Primary Dependencies**: Commander, chalk, boxen, js-yaml, ora, Inquirer  
+**Storage**: Filesystem-based project YAML config, `superposition.json`
+manifests, overlay 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**: Keep project-config discovery plus validation under 200
+ms in representative repositories so initialization remains dominated by the
+existing generation work rather than config loading  
+**Constraints**: Preserve backward compatibility for interactive, flag-driven,
+explicit project-file, and explicit manifest-based flows; preserve source/dist
+path compatibility with candidate-path resolution; maintain full parity between
+supported clean generation inputs and project-config declarations; reject
+conflicting persisted-input source combinations before generation; keep
+ambiguity and validation failures user-facing and deterministic  
+**Scale/Scope**: Single feature spanning `scripts/init.ts`, shared schema/types,
+config-loading helpers, command and composition tests, documentation, and
+generation parity for supported customization inputs
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design and
+before implementation._
+
+- [x] Spec exists at `docs/specs/002-superposition-config-file/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.
+
+Gate status: Pass. Planning may proceed.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+docs/specs/002-superposition-config-file/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── init-project-config.md
+└── tasks.md
+```
+
+### Source Code (repository root)
+
+```text
+scripts/
+└── init.ts
+
+tool/
+├── __tests__/
+│   ├── commands.test.ts
+│   ├── composition.test.ts
+│   ├── manifest-only.test.ts
+│   ├── minimal-and-editor.test.ts
+│   └── summary.test.ts
+├── questionnaire/
+│   └── composer.ts
+├── schema/
+│   ├── config.schema.json
+│   ├── project-config.ts
+│   └── types.ts
+└── utils/
+    └── summary.ts
+
+docs/
+├── examples.md
+├── workflows.md
+└── specs/
+
+README.md
+CHANGELOG.md
+```
+
+**Structure Decision**: Keep the feature centered on `scripts/init.ts`, because
+input discovery, CLI parsing, manifest handling, and answer merging already
+converge there. Add one focused schema/helper module for project-config
+discovery and validation, extend existing shared types for parity with clean
+generation inputs, and keep verification concentrated in existing command and
+composition test suites.
+
+## Phase 0: Research
+
+### Research Goals
+
+- Confirm the correct precedence between project config, direct command input,
+  interactive completion, explicit `--from-project`, implicit project-file
+  source selection, and explicit manifest mode.
+- Define what “full parity to clean generation” means for supported
+  customization inputs without introducing a second generation model.
+- Confirm discovery, ambiguity handling, and validation boundaries for a
+  repository-root YAML config.
+
+### Research Outputs
+
+- [research.md](research.md)
+
+## Phase 1: Design
+
+### Data Model
+
+- [data-model.md](data-model.md)
+
+### Contracts
+
+- [init-project-config.md](contracts/init-project-config.md)
+
+### Quickstart
+
+- [quickstart.md](quickstart.md)
+
+## Implementation Approach
+
+1. Add repository-root project-config discovery and validation to the standard
+   `init` flow and to `regen`, while keeping explicit manifest-based
+   regeneration behavior available as a separate mode.
+2. Model project config as another partial-answer source that feeds the existing
+   `QuestionnaireAnswers` merge path.
+3. Extend the supported config shape so it can declare every supported
+   clean-generation input, including customization surfaces already represented
+   in the current answer and generation flow.
+4. Add explicit source-selection validation so `--from-project` and
+   `--from-manifest` remain mutually exclusive and cannot be combined with
+   clean-generation selection flags such as stack, overlays, or preset choices.
+5. Preserve parity by ensuring project-config declarations yield the same final
+   generated output as equivalent direct user selections.
+6. Add regression coverage for no-config fallback, override precedence,
+   project-file based regen, explicit `--from-project`, manifest isolation,
+   source-conflict validation, invalid config handling, ambiguity detection, and
+   customization parity.
+7. Update docs and changelog entries so the declarative workflow, source
+   selection modes, and conflict rules are user-visible and auditable.
+
+## Verification Strategy
+
+- Add or update automated coverage for:
+    - repository-root project-config discovery
+    - no-config fallback behavior
+    - CLI-over-project-config precedence
+    - explicit `--from-project` behavior for `init` and `regen`
+    - implicit project-file selection for `init --no-interactive` and default
+      `regen`
+    - explicit manifest isolation from project-config defaults
+    - persisted-input source conflict validation (`--from-project`,
+      `--from-manifest`, and clean-generation selection flags)
+    - partial config completion through the existing questionnaire flow
+    - invalid YAML, unsupported keys or values, conflicts, and dual-file
+      ambiguity
+    - parity for supported customization inputs such as custom images, preset
+      glue, editor/minimal settings, environment-related settings, and additional
+      generated features
+- Run `npm test`.
+- Run `npm run lint`.
+- Run `npm run test:smoke` when generation behavior changes across representative
+  stacks.
+- Manually validate the scenarios in [quickstart.md](quickstart.md).
+
+## Post-Design Constitution Check
+
+- [x] Design preserves spec-first workflow and traces directly to the approved
+      spec.
+- [x] Design preserves overlay contract integrity by extending the existing
+      answer and generation pipeline rather than inventing a parallel path.
+- [x] Verification remains proportional to risk: automated tests, smoke
+      validation where applicable, and documentation updates are planned before
+      merge.
+- [x] Documentation synchronization is explicit: `README.md`,
+      `docs/workflows.md`, `docs/examples.md`, `quickstart.md`, and `CHANGELOG.md`.
+- [x] Simplicity and compatibility remain intact: project config is a default
+      persisted input source, explicit `--from-project` and explicit manifest
+      modes remain separate, and candidate-path compatibility stays required.
+
+## Complexity Tracking
+
+No constitution violations require a design exception.

package/docs/specs/002-superposition-config-file/quickstart.md

@@ -0,0 +1,140 @@
+# Quickstart: Project Configuration File
+
+## Goal
+
+Use a committed repository-root config file to declare the same supported setup
+intent that users would otherwise provide through clean generation commands.
+
+## 1. Add one project config file at the repository root
+
+Choose exactly one:
+
+- `.superposition.yml`
+- `superposition.yml`
+
+Do not keep both in the same repository.
+
+## 2. Declare the intended environment
+
+Define the supported clean-generation inputs your project needs, such as:
+
+- stack
+- overlays
+- presets and preset parameters
+- output path
+- custom image or container definition
+- environment-related settings
+- additional generated features and other supported customization inputs
+
+## 3. Run standard initialization
+
+```bash
+npm run init
+```
+
+Expected result:
+
+- the project config file supplies default generation intent
+- only still-missing required values are collected interactively
+- the generated output matches the declared setup and supported customization
+  settings
+
+## 4. Override a value for one run
+
+```bash
+npm run init -- --output ./tmp-devcontainer
+```
+
+Expected result:
+
+- the direct command value wins for that run only
+- the committed project config remains the default source of truth
+
+## 5. Use the same config in automation
+
+Run initialization from CI or another scripted workflow in a repository that
+contains the committed project config.
+
+Expected result:
+
+- non-interactive runs use declared defaults without prompting for already
+  declared values
+- repeated runs resolve the same configuration
+
+## 6. Regenerate from the project file
+
+```bash
+npm run init -- regen
+```
+
+Expected result:
+
+- `regen` uses the repository project file when one exists
+- the command does not require `--from-project` in that default case
+- the generated output matches the project file's declared intent
+
+## 7. Preserve explicit manifest regeneration
+
+```bash
+npm run init -- --from-manifest ./.devcontainer/superposition.json --no-interactive
+```
+
+Expected result:
+
+- the manifest remains the persisted input source for that run
+- repository project config does not silently override it
+
+## 8. Reject conflicting source modes early
+
+```bash
+npm run init -- init --from-project --stack compose
+```
+
+Expected result:
+
+- the command fails before generation
+- the error explains that persisted-input source flags cannot be mixed with
+  clean-generation selection flags
+
+## 9. Validate parity for supported customization inputs
+
+For any supported customization input that can be expressed through the existing
+clean-generation path:
+
+- declare it in the project config file
+- run generation
+- confirm the final generated output matches the equivalent clean-generation
+  result
+
+Examples of parity checks:
+
+- custom image or container definition
+- environment-related settings
+- preset glue values
+- additional generated features
+
+## 10. Maintainer workflow review
+
+Review result for `SC-003`:
+
+- a maintainer can create or update `.superposition.yml`, run `npm run init -- --no-interactive`, and inspect the generated output without reconstructing a long command
+- the documented workflow keeps the committed project config as the source of truth while still allowing one-run CLI overrides
+
+## 11. Verification record
+
+Validated during implementation:
+
+- targeted regression tests for project-config discovery, precedence, manifest isolation, no-config fallback, and customization parity
+- targeted regression tests for explicit `--from-project`, implicit project-file
+  `regen`, and source-conflict validation
+- `npm test`
+- `npm run lint`
+- `npm run test:smoke`
+
+Observed outcomes:
+
+- valid project-config driven runs generated the expected manifest and devcontainer output
+- `regen` used the repository project file by default when present and still
+  allowed explicit manifest-based regeneration
+- `--no-interactive` now works with a repository-root project config and still fails without any persisted input source
+- explicit `--from-manifest` runs ignored repository project-config defaults as required