container-superposition

Composable devcontainer scaffolds that collapse into normal, editable configs.

Development Policy

This project follows spec-first development. Every feature MUST start with a reviewed spec committed under docs/specs/ before implementation code is written.

Quickstart

# Discover available overlays and presets
npx container-superposition list
npx container-superposition explain postgres

# Preview before writing files
npx container-superposition plan --stack compose --overlays nodejs,postgres,grafana
npx container-superposition plan --stack compose --overlays grafana --verbose

# Guided questionnaire — writes shared project intent and generated output
npx container-superposition init

# Declarative project config committed in the repo
cat > superposition.yml <<'YAML'
stack: compose
overlays:
  - nodejs
  - postgres
env:
  APP_ENV: development
mounts:
  - "./local-tools:/workspace/tools"
ports:
  - ${API_PORT:-8080}:8080
customizations:
  envTemplate:
    POSTGRES_PASSWORD: postgres
YAML
npx container-superposition init --no-interactive

# Regenerate from the repository project file
npx container-superposition regen

# Or select the project file explicitly
npx container-superposition regen --from-project

# Non-interactive CLI example
npx container-superposition init --stack compose --language nodejs --database postgres

# Write only superposition.yml without generating .devcontainer/
npx container-superposition init --stack compose --language nodejs --no-scaffold

# Migrate a manifest-only repo to the project-file model
npx container-superposition migrate

What It Does

• Base templates: plain (single image) and compose (multi-service).
• Overlays: add languages, databases, observability, cloud tools, dev tools.
• Composition: merges overlays into a standard .devcontainer/ you can edit freely.
• Compose defaults: tool-owned compose port bindings are hard-rendered to final numeric host ports; .devcontainer/.env and .devcontainer/.env.example are opt-in artifacts only via --compose-env-files / composeEnvFiles: true.
• Project config: superposition.yml (or .superposition.yml) is the canonical input for all generation and regeneration flows. Commit it to your repo for reproducible team and CI builds.
  • init always writes superposition.yml as its primary output
  • regen reads only the project file — superposition.json is an output-only receipt
  • Repos without a project file should run cs migrate once to create one from their manifest
  • Optional ~/.superposition.yml defaults can prefill only eligible fresh init runs (~/.container-superposition.yml still works and wins when both exist)
  • doctor compares the project file against the last-generated manifest and reports drift

Core Commands

• init — run the interactive questionnaire; always writes superposition.yml and (by default) scaffolds .devcontainer/
  • Add --compose-env-files to persist composeEnvFiles: true and generate .devcontainer/.env plus .devcontainer/.env.example
  • Add --no-scaffold to write only the project file without generating .devcontainer/
  • Add --ignore-global-defaults to bypass ~/.container-superposition.yml and ~/.superposition.yml for one run
  • Add --project-root <path> to resolve persisted input from a different repository root
• regen — deterministically replay the repository project file (superposition.yml required)
  • Add --compose-env-files to update shared intent to composeEnvFiles: true before regeneration
  • Add --project-root <path> to resolve persisted input from a different repository root
• migrate — one-time migration: creates superposition.yml from an existing superposition.json
  • Required for repos that ran init before this project-file-first model was introduced
• adopt — migrate an existing .devcontainer/ to the overlay-based workflow
• list — browse overlays and presets
• explain — inspect overlay or preset details
• plan — preview output before writing
  • Add --verbose to narrate dependency resolution and inclusion reasons
  • Add --from-manifest <path> to preview an existing manifest with the same explanation model
• hash — deterministic environment fingerprint
• doctor — validate environment and detect project-file drift

Documentation

Start here:

• Docs index
• superposition.yml reference ← project file authoring guide
• Versioned private catalogs
• Quick reference
• Adopt command
• Hash command
• Examples
• Presets
• Architecture
• Overlays
• Custom patches
• Workflows and regen
• Filesystem contract
• Security
• Publishing

Examples

• Example projects
• Examples guide

Contributing

See CONTRIBUTING.md. Overlay and generated-output behavior changes now use the shared Behave workflow via npm run test:bdd / task test:bdd, with task validate:generated as the full pre-handoff path.

License

MIT. See LICENSE