container-superposition 0.1.1 → 0.1.4

package/docs/overlays.md

@@ -53,6 +53,18 @@ Eclipse Temurin JDK 21 with Maven and Gradle
 | **Tags**     | `language`, `java`, `maven`, `gradle` |
 | **Ports**    | 8080, 8081                            |
 
+### Jupyter (`jupyter`)
+
+Jupyter notebook server for interactive computing and data science
+
+| Property     | Value                                                       |
+| ------------ | ----------------------------------------------------------- |
+| **Category** | language                                                    |
+| **Supports** | compose                                                     |
+| **Requires** | `python`                                                    |
+| **Tags**     | `language`, `jupyter`, `python`, `notebook`, `data-science` |
+| **Ports**    | 8888                                                        |
+
 ### MkDocs (`mkdocs`)
 
 Material for MkDocs - professional documentation generator
@@ -103,6 +115,16 @@ Rust stable with cargo, rustfmt, and clippy
 
 ## Database Overlays
 
+### DuckDB (`duckdb`)
+
+In-process analytical database for OLAP workloads
+
+| Property     | Value                                            |
+| ------------ | ------------------------------------------------ |
+| **Category** | database                                         |
+| **Suggests** | `python`, `jupyter`                              |
+| **Tags**     | `database`, `analytics`, `sql`, `duckdb`, `olap` |
+
 ### MinIO (`minio`)
 
 S3-compatible object storage with web console
@@ -123,18 +145,18 @@ MongoDB 8 with Mongo Express web UI
 | **Category** | database                                   |
 | **Supports** | compose                                    |
 | **Tags**     | `database`, `nosql`, `mongodb`, `document` |
-| **Ports**    | 27017, 8081                                |
+| **Ports**    | [object Object], [object Object]           |
 
 ### MySQL (`mysql`)
 
 MySQL 8 with phpMyAdmin web UI
 
-| Property     | Value                      |
-| ------------ | -------------------------- |
-| **Category** | database                   |
-| **Supports** | compose                    |
-| **Tags**     | `database`, `sql`, `mysql` |
-| **Ports**    | 3306, 8080                 |
+| Property     | Value                            |
+| ------------ | -------------------------------- |
+| **Category** | database                         |
+| **Supports** | compose                          |
+| **Tags**     | `database`, `sql`, `mysql`       |
+| **Ports**    | [object Object], [object Object] |
 
 ### NATS (`nats`)
 
@@ -145,7 +167,7 @@ Lightweight pub/sub messaging with JetStream
 | **Category** | database                                               |
 | **Supports** | compose                                                |
 | **Tags**     | `database`, `messaging`, `pubsub`, `nats`, `jetstream` |
-| **Ports**    | 4222, 8222                                             |
+| **Ports**    | [object Object], [object Object]                       |
 
 ### PostgreSQL (`postgres`)
 
@@ -156,7 +178,7 @@ PostgreSQL 16 database
 | **Category** | database                      |
 | **Supports** | compose                       |
 | **Tags**     | `database`, `sql`, `postgres` |
-| **Ports**    | 5432                          |
+| **Ports**    | [object Object]               |
 
 ### RabbitMQ (`rabbitmq`)
 
@@ -167,7 +189,7 @@ Message broker with AMQP protocol and management UI
 | **Category** | database                                             |
 | **Supports** | compose                                              |
 | **Tags**     | `database`, `messaging`, `queue`, `rabbitmq`, `amqp` |
-| **Ports**    | 5672, 15672                                          |
+| **Ports**    | [object Object], [object Object]                     |
 
 ### Redis (`redis`)
 
@@ -178,7 +200,7 @@ Redis 7 cache
 | **Category** | database                     |
 | **Supports** | compose                      |
 | **Tags**     | `database`, `cache`, `redis` |
-| **Ports**    | 6379                         |
+| **Ports**    | [object Object]              |
 
 ### Redpanda (`redpanda`)
 
@@ -219,13 +241,13 @@ SQLite with litecli and VS Code extensions
 
 Distributed tracing backend
 
-| Property      | Value                                |
-| ------------- | ------------------------------------ |
-| **Category**  | observability                        |
-| **Supports**  | compose                              |
-| **Conflicts** | `tempo`                              |
-| **Tags**      | `observability`, `tracing`, `jaeger` |
-| **Ports**     | 16686, 14250, 14268                  |
+| Property      | Value                                             |
+| ------------- | ------------------------------------------------- |
+| **Category**  | observability                                     |
+| **Supports**  | compose                                           |
+| **Conflicts** | `tempo`                                           |
+| **Tags**      | `observability`, `tracing`, `jaeger`              |
+| **Ports**     | [object Object], [object Object], [object Object] |
 
 ### Loki (`loki`)
 
@@ -237,7 +259,7 @@ Log aggregation system
 | **Supports** | compose                         |
 | **Suggests** | `promtail`                      |
 | **Tags**     | `observability`, `logs`, `loki` |
-| **Ports**    | 3100                            |
+| **Ports**    | [object Object]                 |
 
 ### Prometheus (`prometheus`)
 
@@ -249,7 +271,7 @@ Metrics collection and monitoring
 | **Supports** | compose                                  |
 | **Suggests** | `alertmanager`                           |
 | **Tags**     | `observability`, `metrics`, `prometheus` |
-| **Ports**    | 9090                                     |
+| **Ports**    | [object Object]                          |
 
 ### Tempo (`tempo`)
 
@@ -310,7 +332,7 @@ Observability visualization dashboard with auto-provisioning
 | **Requires** | `prometheus`                           |
 | **Suggests** | `loki`, `jaeger`, `tempo`, `promtail`  |
 | **Tags**     | `observability`, `ui`, `visualization` |
-| **Ports**    | 3000                                   |
+| **Ports**    | [object Object]                        |
 
 ### OTel Demo (Node.js) (`otel-demo-nodejs`)
 
@@ -367,6 +389,18 @@ Google Cloud Platform command-line tools (gcloud, gsutil, bq)
 | **Category** | cloud                           |
 | **Tags**     | `cloud`, `gcp`, `google`, `cli` |
 
+### kind (Kubernetes in Docker) (`kind`)
+
+Local Kubernetes cluster for development and testing
+
+| Property      | Value                                           |
+| ------------- | ----------------------------------------------- |
+| **Category**  | cloud                                           |
+| **Requires**  | `docker-in-docker`                              |
+| **Suggests**  | `kubectl-helm`                                  |
+| **Conflicts** | `k3d`                                           |
+| **Tags**      | `cloud`, `kubernetes`, `k8s`, `kind`, `testing` |
+
 ### kubectl + Helm (`kubectl-helm`)
 
 Kubernetes CLI and Helm package manager
@@ -376,6 +410,18 @@ Kubernetes CLI and Helm package manager
 | **Category** | cloud                         |
 | **Tags**     | `cloud`, `kubernetes`, `helm` |
 
+### LocalStack (`localstack`)
+
+Local AWS cloud stack for development and testing
+
+| Property     | Value                                   |
+| ------------ | --------------------------------------- |
+| **Category** | cloud                                   |
+| **Supports** | compose                                 |
+| **Suggests** | `aws-cli`                               |
+| **Tags**     | `cloud`, `aws`, `testing`, `localstack` |
+| **Ports**    | 4566, 4571                              |
+
 ### Pulumi (`pulumi`)
 
 Modern Infrastructure as Code with TypeScript/Python/Go
@@ -396,6 +442,16 @@ Infrastructure as Code with HCL (includes tflint)
 
 ## Dev Tool Overlays
 
+### Cloudflared (`cloudflared`)
+
+Cloudflare Tunnel for securely exposing local services to the internet
+
+| Property      | Value                                     |
+| ------------- | ----------------------------------------- |
+| **Category**  | dev                                       |
+| **Conflicts** | `ngrok`                                   |
+| **Tags**      | `dev`, `tunneling`, `proxy`, `cloudflare` |
+
 ### Codex (`codex`)
 
 OpenAI Codex CLI for AI-powered code generation and assistance
@@ -413,6 +469,7 @@ Conventional commits validation for automated releases
 | Property     | Value                                       |
 | ------------ | ------------------------------------------- |
 | **Category** | dev                                         |
+| **Requires** | `nodejs`                                    |
 | **Suggests** | `pre-commit`                                |
 | **Tags**     | `dev`, `git`, `commits`, `semantic-release` |
 
@@ -454,6 +511,15 @@ Git LFS, GitHub CLI, GPG/SSH support for secure Git operations
 | **Category** | dev                                    |
 | **Tags**     | `dev`, `git`, `security`, `ssh`, `gpg` |
 
+### gRPC Tools (`grpc-tools`)
+
+Protocol Buffers compiler, Buf, and grpcurl for gRPC development
+
+| Property     | Value                            |
+| ------------ | -------------------------------- |
+| **Category** | dev                              |
+| **Tags**     | `dev`, `grpc`, `protobuf`, `api` |
+
 ### Just Task Runner (`just`)
 
 Fast, simple command runner (Rust-based alternative to Make)
@@ -463,6 +529,29 @@ Fast, simple command runner (Rust-based alternative to Make)
 | **Category** | dev                          |
 | **Tags**     | `dev`, `automation`, `tasks` |
 
+### Keycloak (`keycloak`)
+
+Open-source identity and access management (OIDC/OAuth2)
+
+| Property     | Value                                       |
+| ------------ | ------------------------------------------- |
+| **Category** | dev                                         |
+| **Supports** | compose                                     |
+| **Requires** | `postgres`                                  |
+| **Tags**     | `dev`, `auth`, `oidc`, `oauth2`, `identity` |
+| **Ports**    | [object Object]                             |
+
+### Mailpit (`mailpit`)
+
+Email testing tool with web UI and SMTP server
+
+| Property     | Value                             |
+| ------------ | --------------------------------- |
+| **Category** | dev                               |
+| **Supports** | compose                           |
+| **Tags**     | `dev`, `email`, `smtp`, `testing` |
+| **Ports**    | [object Object], [object Object]  |
+
 ### Modern CLI Tools (`modern-cli-tools`)
 
 jq, yq, ripgrep, fd, bat - Essential modern command-line tools
@@ -476,11 +565,22 @@ jq, yq, ripgrep, fd, bat - Essential modern command-line tools
 
 Secure tunneling for webhook testing and external access
 
-| Property     | Value                          |
-| ------------ | ------------------------------ |
-| **Category** | dev                            |
-| **Tags**     | `dev`, `tunneling`, `webhooks` |
-| **Ports**    | 4040                           |
+| Property      | Value                          |
+| ------------- | ------------------------------ |
+| **Category**  | dev                            |
+| **Conflicts** | `cloudflared`                  |
+| **Tags**      | `dev`, `tunneling`, `webhooks` |
+| **Ports**     | 4040                           |
+
+### OpenAPI Tools (`openapi-tools`)
+
+OpenAPI/Swagger tooling for API development and documentation
+
+| Property     | Value                                               |
+| ------------ | --------------------------------------------------- |
+| **Category** | dev                                                 |
+| **Suggests** | `nodejs`                                            |
+| **Tags**     | `dev`, `openapi`, `swagger`, `api`, `documentation` |
 
 ### Playwright (`playwright`)
 
@@ -498,9 +598,22 @@ Automated code quality gates with pre-commit hooks
 | Property     | Value                            |
 | ------------ | -------------------------------- |
 | **Category** | dev                              |
+| **Requires** | `python`                         |
 | **Suggests** | `commitlint`                     |
 | **Tags**     | `dev`, `git`, `quality`, `hooks` |
 
+### Tilt (`tilt`)
+
+Live update and orchestration for Kubernetes development
+
+| Property      | Value                                                    |
+| ------------- | -------------------------------------------------------- |
+| **Category**  | dev                                                      |
+| **Suggests**  | `kind`, `kubectl-helm`                                   |
+| **Conflicts** | `skaffold`                                               |
+| **Tags**      | `dev`, `kubernetes`, `k8s`, `development`, `live-reload` |
+| **Ports**     | 10350                                                    |
+
 ## Dependency Model
 
 ### Dependency Types
@@ -519,5 +632,3 @@ For example, selecting `grafana` will automatically include `prometheus`.
 Each overlay declares its ports explicitly. When using port offset, all declared ports are shifted by the same offset.
 
 ---
-
-_Documentation generated on 2026-02-08T18:01:55.685Z_

package/docs/presets-architecture.md

@@ -65,10 +65,10 @@ interface PresetGlueConfig {
 
 ### Preset File Structure
 
-Presets are defined in `overlays/presets/` with YAML files:
+Presets are defined in `overlays/.presets/` with YAML files:
 
 ```yaml
-# overlays/presets/web-api.yml
+# overlays/.presets/web-api.yml
 id: web-api
 name: Web API Stack
 description: Full-stack web API with database, cache, and observability
@@ -407,7 +407,7 @@ selects:
 
 ### Adding New Presets
 
-1. **Create YAML file** in `overlays/presets/`
+1. **Create YAML file** in `overlays/.presets/`
 2. **Register in** `overlays/index.yml`
 3. **No code changes needed** (declarative system)
 

package/docs/presets.md

@@ -281,7 +281,7 @@ This allows you to:
 
 To create your own preset:
 
-1. Create `overlays/presets/my-preset.yml`:
+1. Create `overlays/.presets/my-preset.yml`:
 
 ```yaml
 id: my-preset

package/docs/publishing.md

@@ -299,8 +299,6 @@ npm install -g container-superposition
 container-superposition init
 ```
 
-````
-
 ## Continuous Publishing
 
 ### Automated Releases (Future Enhancement)
@@ -312,23 +310,23 @@ Consider GitHub Actions for automated publishing:
 name: Publish to npm
 
 on:
-  release:
-    types: [created]
+    release:
+        types: [created]
 
 jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm test
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    publish:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: '20'
+                  registry-url: 'https://registry.npmjs.org'
+            - run: npm ci
+            - run: npm test
+            - run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
 ## Troubleshooting
@@ -336,6 +334,7 @@ jobs:
 ### ".npmignore not found" Warning
 
 If you see:
+
 ```
 npm warn gitignore-fallback No .npmignore file found, using .gitignore for file exclusion.
 ```
@@ -343,17 +342,18 @@ npm warn gitignore-fallback No .npmignore file found, using .gitignore for file
 **This warning can be safely ignored.** The package uses the `"files"` field in `package.json` as the primary inclusion mechanism (allowlist approach), which is more explicit and maintainable than `.npmignore` (denylist approach).
 
 The `"files"` field specifies exactly what to include:
+
 ```json
 {
-  "files": [
-    "dist/",
-    "templates/",
-    "features/",
-    "overlays/",
-    "tool/**/*.json",
-    "tool/**/*.yml",
-    "docs/**/*.md"
-  ]
+    "files": [
+        "dist/",
+        "templates/",
+        "features/",
+        "overlays/",
+        "tool/**/*.json",
+        "tool/**/*.yml",
+        "docs/**/*.md"
+    ]
 }
 ```
 
@@ -381,14 +381,14 @@ To exclude unnecessary files, modify the `"files"` array in `package.json`:
 
 ```json
 {
-  "files": [
-    "dist/",           // Keep compiled code
-    "templates/",      // Keep base templates
-    "features/",       // Keep custom features
-    "overlays/",       // Keep all overlays
-    // Exclude specific patterns with "!" prefix if needed
-    "!overlays/**/node_modules"
-  ]
+    "files": [
+        "dist/", // Keep compiled code
+        "templates/", // Keep base templates
+        "features/", // Keep custom features
+        "overlays/", // Keep all overlays
+        // Exclude specific patterns with "!" prefix if needed
+        "!overlays/**/node_modules"
+    ]
 }
 ```
 
@@ -407,6 +407,7 @@ npm login
 ### Name Already Taken
 
 Options:
+
 1. Use scoped package: `@veggerby/container-superposition`
 2. Choose different name: `devcontainer-superposition`, `superposition-dev`, etc.
 3. Contact current owner if package is abandoned
@@ -425,6 +426,7 @@ npm publish
 ### Versioning Strategy
 
 Follow [Semantic Versioning](https://semver.org/):
+
 - **MAJOR**: Breaking changes (e.g., removing overlays, changing CLI args)
 - **MINOR**: New features (e.g., adding overlays, new CLI options)
 - **PATCH**: Bug fixes (e.g., fixing composition logic, updating deps)
@@ -473,4 +475,3 @@ npm unpublish container-superposition --force
 - [npm Version Management](https://docs.npmjs.com/cli/v10/commands/npm-version)
 - [Semantic Versioning](https://semver.org/)
 - [npm Package Lifecycle Scripts](https://docs.npmjs.com/cli/v10/using-npm/scripts#life-cycle-scripts)
-````