container-superposition 0.1.5 → 0.1.7

package/overlays/ngrok/setup.sh

@@ -8,16 +8,19 @@ echo "🌐 Setting up ngrok..."
 # Install ngrok using official apt repository (provides signed packages)
 echo "📦 Installing ngrok from official repository..."
 
-# Add ngrok's GPG key and repository
-curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
-    | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
 
+# Add ngrok GPG key and repository
+# Note: ngrok uses .asc (armored) format, piped directly to trusted.gpg.d (no --dearmor needed)
+curl -fsSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
+    | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
 echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
-    | sudo tee /etc/apt/sources.list.d/ngrok.list
+    | sudo tee /etc/apt/sources.list.d/ngrok.list >/dev/null
 
 # Update and install
-sudo apt-get update -qq
-sudo apt-get install -y ngrok
+apt_install ngrok
 
 # Verify installation
 if command -v ngrok &> /dev/null; then

package/overlays/nodejs/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 # Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
 OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
 

package/overlays/openapi-tools/devcontainer.patch.json

@@ -5,6 +5,5 @@
             "apt": "curl",
             "apk": "curl"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-openapi-tools.sh"
+    }
 }

package/overlays/openapi-tools/setup.sh

@@ -3,19 +3,20 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "🔧 Setting up OpenAPI Tools..."
 
 # Install OpenAPI tools globally via npm
 echo "📦 Installing OpenAPI tools..."
 
-# Install swagger-cli (OpenAPI validation)
-npm install -g @apidevtools/swagger-cli || echo "⚠️ swagger-cli already installed or failed"
-
-# Install spectral (OpenAPI linting)
-npm install -g @stoplight/spectral-cli || echo "⚠️ spectral already installed or failed"
-
-# Install redocly CLI (documentation and bundling)
-npm install -g @redocly/cli || echo "⚠️ redocly already installed or failed"
+# Wrap each install in run_spinner to suppress noisy deprecation warnings
+run_spinner "swagger-cli"  npm install -g @apidevtools/swagger-cli
+run_spinner "spectral"     npm install -g @stoplight/spectral-cli
+run_spinner "redocly"      npm install -g @redocly/cli
 
 # Verify installations
 echo ""

package/overlays/opencode/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing opencode AI coding agent..."
 
 # Install opencode-ai globally

package/overlays/otel-collector/overlay.yml

@@ -19,3 +19,5 @@ ports:
     - 8888
     - 8889
 order: 2
+imports:
+    - .shared/otel/instrumentation.env

package/overlays/otel-collector/setup.sh

@@ -5,23 +5,10 @@ set -e
 
 echo "🔧 Configuring OpenTelemetry Collector trace backend..."
 
-# Determine workspace root dynamically
-WORKSPACE_ROOT="${LOCAL_WORKSPACE_FOLDER:-$PWD}"
-
-if [ ! -d "$WORKSPACE_ROOT/.devcontainer" ]; then
-    if [ -d "/workspaces" ]; then
-        FIRST_WORKSPACE_DIR="$(find /workspaces -maxdepth 1 -mindepth 1 -type d 2>/dev/null | head -n 1)"
-        if [ -n "$FIRST_WORKSPACE_DIR" ] && [ -d "$FIRST_WORKSPACE_DIR/.devcontainer" ]; then
-            WORKSPACE_ROOT="$FIRST_WORKSPACE_DIR"
-        fi
-    fi
-fi
-
-if [ ! -d "$WORKSPACE_ROOT/.devcontainer" ] && [ -d "/workspace/.devcontainer" ]; then
-    WORKSPACE_ROOT="/workspace"
-fi
+# Resolve the .devcontainer directory relative to this script.
+DEVCONTAINER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)"
 
-OTEL_CONFIG="$WORKSPACE_ROOT/.devcontainer/otel-collector-config-otel-collector.yaml"
+OTEL_CONFIG="$DEVCONTAINER_DIR/otel-collector-config-otel-collector.yaml"
 
 if [ ! -f "$OTEL_CONFIG" ]; then
     echo "⚠️ OTel Collector config not found"

package/overlays/otel-demo-nodejs/verify.sh

@@ -6,19 +6,18 @@ echo "🔍 Verifying OTel Demo (Node.js) installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if service is running
-if docker ps --format '{{.Names}}' | grep -q otel-demo-nodejs; then
-    echo "✓ OTel Demo (Node.js) service is running"
+# Check if HTTP health endpoint is accessible (primary health signal).
+# docker ps is informational only — not reliably accessible in all devcontainers.
+if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-nodejs:8080/health 2>/dev/null | grep -q "200"; then
+    echo "✓ Demo app HTTP endpoint is accessible"
 else
-    echo "✗ OTel Demo (Node.js) service is not running"
+    echo "✗ Demo app HTTP endpoint not responding (http://otel-demo-nodejs:8080/health)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if HTTP endpoint is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-nodejs:8080/health 2>/dev/null | grep -q "200"; then
-    echo "✓ Demo app HTTP endpoint is accessible"
-else
-    echo "⚠️ Demo app HTTP endpoint not responding yet (may still be starting)"
+# Informational: check via docker ps if available.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q otel-demo-nodejs; then
+    echo "✓ OTel Demo (Node.js) container visible in docker ps"
 fi
 
 # Final result

package/overlays/otel-demo-python/verify.sh

@@ -6,19 +6,25 @@ echo "🔍 Verifying OTel Demo (Python) installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if service is running
-if docker ps --format '{{.Names}}' | grep -q otel-demo-python; then
-    echo "✓ OTel Demo (Python) service is running"
-else
-    echo "✗ OTel Demo (Python) service is not running"
+# Wait for demo app HTTP health endpoint (primary health signal).
+# docker ps is informational only — not reliably accessible in all devcontainers.
+APP_READY=false
+for i in {1..40}; do
+    if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-python:8081/health 2>/dev/null | grep -q "200"; then
+        echo "✓ Demo app HTTP endpoint is accessible"
+        APP_READY=true
+        break
+    fi
+    sleep 3
+done
+if [ "$APP_READY" = false ]; then
+    echo "✗ Demo app HTTP endpoint not responding after 120 s (http://otel-demo-python:8081/health)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if HTTP endpoint is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://otel-demo-python:8081/health 2>/dev/null | grep -q "200"; then
-    echo "✓ Demo app HTTP endpoint is accessible"
-else
-    echo "⚠️ Demo app HTTP endpoint not responding yet (may still be starting)"
+# Informational: check via docker ps if available.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q otel-demo-python; then
+    echo "✓ OTel Demo (Python) container visible in docker ps"
 fi
 
 # Final result

package/overlays/pandoc/README.md

@@ -0,0 +1,286 @@
+# Pandoc PDF Overlay
+
+Adds a complete Markdown → PDF pipeline to your devcontainer, powered by Pandoc, XeLaTeX, and optional Mermaid diagram rendering.
+
+## Features
+
+- **Pandoc 3.x** — Latest release binary from GitHub (not the outdated apt version)
+- **TeX Live / XeLaTeX** — Full Unicode-capable PDF engine (`texlive-xetex`, `texlive-fonts-extra`, `texlive-latex-extra`)
+- **Quality fonts** — Carlito (body), JetBrains Mono (code), Noto Sans Symbols 2 (Unicode fallback), and Noto Color Emoji via system packages
+    - Uses the `cross-distro-packages` feature with fallback package names for Carlito (`fonts-carlito|fonts-crosextra-carlito`)
+- **`diagram.lua`** — Lua filter from [pandoc-ext/diagram](https://github.com/pandoc-ext/diagram) for rendering code-block diagrams
+- **`emoji-fallback.lua`** — Built-in Lua filter that rewrites unsupported emoji and flag glyphs to plain-text placeholders for reliable XeLaTeX PDF builds
+- **Mermaid CLI (`mmdc`)** — Installed when the `nodejs` overlay is present; skipped gracefully otherwise
+- **`~/.pandoc/pandoc.yaml`** — Ready-to-use defaults file (XeLaTeX engine, font settings, table tweaks)
+- **VS Code Extensions:** Markdown All in One (`yzhang.markdown-all-in-one`), markdownlint (`DavidAnson.vscode-markdownlint`)
+
+## How It Works
+
+System packages are installed through the `cross-distro-packages` feature, which handles package-manager detection and now supports fallback package names for distro variants. The setup script then downloads the official Pandoc `.deb` from GitHub releases (Pandoc 3.x is required for `diagram.lua`'s `Figure` AST element). Chromium is installed system-wide to serve as Puppeteer's browser for Mermaid headless rendering.
+
+The pipeline:
+
+```text
+Markdown
+  -> pandoc
+    -> diagram.lua (Lua filter, optional)
+      -> mmdc (Mermaid CLI, headless Chromium)
+    -> XeLaTeX
+      -> PDF
+```
+
+Font discovery is updated with `fc-cache -fv` after installation so XeLaTeX can locate the apt-installed fonts.
+
+The generated defaults also enable an emoji fallback filter for LaTeX output. The overlay now installs Noto Color Emoji as well, which may improve glyph coverage in some contexts, but the fallback filter remains enabled because XeLaTeX still is not reliable for full emoji and flag rendering. The filter converts unsupported glyphs such as `🇵🇹` to `[PT]` and generic emoji such as `😀` to `[emoji]` before XeLaTeX runs, preventing the `Unicode character ... not set up for use with LaTeX` failure.
+
+The setup script also installs a `/usr/local/bin/pandoc` wrapper that automatically applies `~/.pandoc/pandoc.yaml` unless you explicitly pass `-d` or `--defaults`. That makes plain commands like `pandoc doc.md -o doc.pdf` use the overlay defaults.
+
+## Common Commands
+
+### Basic PDF export
+
+```bash
+# Uses the installed wrapper, which applies ~/.pandoc/pandoc.yaml automatically
+pandoc document.md -o document.pdf
+
+# Override the output font on the fly
+pandoc -d ~/.pandoc/pandoc.yaml -V mainfont="DejaVu Serif" document.md -o document.pdf
+```
+
+### PDF with Mermaid diagrams (requires nodejs overlay)
+
+```bash
+pandoc --lua-filter ~/.pandoc/filters/diagram.lua \
+  document.md -o document.pdf
+```
+
+### Inspect installed fonts
+
+```bash
+fc-list | grep -i carlito
+fc-list | grep -i jetbrains
+fc-list | grep -i "noto sans symbols"
+```
+
+### Check Pandoc version
+
+```bash
+pandoc --version
+```
+
+## Mermaid Diagram Usage
+
+Add fenced `mermaid` code blocks to your Markdown:
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+Render with the `diagram.lua` filter:
+
+```bash
+pandoc -d ~/.pandoc/pandoc.yaml \
+  --lua-filter ~/.pandoc/filters/diagram.lua \
+  document.md -o document.pdf
+```
+
+The filter invokes `mmdc` for each `mermaid` block, producing a PNG that XeLaTeX embeds in the PDF. The Puppeteer configuration at `~/.config/mermaid/puppeteer-config.json` points `mmdc` at the system Chromium with `--no-sandbox`, which is required inside containers.
+
+## Configuration
+
+### Default `~/.pandoc/pandoc.yaml`
+
+The setup script writes a defaults file with proven settings:
+
+```yaml
+pdf-engine: xelatex
+filters:
+    - /home/your-user/.pandoc/filters/emoji-fallback.lua
+
+variables:
+    mainfont: 'Carlito'
+    monofont: 'JetBrains Mono'
+    fallbackfont: 'Noto Sans Symbols 2'
+    fontsize: 11pt
+    linestretch: 1.15
+    geometry:
+        - top=16mm
+        - bottom=16mm
+        - left=14mm
+        - right=14mm
+    header-includes:
+        - |
+            \usepackage{etoolbox}
+            \setlength{\tabcolsep}{3pt}
+            \renewcommand{\arraystretch}{1.05}
+            \AtBeginEnvironment{longtable}{\small}
+            \AtBeginEnvironment{tabular}{\small}
+```
+
+### Per-project override
+
+Create a `pandoc.yaml` in your project directory to override the defaults:
+
+```yaml
+# project/pandoc.yaml
+pdf-engine: xelatex
+variables:
+    mainfont: 'DejaVu Serif'
+    fontsize: 12pt
+toc: true
+toc-depth: 3
+number-sections: true
+filters:
+    - /home/your-user/.pandoc/filters/emoji-fallback.lua
+    - /home/your-user/.pandoc/filters/diagram.lua
+```
+
+Then build with:
+
+```bash
+pandoc -d pandoc.yaml document.md -o document.pdf
+```
+
+### Enable TOC and section numbering
+
+Uncomment the relevant lines in `~/.pandoc/pandoc.yaml`:
+
+```yaml
+toc: true
+toc-depth: 3
+number-sections: true
+```
+
+### Enable Mermaid rendering by default
+
+Uncomment in `~/.pandoc/pandoc.yaml`:
+
+```yaml
+filters:
+    - /home/your-user/.pandoc/filters/emoji-fallback.lua
+    - /home/your-user/.pandoc/filters/diagram.lua
+```
+
+## Unicode and Emoji
+
+XeLaTeX handles normal Unicode text well with the bundled fonts. The overlay now also installs Noto Color Emoji, which can help with emoji coverage, but the failure mode in PDF builds is still usually emoji or regional-indicator flags, for example `🇵🇹`, which XeLaTeX may reject before font fallback can help.
+
+The overlay now enables `~/.pandoc/filters/emoji-fallback.lua` by default for LaTeX output. It keeps normal Unicode text intact and rewrites unsupported emoji to plain-text placeholders:
+
+- `🇵🇹 Porto` becomes `[PT] Porto`
+- `😀` becomes `[emoji]`
+
+If you want to experiment with more native emoji rendering, keep the installed emoji font and override the default Pandoc/LaTeX settings in a project-local `pandoc.yaml`, but the placeholder filter is still the reliable default for PDF generation.
+
+## Use Cases
+
+- **Architecture documentation** — Architecture Decision Records (ADRs), system design docs
+- **API specifications** — OpenAPI-style documentation with code samples
+- **Technical reports** — Multi-section documents with tables and diagrams
+- **README to PDF** — Convert project READMEs to distributable PDF format
+
+**Integrates well with:**
+
+- `nodejs` overlay — Enables Mermaid CLI for diagram rendering
+- `git-helpers` overlay — Commit generated PDFs alongside source Markdown
+- `modern-cli-tools` overlay — Use `bat` to preview Markdown, `rg` to search documents
+
+## Troubleshooting
+
+### `xelatex: command not found`
+
+TeX Live was not installed correctly. Re-run the setup script:
+
+```bash
+bash .devcontainer/scripts/setup-pandoc.sh
+```
+
+### Missing glyph warnings / blank characters in PDF
+
+The font does not include that glyph. For common Unicode symbols, Noto Sans Symbols 2 covers most cases. Verify it is installed:
+
+```bash
+fc-list | grep -i "noto sans symbols 2"
+```
+
+If not found, rebuild the font cache:
+
+```bash
+sudo fc-cache -fv
+```
+
+### Wide tables overflow page margins
+
+The `header-includes` in `pandoc.yaml` applies `\small` inside `longtable` and `tabular` environments. For very wide tables, also add `\tiny` or use column width constraints in your Markdown:
+
+```markdown
+| Col 1 | Col 2 | Col 3 |
+| :---- | :---- | :---- |
+| data  | data  | data  |
+```
+
+### Mermaid: Chromium crashes or `--no-sandbox` error
+
+The Puppeteer config at `~/.config/mermaid/puppeteer-config.json` must set `--no-sandbox`:
+
+```json
+{
+    "executablePath": "/usr/bin/chromium",
+    "args": ["--no-sandbox", "--disable-setuid-sandbox"]
+}
+```
+
+Verify the file exists and contains the correct content:
+
+```bash
+cat ~/.config/mermaid/puppeteer-config.json
+```
+
+### `mmdc` not found
+
+The `nodejs` overlay must be selected to install Mermaid CLI. Check if Node.js is available:
+
+```bash
+node --version
+npm --version
+mmdc --version
+```
+
+If Node.js is present but `mmdc` is missing, install it manually:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+### Upgrading Pandoc
+
+To upgrade to a newer Pandoc release, update `PANDOC_VERSION` in `setup.sh` and re-run it:
+
+```bash
+PANDOC_VERSION=3.7.0  # update as needed
+ARCH=$(dpkg --print-architecture)
+PANDOC_DEB="pandoc-${PANDOC_VERSION}-1-${ARCH}.deb"
+curl -fsSL "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/${PANDOC_DEB}" \
+    -o "/tmp/${PANDOC_DEB}"
+sudo dpkg -i "/tmp/${PANDOC_DEB}"
+rm "/tmp/${PANDOC_DEB}"
+```
+
+## References
+
+- [Pandoc releases](https://github.com/jgm/pandoc/releases)
+- [pandoc-ext/diagram Lua filter](https://github.com/pandoc-ext/diagram)
+- [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)
+- [Puppeteer in containers](https://pptr.dev/troubleshooting#running-puppeteer-in-docker)
+- [TeX Live packages](https://packages.debian.org/search?keywords=texlive)
+
+**Related Overlays:**
+
+- `nodejs` — Required for Mermaid diagram rendering via `mmdc`
+- `git-helpers` — Secure Git operations for committing generated docs
+- `modern-cli-tools` — Productivity tools for Markdown authoring workflows

package/overlays/pandoc/devcontainer.patch.json

@@ -0,0 +1,18 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "texlive-xetex texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra texlive-lang-european lmodern fonts-carlito|fonts-crosextra-carlito fonts-noto fonts-noto-extra fonts-noto-mono fonts-jetbrains-mono fonts-noto-color-emoji fontconfig librsvg2-bin perl chromium",
+            "apk": "fontconfig noto-fonts-emoji|noto-emoji perl chromium"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["yzhang.markdown-all-in-one", "DavidAnson.vscode-markdownlint"]
+        }
+    },
+    "remoteEnv": {
+        "PUPPETEER_EXECUTABLE_PATH": "/usr/local/bin/chromium-no-sandbox",
+        "PUPPETEER_SKIP_DOWNLOAD": "true"
+    }
+}

package/overlays/pandoc/overlay.yml

@@ -0,0 +1,19 @@
+id: pandoc
+name: Pandoc PDF
+description: Pandoc with XeLaTeX, Mermaid diagrams, and quality fonts for Markdown-to-PDF export
+category: dev
+supports: []
+requires: []
+suggests:
+    - nodejs
+conflicts: []
+tags:
+    - dev
+    - pandoc
+    - pdf
+    - latex
+    - markdown
+    - docs
+    - mermaid
+ports: []
+order: 25