container-superposition 0.1.9 → 0.1.11

package/tool/schema/config.schema.json

@@ -83,6 +83,7 @@
                     "otel-demo-nodejs",
                     "otel-demo-python",
                     "pandoc",
+                    "pi",
                     "playwright",
                     "postgres",
                     "powershell",
@@ -199,7 +200,8 @@
                     "gemini-cli",
                     "amp",
                     "windsurf-cli",
-                    "opencode"
+                    "opencode",
+                    "pi"
                 ]
             },
             "default": [],
@@ -272,6 +274,41 @@
                 ]
             }
         },
+        "mounts": {
+            "description": "Project-level mount specs routed to devcontainer.json mounts or docker-compose volumes based on stack/target",
+            "oneOf": [
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/projectMountEntry"
+                    }
+                },
+                {
+                    "type": "object",
+                    "description": "Named mount map form",
+                    "additionalProperties": {
+                        "$ref": "#/$defs/projectMountObject"
+                    }
+                }
+            ]
+        },
+        "shell": {
+            "type": "object",
+            "description": "Shell profile customizations written via a managed shell-init hook",
+            "properties": {
+                "aliases": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" },
+                    "description": "Alias name -> command map (e.g. k: kubectl)"
+                },
+                "snippets": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Raw shell snippets appended to generated shell-init"
+                }
+            },
+            "additionalProperties": false
+        },
         "customizations": {
             "type": "object",
             "properties": {
@@ -328,5 +365,43 @@
         }
     },
     "required": [],
-    "additionalProperties": false
+    "additionalProperties": false,
+    "$defs": {
+        "projectMountTarget": {
+            "type": "string",
+            "enum": ["auto", "devcontainerMount", "composeVolume"]
+        },
+        "projectMountObject": {
+            "type": "object",
+            "properties": {
+                "value": {
+                    "type": "string",
+                    "description": "Raw mount spec string (escape hatch)"
+                },
+                "source": { "type": "string", "description": "Mount source path or volume name" },
+                "destination": { "type": "string", "description": "Container destination path" },
+                "type": { "type": "string", "enum": ["bind", "volume", "tmpfs"] },
+                "consistency": { "type": "string", "enum": ["consistent", "cached", "delegated"] },
+                "cached": {
+                    "type": "boolean",
+                    "description": "Convenience alias for consistency: cached"
+                },
+                "readOnly": { "type": "boolean" },
+                "target": { "$ref": "#/$defs/projectMountTarget" }
+            },
+            "additionalProperties": false,
+            "oneOf": [{ "required": ["value"] }, { "required": ["source", "destination"] }]
+        },
+        "projectMountEntry": {
+            "oneOf": [
+                {
+                    "type": "string",
+                    "description": "Raw mount spec string"
+                },
+                {
+                    "$ref": "#/$defs/projectMountObject"
+                }
+            ]
+        }
+    }
 }

package/tool/schema/superposition.schema.json

@@ -0,0 +1,569 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://raw.githubusercontent.com/veggerby/container-superposition/main/tool/schema/superposition.schema.json",
+    "title": "Superposition Project Configuration",
+    "description": "Schema for superposition.yml / .superposition.yml — the project configuration file for container-superposition. See https://github.com/veggerby/container-superposition for documentation.",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "JSON Schema reference URI"
+        },
+        "stack": {
+            "type": "string",
+            "enum": ["plain", "compose"],
+            "description": "Base devcontainer template: plain (single image) or compose (multi-service Docker Compose)"
+        },
+        "baseImage": {
+            "type": "string",
+            "enum": ["bookworm", "trixie", "alpine", "ubuntu", "custom"],
+            "description": "Base OS image. Use \"custom\" together with customImage to specify an arbitrary image.",
+            "default": "bookworm"
+        },
+        "customImage": {
+            "type": "string",
+            "description": "Fully-qualified Docker image reference. Only valid when baseImage is \"custom\".",
+            "examples": ["ghcr.io/myorg/my-base:latest"]
+        },
+        "containerName": {
+            "type": "string",
+            "description": "Sets the \"name\" field in devcontainer.json (displayed by VS Code)",
+            "examples": ["My Web API"]
+        },
+        "overlays": {
+            "type": "array",
+            "description": "Flat list of overlay IDs to include. Preferred over the legacy category arrays. Dependency resolution runs automatically.",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "alertmanager",
+                    "all",
+                    "amp",
+                    "ansible",
+                    "argocd",
+                    "aws-cli",
+                    "azure-cli",
+                    "bun",
+                    "claude-code",
+                    "cloudflared",
+                    "codex",
+                    "comfyui",
+                    "commitlint",
+                    "cuda",
+                    "devcontainer-cli",
+                    "direnv",
+                    "docker-in-docker",
+                    "docker-sock",
+                    "dotnet",
+                    "duckdb",
+                    "fuseki",
+                    "gcloud",
+                    "gemini-cli",
+                    "git-helpers",
+                    "go",
+                    "grafana",
+                    "grpc-tools",
+                    "jaeger",
+                    "java",
+                    "jupyter",
+                    "just",
+                    "k3d",
+                    "keycloak",
+                    "kind",
+                    "kubectl-helm",
+                    "localstack",
+                    "loki",
+                    "mailpit",
+                    "minio",
+                    "mkdocs",
+                    "mkdocs2",
+                    "modern-cli-tools",
+                    "mongodb",
+                    "mysql",
+                    "nats",
+                    "ngrok",
+                    "nodejs",
+                    "ollama",
+                    "ollama-cli",
+                    "open-webui",
+                    "openapi-tools",
+                    "opencode",
+                    "otel-collector",
+                    "otel-demo-nodejs",
+                    "otel-demo-python",
+                    "pandoc",
+                    "pgvector",
+                    "pi",
+                    "playwright",
+                    "postgres",
+                    "powershell",
+                    "pre-commit",
+                    "prometheus",
+                    "promtail",
+                    "pulumi",
+                    "python",
+                    "qdrant",
+                    "rabbitmq",
+                    "redis",
+                    "redpanda",
+                    "rocm",
+                    "rust",
+                    "skaffold",
+                    "spec-kit",
+                    "sqlite",
+                    "sqlserver",
+                    "task",
+                    "tempo",
+                    "terraform",
+                    "tilt",
+                    "windsurf-cli"
+                ],
+                "description": "Overlay identifier"
+            },
+            "uniqueItems": true
+        },
+        "preset": {
+            "type": "string",
+            "enum": [
+                "data-engineering",
+                "docs-site",
+                "event-sourced-service",
+                "frontend",
+                "full-observability",
+                "fullstack",
+                "k8s-dev",
+                "k8s-operator-dev",
+                "local-llm",
+                "microservice",
+                "sdd",
+                "vector-ai",
+                "web-api"
+            ],
+            "description": "ID of a preset (meta-overlay) to expand. Use cs list --presets to browse available presets."
+        },
+        "presetChoices": {
+            "type": "object",
+            "description": "Parameter values passed to the selected preset. Keys depend on the preset definition.",
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
+        "outputPath": {
+            "type": "string",
+            "description": "Where to write the generated devcontainer files. Default: .devcontainer",
+            "default": "./.devcontainer",
+            "examples": ["./.devcontainer"]
+        },
+        "portOffset": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Shift all overlay-declared host ports by this integer. Useful for running multiple instances on one machine.",
+            "examples": [100, 200]
+        },
+        "target": {
+            "type": "string",
+            "enum": ["local", "codespaces", "gitpod", "devpod"],
+            "description": "Deployment target profile. Applies environment-specific patches during generation."
+        },
+        "minimal": {
+            "type": "boolean",
+            "description": "When true, overlays marked with minimal: true in their overlay.yml are excluded. Useful for CI environments."
+        },
+        "editor": {
+            "type": "string",
+            "enum": ["vscode", "jetbrains", "none"],
+            "description": "Editor profile: vscode (default, includes extensions/settings), jetbrains (removes VS Code config), none (removes VS Code config)",
+            "default": "vscode"
+        },
+        "env": {
+            "type": "object",
+            "description": "Runtime environment variables. Routed to devcontainer.json remoteEnv or docker-compose environment based on stack and target.",
+            "additionalProperties": {
+                "oneOf": [
+                    {
+                        "type": "string",
+                        "description": "String shorthand — target is auto-detected based on stack (plain→remoteEnv, compose→docker-compose environment)"
+                    },
+                    {
+                        "type": "object",
+                        "description": "Long form with explicit routing target",
+                        "required": ["value"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "value": {
+                                "type": "string",
+                                "description": "Variable value (supports ${VAR} and ${VAR:-default} syntax)"
+                            },
+                            "target": {
+                                "type": "string",
+                                "enum": ["auto", "remoteEnv", "composeEnv"],
+                                "description": "auto (default): plain→remoteEnv, compose→docker-compose environment; remoteEnv: always devcontainer.json; composeEnv: always docker-compose (compose only)",
+                                "default": "auto"
+                            }
+                        }
+                    }
+                ]
+            }
+        },
+        "mounts": {
+            "oneOf": [
+                {
+                    "type": "array",
+                    "description": "List of filesystem mounts",
+                    "items": {
+                        "oneOf": [
+                            {
+                                "type": "string",
+                                "description": "Raw mount string (escape hatch)",
+                                "minLength": 1
+                            },
+                            {
+                                "type": "object",
+                                "description": "Structured mount using source/destination fields",
+                                "required": ["source", "destination"],
+                                "additionalProperties": false,
+                                "properties": {
+                                    "source": {
+                                        "type": "string",
+                                        "description": "Mount source path or volume name"
+                                    },
+                                    "destination": {
+                                        "type": "string",
+                                        "description": "Mount destination path inside the container"
+                                    },
+                                    "type": {
+                                        "type": "string",
+                                        "enum": ["bind", "volume", "tmpfs"],
+                                        "description": "Mount type (default: bind)"
+                                    },
+                                    "consistency": {
+                                        "type": "string",
+                                        "enum": ["consistent", "cached", "delegated"],
+                                        "description": "Mount consistency mode"
+                                    },
+                                    "cached": {
+                                        "type": "boolean",
+                                        "description": "Shorthand for consistency: cached"
+                                    },
+                                    "readOnly": {
+                                        "type": "boolean",
+                                        "description": "Make the mount read-only"
+                                    },
+                                    "target": {
+                                        "type": "string",
+                                        "enum": ["auto", "devcontainerMount", "composeVolume"],
+                                        "description": "Routing target: auto (default) always routes to devcontainer.json mounts[]; composeVolume routes to docker-compose volumes (compose stack only)",
+                                        "default": "auto"
+                                    }
+                                }
+                            },
+                            {
+                                "type": "object",
+                                "description": "Raw-value mount with optional routing target",
+                                "required": ["value"],
+                                "additionalProperties": false,
+                                "properties": {
+                                    "value": {
+                                        "type": "string",
+                                        "description": "Raw mount string",
+                                        "minLength": 1
+                                    },
+                                    "target": {
+                                        "type": "string",
+                                        "enum": ["auto", "devcontainerMount", "composeVolume"],
+                                        "description": "Routing target override",
+                                        "default": "auto"
+                                    }
+                                }
+                            }
+                        ]
+                    }
+                },
+                {
+                    "type": "object",
+                    "description": "Named map of filesystem mounts",
+                    "additionalProperties": {
+                        "type": "object",
+                        "description": "Structured mount (named form; name is not serialized back)",
+                        "required": ["source", "destination"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "source": {
+                                "type": "string"
+                            },
+                            "destination": {
+                                "type": "string"
+                            },
+                            "type": {
+                                "type": "string",
+                                "enum": ["bind", "volume", "tmpfs"]
+                            },
+                            "consistency": {
+                                "type": "string",
+                                "enum": ["consistent", "cached", "delegated"]
+                            },
+                            "cached": {
+                                "type": "boolean"
+                            },
+                            "readOnly": {
+                                "type": "boolean"
+                            },
+                            "target": {
+                                "type": "string",
+                                "enum": ["auto", "devcontainerMount", "composeVolume"]
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        "shell": {
+            "type": "object",
+            "description": "Declarative shell profile customizations (aliases and snippets). Use env for environment variables.",
+            "additionalProperties": false,
+            "properties": {
+                "aliases": {
+                    "type": "object",
+                    "description": "Shell aliases written to .devcontainer/scripts/shell-init.sh",
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "examples": [
+                        {
+                            "k": "kubectl",
+                            "kgp": "kubectl get pods"
+                        }
+                    ]
+                },
+                "snippets": {
+                    "type": "array",
+                    "description": "Shell snippet lines appended to shell-init.sh. Guard shell-specific syntax with $BASH_VERSION / $ZSH_VERSION.",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "customizations": {
+            "type": "object",
+            "description": "Inline patches applied during generation (equivalent to .devcontainer/custom/ patches).",
+            "additionalProperties": false,
+            "properties": {
+                "devcontainerPatch": {
+                    "type": "object",
+                    "description": "Deep-merged into devcontainer.json after all overlays are applied"
+                },
+                "dockerComposePatch": {
+                    "type": "object",
+                    "description": "Deep-merged into docker-compose.yml after all overlays are applied (compose stack only)"
+                },
+                "envTemplate": {
+                    "type": "object",
+                    "description": "Key/value pairs written to .devcontainer/.env.example",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "environment": {
+                    "type": "object",
+                    "description": "Alias for envTemplate (deprecated; prefer envTemplate)",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "scripts": {
+                    "type": "object",
+                    "description": "Shell commands appended to postCreate / postStart hooks",
+                    "additionalProperties": false,
+                    "properties": {
+                        "postCreate": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            },
+                            "description": "Commands run once after container creation (postCreateCommand)"
+                        },
+                        "postStart": {
+                            "type": "array",
+                            "items": {
+                                "type": "string"
+                            },
+                            "description": "Commands run each time the container starts (postStartCommand)"
+                        }
+                    }
+                },
+                "files": {
+                    "type": "array",
+                    "description": "Extra files to write into the output directory",
+                    "items": {
+                        "type": "object",
+                        "required": ["path", "content"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "path": {
+                                "type": "string",
+                                "description": "Destination path"
+                            },
+                            "content": {
+                                "type": "string",
+                                "description": "File content"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "parameters": {
+            "type": "object",
+            "description": "Overlay parameter values. Keys correspond to parameters declared in overlay.yml. Values substitute {{cs.KEY}} tokens throughout generated files.",
+            "additionalProperties": {
+                "oneOf": [
+                    {
+                        "type": "string"
+                    },
+                    {
+                        "type": "number"
+                    }
+                ],
+                "description": "Parameter value (strings and numbers are both accepted)"
+            }
+        },
+        "language": {
+            "type": "array",
+            "description": "Deprecated — use overlays: [...] instead",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "bun",
+                    "dotnet",
+                    "go",
+                    "java",
+                    "jupyter",
+                    "nodejs",
+                    "powershell",
+                    "python",
+                    "rust"
+                ]
+            },
+            "deprecated": true
+        },
+        "database": {
+            "type": "array",
+            "description": "Deprecated — use overlays: [...] instead",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "duckdb",
+                    "fuseki",
+                    "minio",
+                    "mongodb",
+                    "mysql",
+                    "nats",
+                    "pgvector",
+                    "postgres",
+                    "qdrant",
+                    "rabbitmq",
+                    "redis",
+                    "redpanda",
+                    "sqlite",
+                    "sqlserver"
+                ]
+            },
+            "deprecated": true
+        },
+        "observability": {
+            "type": "array",
+            "description": "Deprecated — use overlays: [...] instead",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "alertmanager",
+                    "grafana",
+                    "jaeger",
+                    "loki",
+                    "otel-collector",
+                    "otel-demo-nodejs",
+                    "otel-demo-python",
+                    "prometheus",
+                    "promtail",
+                    "tempo"
+                ]
+            },
+            "deprecated": true
+        },
+        "cloudTools": {
+            "type": "array",
+            "description": "Deprecated — use overlays: [...] instead",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "ansible",
+                    "argocd",
+                    "aws-cli",
+                    "azure-cli",
+                    "gcloud",
+                    "k3d",
+                    "kind",
+                    "kubectl-helm",
+                    "localstack",
+                    "pulumi",
+                    "terraform"
+                ]
+            },
+            "deprecated": true
+        },
+        "devTools": {
+            "type": "array",
+            "description": "Deprecated — use overlays: [...] instead",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "all",
+                    "amp",
+                    "claude-code",
+                    "cloudflared",
+                    "codex",
+                    "comfyui",
+                    "commitlint",
+                    "cuda",
+                    "devcontainer-cli",
+                    "direnv",
+                    "docker-in-docker",
+                    "docker-sock",
+                    "gemini-cli",
+                    "git-helpers",
+                    "grpc-tools",
+                    "just",
+                    "keycloak",
+                    "mailpit",
+                    "mkdocs",
+                    "mkdocs2",
+                    "modern-cli-tools",
+                    "ngrok",
+                    "ollama",
+                    "ollama-cli",
+                    "open-webui",
+                    "openapi-tools",
+                    "opencode",
+                    "pandoc",
+                    "pi",
+                    "playwright",
+                    "pre-commit",
+                    "rocm",
+                    "skaffold",
+                    "spec-kit",
+                    "task",
+                    "tilt",
+                    "windsurf-cli"
+                ]
+            },
+            "deprecated": true
+        },
+        "playwright": {
+            "type": "boolean",
+            "description": "Deprecated — use overlays: [playwright] instead",
+            "deprecated": true
+        }
+    }
+}