container-superposition 0.1.5 → 0.1.6

package/features/cross-distro-packages/install.sh

@@ -14,6 +14,50 @@ deduplicate_packages() {
     echo "$packages" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/ $//'
 }
 
+resolve_package_token() {
+    local manager="$1"
+    local token="$2"
+    local IFS='|'
+    read -r -a candidates <<< "$token"
+
+    for candidate in "${candidates[@]}"; do
+        if [ -z "$candidate" ]; then
+            continue
+        fi
+
+        if [ "$manager" = "apt" ]; then
+            if apt-cache show "$candidate" >/dev/null 2>&1; then
+                echo "$candidate"
+                return 0
+            fi
+        elif [ "$manager" = "apk" ]; then
+            if apk search -x "$candidate" >/dev/null 2>&1; then
+                echo "$candidate"
+                return 0
+            fi
+        fi
+    done
+
+    return 1
+}
+
+resolve_package_list() {
+    local manager="$1"
+    local packages="$2"
+    local resolved=()
+
+    for token in $packages; do
+        local selected=""
+        if ! selected=$(resolve_package_token "$manager" "$token"); then
+            echo "❌ No package candidate found for \"$token\" using $manager" >&2
+            exit 1
+        fi
+        resolved+=("$selected")
+    done
+
+    deduplicate_packages "${resolved[*]}"
+}
+
 # Exit early if no packages specified
 if [ -z "$APT_PACKAGES" ] && [ -z "$APK_PACKAGES" ]; then
     echo "⚠️  No packages specified for installation"
@@ -26,9 +70,8 @@ echo "📦 Installing cross-distro packages..."
 if command -v apk > /dev/null 2>&1; then
     # Alpine Linux (apk)
     if [ -n "$APK_PACKAGES" ]; then
-        # Deduplicate package list
-        APK_PACKAGES=$(deduplicate_packages "$APK_PACKAGES")
-        
+        APK_PACKAGES=$(resolve_package_list "apk" "$APK_PACKAGES")
+
         echo "  Detected: Alpine Linux (apk)"
         echo "  Installing: $APK_PACKAGES"
         apk add --no-cache $APK_PACKAGES
@@ -39,12 +82,11 @@ if command -v apk > /dev/null 2>&1; then
 elif command -v apt-get > /dev/null 2>&1; then
     # Debian/Ubuntu (apt)
     if [ -n "$APT_PACKAGES" ]; then
-        # Deduplicate package list
-        APT_PACKAGES=$(deduplicate_packages "$APT_PACKAGES")
-        
+        apt-get update
+        APT_PACKAGES=$(resolve_package_list "apt" "$APT_PACKAGES")
+
         echo "  Detected: Debian/Ubuntu (apt)"
         echo "  Installing: $APT_PACKAGES"
-        apt-get update
         DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $APT_PACKAGES
         apt-get clean
         rm -rf /var/lib/apt/lists/*

package/overlays/pandoc/README.md

@@ -0,0 +1,279 @@
+# 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) 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
+- **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.
+
+## Common Commands
+
+### Basic PDF export
+
+```bash
+# Use the default pandoc.yaml
+pandoc -d ~/.pandoc/pandoc.yaml 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 -d ~/.pandoc/pandoc.yaml \
+  --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
+
+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
+lua-filter:
+    - ~/.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
+lua-filter:
+    - ~/.pandoc/filters/diagram.lua
+```
+
+## Unicode and Emoji
+
+XeLaTeX handles Unicode well with the Noto and Carlito fonts, but emoji (🎉 🚀) require a colour emoji font (e.g. `fonts-noto-color-emoji`) which is not installed by default due to size. For documents with emoji, either:
+
+1. Replace emoji with text equivalents before generating the PDF:
+
+    ```bash
+    sed 's/🎉/[celebration]/g; s/🚀/[rocket]/g' doc.md | pandoc -d ~/.pandoc/pandoc.yaml -o doc.pdf
+    ```
+
+2. Install `fonts-noto-color-emoji` and add `\setmainfont{Noto Color Emoji}` for the emoji font fallback in your `header-includes`.
+
+## 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,14 @@
+{
+    "$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 fonts-carlito|fonts-crosextra-carlito fonts-noto fonts-noto-extra fonts-noto-mono fonts-jetbrains-mono fontconfig perl chromium",
+            "apk": "fontconfig perl chromium"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["yzhang.markdown-all-in-one", "DavidAnson.vscode-markdownlint"]
+        }
+    }
+}

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

package/overlays/pandoc/setup.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# pandoc overlay setup — Markdown -> PDF pipeline
+
+set -e
+
+echo "📦 Refreshing font cache..."
+sudo fc-cache -fv
+
+echo "📦 Installing Pandoc (latest release)..."
+PANDOC_VERSION="3.6.4"
+
+if command -v apt-get > /dev/null 2>&1; then
+    # Debian/Ubuntu — install official .deb from GitHub releases
+    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}"
+elif command -v apk > /dev/null 2>&1; then
+    # Alpine Linux — install via apk (version may differ from pinned release)
+    echo "⚠  Alpine detected: installing pandoc via apk (version may differ from ${PANDOC_VERSION})"
+    apk add --no-cache pandoc
+else
+    echo "❌ Unsupported distro: neither apt-get nor apk found. Cannot install Pandoc."
+    exit 1
+fi
+
+echo "✓ pandoc $(pandoc --version | head -1)"
+
+echo "📦 Installing diagram.lua Lua filter..."
+mkdir -p "$HOME/.pandoc/filters"
+curl -fsSL \
+    "https://raw.githubusercontent.com/pandoc-ext/diagram/main/_extensions/diagram/diagram.lua" \
+    -o "$HOME/.pandoc/filters/diagram.lua"
+
+echo "📦 Installing Mermaid CLI (requires Node.js)..."
+if command -v npm &>/dev/null; then
+    npm install -g @mermaid-js/mermaid-cli
+    # Point mmdc at the system Chromium (avoids Puppeteer downloading its own)
+    mkdir -p "$HOME/.config/mermaid"
+    cat > "$HOME/.config/mermaid/puppeteer-config.json" <<'EOF'
+{
+  "executablePath": "/usr/bin/chromium",
+  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
+}
+EOF
+    if command -v mmdc >/dev/null 2>&1; then
+        echo "✓ Mermaid CLI installed: $(command -v mmdc)"
+    else
+        echo "⚠  Mermaid CLI install completed but mmdc is not on PATH yet"
+    fi
+else
+    echo "⚠  Node.js not found — Mermaid CLI skipped. Add the nodejs overlay for diagram support."
+fi
+
+echo "📦 Writing default pandoc.yaml..."
+mkdir -p "$HOME/.pandoc"
+cat > "$HOME/.pandoc/pandoc.yaml" <<'EOF'
+pdf-engine: xelatex
+
+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}
+
+# Uncomment to enable TOC and section numbering:
+# toc: true
+# toc-depth: 3
+# number-sections: true
+
+# Uncomment to enable Mermaid/diagram rendering (requires nodejs overlay):
+# lua-filter:
+#   - ~/.pandoc/filters/diagram.lua
+EOF
+
+echo ""
+echo "✓ pandoc overlay setup complete"
+echo "ℹ️  Build a PDF:  pandoc -d ~/.pandoc/pandoc.yaml doc.md -o doc.pdf"
+echo "ℹ️  With Mermaid: pandoc -d ~/.pandoc/pandoc.yaml --lua-filter ~/.pandoc/filters/diagram.lua doc.md -o doc.pdf"

package/overlays/pandoc/verify.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -e
+command -v pandoc  || { echo "✗ pandoc not found"; exit 1; }
+command -v xelatex || { echo "✗ xelatex not found"; exit 1; }
+[ -f "$HOME/.pandoc/filters/diagram.lua" ] || { echo "✗ diagram.lua not found"; exit 1; }
+[ -f "$HOME/.pandoc/pandoc.yaml" ]         || { echo "✗ pandoc.yaml not found"; exit 1; }
+
+# Smoke test: render a trivial PDF
+echo "# Test" | pandoc --pdf-engine=xelatex -o /tmp/pandoc-verify-test.pdf && \
+    echo "✓ pandoc PDF smoke test passed" || { echo "✗ pandoc PDF render failed"; exit 1; }
+
+rm -f /tmp/pandoc-verify-test.pdf
+echo "✓ pandoc overlay: OK"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",