container-superposition 0.1.6 → 0.1.8

package/docs/deployment-targets.md

@@ -1,16 +1,24 @@
 # Deployment Target Support
 
-Container Superposition validates overlay compatibility with different deployment environments using the `--target` flag.
+Container Superposition generates workspace artifacts and setup guidance tailored to the
+selected deployment environment using the `--target` flag.
 
 ## Quick Start
 
 ```bash
-# Specify deployment target
+# Default — local development (no additional files)
+npx container-superposition init --stack compose --language nodejs
+
+# GitHub Codespaces (adds hostRequirements + CODESPACES.md)
 npx container-superposition init --target codespaces
+
+# Gitpod (adds .gitpod.yml + GITPOD.md)
 npx container-superposition init --target gitpod
-npx container-superposition init --target local  # default
 
-# With specific configuration
+# DevPod (adds devpod.yaml + DEVPOD.md)
+npx container-superposition init --target devpod
+
+# Full example for Codespaces
 npx container-superposition init \
     --stack compose \
     --language nodejs \
@@ -21,24 +29,52 @@ npx container-superposition init \
 
 ## Supported Deployment Targets
 
-| Target         | Description                       | Docker Support | Auto Port Forward |
-| -------------- | --------------------------------- | -------------- | ----------------- |
-| **local**      | Local machine with Docker Desktop | ✅ Host Docker | No                |
-| **codespaces** | GitHub Codespaces (cloud IDE)     | ⚠️ DinD only   | Yes               |
-| **gitpod**     | Gitpod workspaces                 | ⚠️ DinD only   | Yes               |
-| **devpod**     | DevPod client-only environments   | ✅ Host Docker | No                |
+| Target         | Description                       | Docker Support | Auto Port Forward | Extra Artifacts                                          |
+| -------------- | --------------------------------- | -------------- | ----------------- | -------------------------------------------------------- |
+| **local**      | Local machine with Docker Desktop | ✅ Host Docker | No                | None (current behavior)                                  |
+| **codespaces** | GitHub Codespaces (cloud IDE)     | ⚠️ DinD only   | Yes               | `hostRequirements` in devcontainer.json; `CODESPACES.md` |
+| **gitpod**     | Gitpod workspaces                 | ⚠️ DinD only   | Yes               | `.gitpod.yml` at project root; `GITPOD.md`               |
+| **devpod**     | DevPod client-only environments   | ✅ Host Docker | No                | `devpod.yaml` at project root; `DEVPOD.md`               |
 
-## How It Works
+## Target-Specific Artifact Inventory
 
-### Interactive Mode
+### `--target codespaces`
+
+| File                | Location         | Purpose                                                                           |
+| ------------------- | ---------------- | --------------------------------------------------------------------------------- |
+| `devcontainer.json` | `.devcontainer/` | Extended with `hostRequirements` (cpu/memory/storage recommendation)              |
+| `CODESPACES.md`     | `.devcontainer/` | How to open the repo in a Codespace; machine-type guidance; port forwarding notes |
+
+**Machine size recommendation** is determined automatically from the overlays selected:
+
+- 0–1 service overlays → 2-core (default)
+- 2–3 service overlays → 4-core recommended
+- 4+ service overlays → 8-core recommended
+
+### `--target gitpod`
+
+| File          | Location         | Purpose                                                                             |
+| ------------- | ---------------- | ----------------------------------------------------------------------------------- |
+| `.gitpod.yml` | **Project root** | Gitpod workspace config; references devcontainer; declares tasks and port exposures |
+| `GITPOD.md`   | `.devcontainer/` | One-click open badge; Gitpod-specific usage notes                                   |
 
-If you select incompatible overlays (e.g., `docker-sock` for Codespaces), the tool will:
+### `--target devpod`
 
-- Show which overlays won't work in your target environment
-- Suggest compatible alternatives
-- Let you choose your deployment target with informed guidance
+| File          | Location         | Purpose                                              |
+| ------------- | ---------------- | ---------------------------------------------------- |
+| `devpod.yaml` | **Project root** | DevPod workspace descriptor; references devcontainer |
+| `DEVPOD.md`   | `.devcontainer/` | `devpod up` instructions; provider examples          |
 
-**Example interaction:**
+### `--target local` / no `--target`
+
+No additional files are written. Output is identical to the current local-first workflow.
+
+## How It Works
+
+### Interactive Mode
+
+If you select overlays that may not work in a cloud environment (e.g. `docker-sock`), the tool
+prompts you to choose a target so it can warn about incompatibilities:
 
 ```
 ⚠️  Deployment Target Compatibility Check:
@@ -56,76 +92,70 @@ Which environment are you targeting?
   📦 DevPod
 ```
 
-### CLI Mode
-
-The target validates your selection and generates the configuration:
-
-- Incompatibilities are allowed (you know what you're doing)
-- Generated documentation notes any compatibility issues
+After you confirm the target, the generator produces the appropriate workspace artifacts
+alongside the standard `.devcontainer/` output.
 
-## Example Configurations
+### CLI Mode
 
-### Optimized for GitHub Codespaces
+Pass `--target` directly — the target is applied without interactive prompts:
 
 ```bash
 npx container-superposition init \
     --stack compose \
     --language nodejs \
-    --database postgres \
     --dev-tools docker-in-docker \
-    --target codespaces
+    --target gitpod
 ```
 
-### Local Development
+### Regeneration
+
+The selected target is saved in `superposition.json` as the `target` field. Regeneration
+re-produces the correct artifacts automatically without re-prompting:
 
 ```bash
-npx container-superposition init \
-    --stack compose \
-    --language nodejs \
-    --database postgres \
-    --dev-tools docker-sock \
-    --target local
+# superposition.json contains "target": "gitpod"
+npx container-superposition regen   # → .gitpod.yml and GITPOD.md reproduced
+```
+
+To switch target on regeneration, pass `--target` explicitly:
+
+```bash
+npx container-superposition regen --target codespaces
 ```
 
+Stale artifacts from the previous target (e.g. `.gitpod.yml`) are **removed automatically**
+before the new target's artifacts are written.
+
 ## Key Compatibility Rules
 
 - ⚠️ **docker-sock** requires host Docker → Use in `local` or `devpod` only
 - ✅ **docker-in-docker** works everywhere → Recommended for `codespaces` and `gitpod`
-- 🔄 Cloud targets auto-forward ports → No manual forwarding needed
+- 🔄 Cloud targets auto-forward ports → No manual port forwarding needed
 
 ## Environment Differences
 
-Different environments have different capabilities:
-
-### Codespaces/Gitpod
+### Codespaces / Gitpod
 
-- **No access to host Docker daemon** - Must use docker-in-docker
-- **Auto-forward ports** - Ports are automatically accessible
-- **Cloud-based** - Resources may be constrained
+- **No access to host Docker daemon** — Must use docker-in-docker
+- **Auto-forward ports** — Ports declared in devcontainer.json are automatically accessible
+- **Cloud-based** — Resources may be constrained; machine size matters
 
 ### Local
 
-- **Full access to host Docker** - Can use docker-sock for better performance
-- **Faster builds** - Shared cache with host
-- **Manual port forwarding** - Need to expose ports explicitly
+- **Full access to host Docker** — Can use docker-sock for better performance
+- **Faster builds** — Shared cache with host
+- **Manual port forwarding** — Expose ports explicitly when needed
 
 ### DevPod
 
-- **Client-managed** - Runs on your infrastructure
-- **Can access host Docker** - Depending on setup
-- **Flexible** - Configure based on your needs
-
-## Why Deployment Targets?
-
-The target system ensures you get warnings about incompatibilities before deploying. This prevents:
-
-- Wasted time debugging environment-specific issues
-- Confusion about why overlays don't work in cloud IDEs
-- Having to manually research compatibility
+- **Client-managed** — Runs on your infrastructure (local Docker, cloud VM, etc.)
+- **Can access host Docker** — Depending on provider configuration
+- **Flexible** — Provider chosen at `devpod up` time, not at generation time
 
 ## Configuration
 
-Target configurations are stored in `overlays/.registry/deployment-targets.yml`. To add a new target, simply add an entry to this file:
+Deployment target configurations (compatibility rules, port forwarding defaults) are stored in
+`overlays/.registry/deployment-targets.yml`. To add a new target entry:
 
 ```yaml
 - id: new-target
@@ -144,6 +174,8 @@ Target configurations are stored in `overlays/.registry/deployment-targets.yml`.
       supportsPrivileged: true
 ```
 
+Target-specific file generation rules are implemented in `tool/schema/target-rules.ts`.
+
 ## See Also
 
 - [Discovery Commands](discovery-commands.md) - Explore overlays before generating

package/docs/examples.md

@@ -19,9 +19,11 @@ language:
 database:
     - postgres
 outputPath: ./.devcontainer
+env:
+    APP_ENV: development
 customizations:
-    environment:
-        APP_ENV: development
+    envTemplate:
+        POSTGRES_PASSWORD: postgres
     devcontainerPatch:
         features:
             ghcr.io/devcontainers-extra/features/apt-get-packages:1:
@@ -171,24 +173,25 @@ All examples produce:
 
 ## Customization After Generation
 
-The output is plain JSON - edit directly:
+Prefer editing `superposition.yml` and regenerating:
 
-```jsonc
-// .devcontainer/devcontainer.json
-{
-    "name": "My Custom Name", // Change this
-    "features": {
-        // Add/remove features
-        "ghcr.io/devcontainers/features/go:1": {},
-    },
-    "forwardPorts": [3000, 8080], // Adjust ports
-    "remoteEnv": {
-        "MY_VAR": "value", // Add environment variables
-    },
-}
+```yaml
+# superposition.yml
+containerName: My Custom Name
+env:
+    MY_VAR: value
+customizations:
+    devcontainerPatch:
+        forwardPorts:
+            - 3000
+            - 8080
 ```
 
-The tool gets you started—you customize from there.
+Then regenerate:
+
+```bash
+npx container-superposition regen
+```
 
 ## Help and Documentation
 

package/docs/filesystem-contract.md

@@ -11,6 +11,9 @@ your-project/
 │   ├── docker-compose.yml       # Services (compose stack only)
 │   ├── .env.example             # Environment variable templates
 │   ├── ports.json               # Port documentation and connection strings
+│   ├── CODESPACES.md            # Codespaces setup guidance (--target codespaces only)
+│   ├── GITPOD.md                # Gitpod setup guidance (--target gitpod only)
+│   ├── DEVPOD.md                # DevPod setup guidance (--target devpod only)
 │   ├── scripts/                 # Setup and verification scripts
 │   │   ├── post-create.sh       # Runs once when container is created
 │   │   └── post-start.sh        # Runs every time container starts
@@ -18,6 +21,8 @@ your-project/
 │       ├── devcontainer.patch.json
 │       └── docker-compose.patch.yml
 ├── superposition.json           # Manifest file (enables regeneration)
+├── .gitpod.yml                  # Gitpod workspace config (--target gitpod only)
+├── devpod.yaml                  # DevPod workspace descriptor (--target devpod only)
 └── .devcontainer.backup-*/      # Automatic backups (gitignored)
 ```
 

package/docs/minimal-and-editor.md

@@ -86,7 +86,7 @@ container-superposition init --editor vscode
 # None - CLI-only, no editor customizations
 container-superposition init --editor none
 
-# JetBrains - Skip VS Code customizations (reserved for future JetBrains support)
+# JetBrains - Generate .idea/ project settings and run configurations
 container-superposition init --editor jetbrains
 ```
 
@@ -126,15 +126,61 @@ Removes all editor customizations. Useful for:
 
 #### jetbrains
 
-Removes VS Code customizations. Reserved for future JetBrains-specific settings (Gateway, Fleet, etc.).
+Generates JetBrains IDE project artifacts and sets the appropriate IDE backend in
+`devcontainer.json`. VS Code customizations are removed.
 
 ```json
 {
-    // No vscode customizations
-    // Future: JetBrains-specific settings could be added here
+    "customizations": {
+        "jetbrains": {
+            "backend": "WebStorm"
+        }
+    }
 }
 ```
 
+The `backend` value is automatically selected based on the primary language overlay:
+
+| Language overlay          | JetBrains IDE                     |
+| ------------------------- | --------------------------------- |
+| `nodejs` / `bun`          | `WebStorm`                        |
+| `python` / `mkdocs`       | `PyCharm`                         |
+| `go`                      | `GoLand`                          |
+| `dotnet`                  | `Rider`                           |
+| `java`                    | `IntelliJIdea`                    |
+| `rust`                    | `RustRover`                       |
+| none / multiple / unknown | `IntelliJIdea` (generic fallback) |
+
+##### Generated artifacts
+
+In addition to the `devcontainer.json` update, enabling JetBrains support generates the
+following files in the **project root** (the parent of `.devcontainer/`):
+
+```
+.idea/
+  .gitignore                        # shared workspace entries committed to VCS
+  runConfigurations/
+    npm_dev.xml                     # Node.js — npm run dev
+    python_main.xml                 # Python — python main.py
+    go_run.xml                      # Go — go run ./...
+    dotnet_run.xml                  # .NET — dotnet run
+    java_run.xml                    # Java — Application run
+    rust_run.xml                    # Rust — cargo run
+```
+
+Only run configuration files matching the selected language overlays are created.
+
+##### Existing `.idea/` directory
+
+If `.idea/` already exists (e.g., from a previous generation or user customisation),
+existing files are **never overwritten**. Only files that are missing are written.
+
+##### Regenerating with a different editor profile
+
+If you later regenerate with `--editor vscode` after a JetBrains generation, the `.idea/`
+directory is **not removed** — it may contain user-created configurations. Switch back
+to `--editor jetbrains` if you want to add new run configurations.
+
 ### When to Use Editor Profiles
 
 **Terminal Workflows:**
@@ -187,7 +233,7 @@ container-superposition regen --minimal
 
 # Step 3: Or regenerate for a different editor
 container-superposition regen --editor jetbrains
-# Removes VS Code customizations
+# Adds JetBrains customizations and generates .idea/ artifacts
 
 # Step 4: Or both together
 container-superposition regen --minimal --editor none
@@ -237,6 +283,20 @@ container-superposition init \
 
 **Result:** Lean Codespaces environment with essential tools and VS Code extensions.
 
+### JetBrains IDE Setup
+
+```bash
+container-superposition init \
+  --editor jetbrains \
+  --stack compose \
+  --language nodejs \
+  --database postgres
+```
+
+**Result:** Node.js + PostgreSQL workspace with `.idea/` project settings, a `WebStorm`
+backend in `devcontainer.json`, and an `npm run dev` run configuration ready to use. No
+VS Code extensions included.
+
 ## Manifest Support
 
 Both settings are stored in `superposition.json`: