container-superposition 0.1.7 → 0.1.9

package/dist/tool/utils/parameters.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Overlay parameter resolution and {{cs.PARAM_NAME}} substitution engine.
+ *
+ * Syntax: {{cs.PARAM_NAME}} — chosen because it:
+ *  - does NOT collide with Docker Compose ${VAR} / ${VAR:-default}
+ *  - does NOT collide with shell $VAR / ${VAR} / ${VAR:-x}
+ *  - does NOT collide with VS Code ${localWorkspaceFolder} / ${env:VAR}
+ *  - does NOT collide with GitHub Actions ${{ github.* }}
+ *  - is consistent with the existing preset {{parameters.<key>.id}} convention
+ *
+ * This module deliberately has NO parser, NO AST, NO conditionals.
+ * If string.replace() can't do it, it doesn't belong here.
+ */
+import type { OverlayMetadata, OverlayParameterDefinition } from '../schema/types.js';
+/**
+ * A parameter declaration enriched with the overlay that declared it.
+ */
+export interface DeclaredParameter extends OverlayParameterDefinition {
+    overlayId: string;
+}
+/**
+ * Result of parameter resolution.
+ */
+export interface ResolvedParameters {
+    /** Key → resolved value map ready for substitution. */
+    values: Record<string, string>;
+    /** Parameters that are required but have no value — generation must fail. */
+    missingRequired: string[];
+    /** User-supplied parameter keys not declared by any selected overlay (warnings only). */
+    unknownSupplied: string[];
+}
+/**
+ * Collect all parameter declarations from the selected overlay set.
+ * Returns a map of parameter name → declaration enriched with the declaring overlay.
+ *
+ * When two overlays declare the same parameter name, the first declaration wins
+ * (overlays are processed in composition order).
+ */
+export declare function collectOverlayParameters(overlayIds: string[], allOverlayDefs: OverlayMetadata[]): Record<string, DeclaredParameter>;
+/**
+ * Resolve parameter values by applying the resolution order:
+ *   1. Supplied values (from project file or CLI — highest priority)
+ *   2. Overlay defaults (lowest priority)
+ *
+ * Returns resolved values, any missing-required errors, and unknown-supplied warnings.
+ */
+export declare function resolveParameters(declared: Record<string, DeclaredParameter>, supplied: Record<string, string>): ResolvedParameters;
+/**
+ * Replace all {{cs.KEY}} tokens in `content` with the corresponding resolved value.
+ * Tokens for keys not present in `resolved` are left intact (to be caught by validation).
+ *
+ * Docker Compose ${VAR}, shell $VAR, VS Code ${env:VAR}, and GitHub Actions ${{ }}
+ * expressions are NEVER touched — only the {{cs.KEY}} pattern is matched.
+ */
+export declare function substituteParameters(content: string, resolved: Record<string, string>): string;
+/**
+ * Recursively substitute {{cs.KEY}} tokens in all string fields of an object.
+ * This is preferred over substituting into JSON.stringify() output because it
+ * avoids producing invalid JSON when parameter values contain JSON-special
+ * characters (quotes, backslashes, newlines, etc.).
+ *
+ * Non-string values (numbers, booleans, arrays, nested objects) are traversed
+ * but their non-string leaves are returned unchanged.
+ */
+export declare function substituteParametersInObject(obj: unknown, resolved: Record<string, string>): unknown;
+/**
+ * Validate that no unresolved {{cs.*}} tokens remain in `content`.
+ * Returns a list of unresolved token strings (empty = valid).
+ */
+export declare function findUnresolvedTokens(content: string): string[];
+/**
+ * Redact sensitive parameter values for display (e.g. in plan output).
+ * Non-sensitive values are returned as-is.
+ */
+export declare function redactSensitiveValues(values: Record<string, string>, declared: Record<string, DeclaredParameter>): Record<string, string>;
+//# sourceMappingURL=parameters.d.ts.map

package/dist/tool/utils/parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../../tool/utils/parameters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAKtF;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,0BAA0B;IACjE,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,yFAAyF;IACzF,eAAe,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,MAAM,EAAE,EACpB,cAAc,EAAE,eAAe,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAgBnC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,kBAAkB,CAmBpB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CACxC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,OAAO,CAeT;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ9D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC5C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}

package/dist/tool/utils/parameters.js

@@ -0,0 +1,125 @@
+/**
+ * Overlay parameter resolution and {{cs.PARAM_NAME}} substitution engine.
+ *
+ * Syntax: {{cs.PARAM_NAME}} — chosen because it:
+ *  - does NOT collide with Docker Compose ${VAR} / ${VAR:-default}
+ *  - does NOT collide with shell $VAR / ${VAR} / ${VAR:-x}
+ *  - does NOT collide with VS Code ${localWorkspaceFolder} / ${env:VAR}
+ *  - does NOT collide with GitHub Actions ${{ github.* }}
+ *  - is consistent with the existing preset {{parameters.<key>.id}} convention
+ *
+ * This module deliberately has NO parser, NO AST, NO conditionals.
+ * If string.replace() can't do it, it doesn't belong here.
+ */
+/** Regex matching ALL {{cs.KEY}} tokens (used for substitution and validation). */
+const CS_PARAM_REGEX = /\{\{cs\.([A-Z0-9_]+)\}\}/g;
+/**
+ * Collect all parameter declarations from the selected overlay set.
+ * Returns a map of parameter name → declaration enriched with the declaring overlay.
+ *
+ * When two overlays declare the same parameter name, the first declaration wins
+ * (overlays are processed in composition order).
+ */
+export function collectOverlayParameters(overlayIds, allOverlayDefs) {
+    const declared = {};
+    const overlayById = new Map(allOverlayDefs.map((o) => [o.id, o]));
+    for (const id of overlayIds) {
+        const overlay = overlayById.get(id);
+        if (!overlay?.parameters)
+            continue;
+        for (const [key, def] of Object.entries(overlay.parameters)) {
+            if (!(key in declared)) {
+                declared[key] = { ...def, overlayId: id };
+            }
+        }
+    }
+    return declared;
+}
+/**
+ * Resolve parameter values by applying the resolution order:
+ *   1. Supplied values (from project file or CLI — highest priority)
+ *   2. Overlay defaults (lowest priority)
+ *
+ * Returns resolved values, any missing-required errors, and unknown-supplied warnings.
+ */
+export function resolveParameters(declared, supplied) {
+    const values = {};
+    const missingRequired = [];
+    // Resolve each declared parameter
+    for (const [key, def] of Object.entries(declared)) {
+        if (key in supplied) {
+            values[key] = supplied[key];
+        }
+        else if (def.default !== undefined) {
+            values[key] = def.default;
+        }
+        else {
+            missingRequired.push(key);
+        }
+    }
+    // Identify unknown supplied parameters (not declared by any overlay)
+    const unknownSupplied = Object.keys(supplied).filter((key) => !(key in declared));
+    return { values, missingRequired, unknownSupplied };
+}
+/**
+ * Replace all {{cs.KEY}} tokens in `content` with the corresponding resolved value.
+ * Tokens for keys not present in `resolved` are left intact (to be caught by validation).
+ *
+ * Docker Compose ${VAR}, shell $VAR, VS Code ${env:VAR}, and GitHub Actions ${{ }}
+ * expressions are NEVER touched — only the {{cs.KEY}} pattern is matched.
+ */
+export function substituteParameters(content, resolved) {
+    return content.replace(CS_PARAM_REGEX, (match, key) => {
+        return key in resolved ? resolved[key] : match;
+    });
+}
+/**
+ * Recursively substitute {{cs.KEY}} tokens in all string fields of an object.
+ * This is preferred over substituting into JSON.stringify() output because it
+ * avoids producing invalid JSON when parameter values contain JSON-special
+ * characters (quotes, backslashes, newlines, etc.).
+ *
+ * Non-string values (numbers, booleans, arrays, nested objects) are traversed
+ * but their non-string leaves are returned unchanged.
+ */
+export function substituteParametersInObject(obj, resolved) {
+    if (typeof obj === 'string') {
+        return substituteParameters(obj, resolved);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => substituteParametersInObject(item, resolved));
+    }
+    if (obj !== null && typeof obj === 'object') {
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = substituteParametersInObject(v, resolved);
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Validate that no unresolved {{cs.*}} tokens remain in `content`.
+ * Returns a list of unresolved token strings (empty = valid).
+ */
+export function findUnresolvedTokens(content) {
+    const found = [];
+    let match;
+    const regex = new RegExp(CS_PARAM_REGEX.source, 'g');
+    while ((match = regex.exec(content)) !== null) {
+        found.push(match[0]);
+    }
+    return found;
+}
+/**
+ * Redact sensitive parameter values for display (e.g. in plan output).
+ * Non-sensitive values are returned as-is.
+ */
+export function redactSensitiveValues(values, declared) {
+    const result = {};
+    for (const [key, value] of Object.entries(values)) {
+        result[key] = declared[key]?.sensitive ? '***' : value;
+    }
+    return result;
+}
+//# sourceMappingURL=parameters.js.map

package/dist/tool/utils/parameters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameters.js","sourceRoot":"","sources":["../../../tool/utils/parameters.ts"],"names":[],"mappings":"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"}

package/dist/tool/utils/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveRepoPath(relativePath: string, anchor: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/tool/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../tool/utils/paths.ts"],"names":[],"mappings":"AAiBA,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAiB5E"}

package/dist/tool/utils/paths.js

@@ -0,0 +1,31 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Resolve a repo-relative path from an anchor directory, handling both
+ * source (scripts/) and compiled (dist/scripts/) locations.
+ *
+ * Walks up from the anchor directory collecting candidate paths:
+ * anchor/relative, anchor/../relative, anchor/../../relative, ...
+ * Returns the first that exists, or the first candidate as a fallback.
+ */
+// Maximum number of parent directories to walk up when searching for repo-relative paths.
+// 5 levels is sufficient to cover source (<repo>/tool/questionnaire) and compiled
+// (<repo>/dist/tool/questionnaire) layouts without walking too far up the filesystem.
+const MAX_DIRECTORY_WALK_DEPTH = 5;
+export function resolveRepoPath(relativePath, anchor) {
+    const candidates = [];
+    let currentAnchor = anchor;
+    // Walk up from the anchor directory, collecting candidate paths like:
+    // anchor/relative, anchor/../relative, anchor/../../relative, ...
+    // Stop after MAX_DIRECTORY_WALK_DEPTH levels or when reaching the filesystem root.
+    for (let i = 0; i < MAX_DIRECTORY_WALK_DEPTH; i++) {
+        candidates.push(path.join(currentAnchor, relativePath));
+        const parent = path.dirname(currentAnchor);
+        if (parent === currentAnchor) {
+            break;
+        }
+        currentAnchor = parent;
+    }
+    return candidates.find((c) => fs.existsSync(c)) ?? candidates[0];
+}
+//# sourceMappingURL=paths.js.map

package/dist/tool/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../tool/utils/paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;GAOG;AAEH,0FAA0F;AAC1F,kFAAkF;AAClF,sFAAsF;AACtF,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC,MAAM,UAAU,eAAe,CAAC,YAAoB,EAAE,MAAc;IAChE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,aAAa,GAAG,MAAM,CAAC;IAE3B,sEAAsE;IACtE,kEAAkE;IAClE,mFAAmF;IACnF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,wBAAwB,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC3C,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;YAC3B,MAAM;QACV,CAAC;QACD,aAAa,GAAG,MAAM,CAAC;IAC3B,CAAC;IAED,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC"}

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`: