container-superposition 0.1.6 → 0.1.8

package/overlays/pandoc/setup.sh

@@ -4,18 +4,23 @@
 set -e
 
 echo "📦 Refreshing font cache..."
-sudo fc-cache -fv
+sudo fc-cache -f
 
 echo "📦 Installing Pandoc (latest release)..."
 PANDOC_VERSION="3.6.4"
 
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 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}"
+    with_apt_lock 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)
@@ -26,7 +31,50 @@ else
     exit 1
 fi
 
-echo "✓ pandoc $(pandoc --version | head -1)"
+if [ -x /usr/bin/pandoc ]; then
+    PANDOC_REAL_BIN="/usr/bin/pandoc"
+elif [ -x /usr/local/bin/pandoc ] && [ ! -L /usr/local/bin/pandoc ]; then
+    PANDOC_REAL_BIN="/usr/local/bin/pandoc"
+else
+    PANDOC_REAL_BIN="$(type -P pandoc || true)"
+fi
+
+if [ -z "$PANDOC_REAL_BIN" ] || [ ! -x "$PANDOC_REAL_BIN" ]; then
+    echo "❌ Could not resolve the real pandoc binary."
+    exit 1
+fi
+
+if [ "$PANDOC_REAL_BIN" = "/usr/local/bin/pandoc" ] && [ -f /usr/local/bin/pandoc ]; then
+    if grep -q 'DEFAULTS_FILE="\${HOME}/.pandoc/pandoc.yaml"' /usr/local/bin/pandoc 2>/dev/null; then
+        echo "❌ Refusing to wrap /usr/local/bin/pandoc because it is already the pandoc wrapper."
+        exit 1
+    fi
+fi
+
+echo "✓ pandoc $("$PANDOC_REAL_BIN" --version | head -1)"
+
+echo "📦 Installing pandoc wrapper with default PDF settings..."
+sudo tee /usr/local/bin/pandoc > /dev/null <<EOF
+#!/bin/sh
+REAL_PANDOC="${PANDOC_REAL_BIN}"
+DEFAULTS_FILE="\${HOME}/.pandoc/pandoc.yaml"
+
+for arg in "\$@"; do
+    case "\$arg" in
+        -d|--defaults|--defaults=*)
+            exec "\${REAL_PANDOC}" "\$@"
+            ;;
+    esac
+done
+
+if [ -f "\${DEFAULTS_FILE}" ]; then
+    exec "\${REAL_PANDOC}" --defaults "\${DEFAULTS_FILE}" "\$@"
+fi
+
+exec "\${REAL_PANDOC}" "\$@"
+EOF
+sudo chmod +x /usr/local/bin/pandoc
+echo "✓ pandoc wrapper installed: /usr/local/bin/pandoc -> ${PANDOC_REAL_BIN}"
 
 echo "📦 Installing diagram.lua Lua filter..."
 mkdir -p "$HOME/.pandoc/filters"
@@ -34,17 +82,167 @@ curl -fsSL \
     "https://raw.githubusercontent.com/pandoc-ext/diagram/main/_extensions/diagram/diagram.lua" \
     -o "$HOME/.pandoc/filters/diagram.lua"
 
+echo "📦 Writing emoji fallback Lua filter..."
+cat > "$HOME/.pandoc/filters/emoji-fallback.lua" <<'EOF'
+-- Replace emoji and flag glyphs that XeLaTeX commonly cannot render.
+--
+-- * BMP symbols (Miscellaneous Symbols U+2600-U+26FF, Dingbats U+2700-U+27BF)
+--   are routed to the fallback font via \textfallback{} so they render as
+--   real glyphs using Noto Sans Symbols 2 (declared by pandoc's fallbackfont
+--   variable in pandoc.yaml).
+--
+-- * High-plane emoji (U+1F000-U+1FAFF: 🎉 🚀 etc.) are replaced with the
+--   plain-text marker [emoji] because no common PDF font covers them fully.
+--
+-- * Flag sequences (pairs of regional-indicator letters: 🇺🇸 etc.) are
+--   replaced with the two-letter country code in brackets, e.g. [US].
+--
+-- The filter is a no-op for all non-LaTeX output formats.
+
+local REGIONAL_INDICATOR_A = 0x1F1E6
+local REGIONAL_INDICATOR_Z = 0x1F1FF
+
+local function is_regional_indicator(cp)
+    return cp >= REGIONAL_INDICATOR_A and cp <= REGIONAL_INDICATOR_Z
+end
+
+-- High-plane emoji that no standard PDF font renders reliably.
+local function is_high_plane_emoji(cp)
+    return cp >= 0x1F000 and cp <= 0x1FAFF
+end
+
+-- BMP symbol blocks absent from Carlito (and most body fonts).
+-- Characters in these ranges are routed to the \textfallback font instead.
+local function is_bmp_symbol(cp)
+    return (cp >= 0x2600 and cp <= 0x26FF)  -- Miscellaneous Symbols (⚠ ☀ ⛔ …)
+        or (cp >= 0x2700 and cp <= 0x27BF)  -- Dingbats             (✅ ❌ ✓ …)
+end
+
+-- Parse text into a list of pandoc inline elements, applying substitutions.
+-- Returns nil when no substitutions are needed.
+local function text_to_inlines(text)
+    if FORMAT ~= 'latex' then return nil end
+
+    -- Quick scan: skip AST work when there is nothing to process.
+    local needs_processing = false
+    for _, cp in utf8.codes(text) do
+        if is_regional_indicator(cp) or is_high_plane_emoji(cp) or is_bmp_symbol(cp)
+                or cp == 0x200D or cp == 0x20E3 or cp == 0xFE0F then
+            needs_processing = true
+            break
+        end
+    end
+    if not needs_processing then return nil end
+
+    local codepoints = {}
+    for _, cp in utf8.codes(text) do table.insert(codepoints, cp) end
+
+    local inlines = {}
+    local buf = {}
+
+    local function flush_buf()
+        if #buf > 0 then
+            table.insert(inlines, pandoc.Str(table.concat(buf)))
+            buf = {}
+        end
+    end
+
+    local i = 1
+    while i <= #codepoints do
+        local cp = codepoints[i]
+
+        -- Variation selectors / zero-width joiners / combining enclosing keycap
+        if cp == 0x200D or cp == 0x20E3 or cp == 0xFE0F then
+            i = i + 1
+
+        -- Flag sequences: two consecutive regional-indicator letters → [XX]
+        elseif is_regional_indicator(cp)
+                and i < #codepoints
+                and is_regional_indicator(codepoints[i + 1]) then
+            flush_buf()
+            local a = string.char((cp - REGIONAL_INDICATOR_A) + string.byte('A'))
+            local b = string.char((codepoints[i + 1] - REGIONAL_INDICATOR_A) + string.byte('A'))
+            table.insert(inlines, pandoc.Str('[' .. a .. b .. ']'))
+            i = i + 2
+
+        -- High-plane emoji → [emoji] text marker
+        elseif is_high_plane_emoji(cp) then
+            flush_buf()
+            table.insert(inlines, pandoc.Str('[emoji]'))
+            i = i + 1
+            -- Collapse consecutive emoji into one marker
+            while i <= #codepoints
+                    and (is_high_plane_emoji(codepoints[i])
+                         or codepoints[i] == 0xFE0F
+                         or codepoints[i] == 0x200D) do
+                i = i + 1
+            end
+
+        -- BMP symbols → \textfallback{char} (renders with Noto Sans Symbols 2)
+        elseif is_bmp_symbol(cp) then
+            flush_buf()
+            table.insert(inlines, pandoc.RawInline('latex',
+                '\\textfallback{' .. utf8.char(cp) .. '}'))
+            i = i + 1
+            -- Skip trailing variation selector-16 (e.g. U+FE0F after ⚠)
+            if i <= #codepoints and codepoints[i] == 0xFE0F then i = i + 1 end
+
+        else
+            table.insert(buf, utf8.char(cp))
+            i = i + 1
+        end
+    end
+    flush_buf()
+
+    -- If result is a single identical Str, nothing actually changed.
+    if #inlines == 1 and inlines[1].t == 'Str' and inlines[1].text == text then
+        return nil
+    end
+
+    return inlines
+end
+
+function Str(el)
+    local inlines = text_to_inlines(el.text)
+    if inlines == nil then return nil end
+    return inlines
+end
+
+-- In code spans / code blocks we cannot use \textfallback (verbatim context),
+-- so we simply drop the offending characters to prevent XeLaTeX warnings.
+local function strip_unsupported(el)
+    if FORMAT ~= 'latex' then return nil end
+    local changed = false
+    local out = {}
+    for _, cp in utf8.codes(el.text) do
+        if is_high_plane_emoji(cp) or is_bmp_symbol(cp)
+                or cp == 0x200D or cp == 0x20E3 or cp == 0xFE0F then
+            changed = true
+        else
+            table.insert(out, utf8.char(cp))
+        end
+    end
+    if not changed then return nil end
+    el.text = table.concat(out)
+    return el
+end
+
+function Code(el)     return strip_unsupported(el) end
+function CodeBlock(el) return strip_unsupported(el) end
+EOF
+
 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
+    run_spinner "Mermaid CLI" npm install -g @mermaid-js/mermaid-cli
+    # Create a chromium wrapper that always passes --no-sandbox (required in containers).
+    # This is more robust than configuring mmdc/puppeteer individually — any tool
+    # that launches chromium via PUPPETEER_EXECUTABLE_PATH gets the sandbox flags.
+    sudo tee /usr/local/bin/chromium-no-sandbox > /dev/null <<'WRAPPER'
+#!/bin/sh
+exec /usr/bin/chromium --no-sandbox --disable-setuid-sandbox "$@"
+WRAPPER
+    sudo chmod +x /usr/local/bin/chromium-no-sandbox
+    echo "✓ chromium-no-sandbox wrapper installed"
     if command -v mmdc >/dev/null 2>&1; then
         echo "✓ Mermaid CLI installed: $(command -v mmdc)"
     else
@@ -56,8 +254,12 @@ fi
 
 echo "📦 Writing default pandoc.yaml..."
 mkdir -p "$HOME/.pandoc"
+PANDOC_FILTERS_DIR="$HOME/.pandoc/filters"
 cat > "$HOME/.pandoc/pandoc.yaml" <<'EOF'
 pdf-engine: xelatex
+filters:
+  - __PANDOC_FILTERS_DIR__/emoji-fallback.lua
+  - __PANDOC_FILTERS_DIR__/diagram.lua
 
 variables:
   mainfont: "Carlito"
@@ -82,13 +284,10 @@ variables:
 # toc: true
 # toc-depth: 3
 # number-sections: true
-
-# Uncomment to enable Mermaid/diagram rendering (requires nodejs overlay):
-# lua-filter:
-#   - ~/.pandoc/filters/diagram.lua
 EOF
+sed -i "s|__PANDOC_FILTERS_DIR__|${PANDOC_FILTERS_DIR}|g" "$HOME/.pandoc/pandoc.yaml"
 
 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"
+echo "ℹ️  Build a PDF:           pandoc doc.md -o doc.pdf"
+echo "ℹ️  With Mermaid diagrams: pandoc doc.md -o doc.pdf  (diagram.lua enabled by default)"

package/overlays/pandoc/verify.sh

@@ -3,11 +3,23 @@ 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; }
+[ -f "$HOME/.pandoc/filters/emoji-fallback.lua" ] || { echo "✗ emoji-fallback.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; }
+# Smoke test: render a PDF that includes generic emoji and flag sequences
+# which XeLaTeX can reject without the fallback filter.
+printf '%s\n' \
+    '# Unicode Smoke Test' \
+    '' \
+    'Status icons: ✅ ⚠️ ❌' \
+    'Activity emoji: 🎉 🚀 🧪' \
+    'Flag emoji: 🇺🇸 🇯🇵 🇧🇷' \
+    'Mixed sample: Unicode check 😀' |
+    pandoc -o /tmp/pandoc-verify-test.pdf &&
+    echo "✓ pandoc Unicode PDF smoke test passed" || {
+    echo "✗ pandoc Unicode PDF render failed"
+    exit 1
+}
 
 rm -f /tmp/pandoc-verify-test.pdf
 echo "✓ pandoc overlay: OK"

package/overlays/pgvector/.env.example

@@ -0,0 +1,6 @@
+# pgvector Configuration
+PGVECTOR_VERSION={{cs.PGVECTOR_VERSION}}
+PGVECTOR_DB={{cs.PGVECTOR_DB}}
+PGVECTOR_USER={{cs.PGVECTOR_USER}}
+PGVECTOR_PASSWORD={{cs.PGVECTOR_PASSWORD}}
+PGVECTOR_PORT={{cs.PGVECTOR_PORT}}

package/overlays/pgvector/README.md

@@ -0,0 +1,215 @@
+# pgvector Overlay
+
+Adds a PostgreSQL 16 database pre-loaded with the [pgvector](https://github.com/pgvector/pgvector) extension, enabling vector similarity search directly within a familiar SQL environment.
+
+> **Note:** This overlay conflicts with the `postgres` overlay because both provide a PostgreSQL service on port 5432. Choose `pgvector` when you need vector search, or `postgres` for a plain database.
+
+## Features
+
+- **pgvector extension** — `CREATE EXTENSION vector;` is available immediately; no manual installation required
+- **Full PostgreSQL 16** — All standard SQL features alongside vector operations
+- **`psql` client in devcontainer** — `postgresql-client` package installed for interactive SQL sessions
+- **Pre-configured environment** — `PGHOST`, `PGPORT`, `PGDATABASE`, and `PGUSER` set automatically
+- **Persistent storage** — Named Docker volume preserves data across container rebuilds
+- **Health check** — Compose readiness check using `pg_isready` before dependent services start
+
+## How It Works
+
+pgvector runs as a Docker Compose service (`pgvector`) alongside your devcontainer, using the official `pgvector/pgvector:pg16` image, which bundles PostgreSQL 16 with the pgvector extension pre-compiled and ready to use.
+
+**Service configuration:**
+
+- Image: `pgvector/pgvector:pg16`
+- Network: `devnet` (shared with the dev container)
+- Port: `5432` (customisable via `PGVECTOR_PORT`)
+- Volume: `pgvector-data` for persistent data
+
+The following environment variables are pre-set in the devcontainer for seamless `psql` usage:
+
+| Variable     | Value      |
+| ------------ | ---------- |
+| `PGHOST`     | `pgvector` |
+| `PGPORT`     | `5432`     |
+| `PGDATABASE` | `devdb`    |
+| `PGUSER`     | `postgres` |
+
+## Getting Started
+
+```bash
+# Connect to the database
+psql -h pgvector -U postgres -d devdb
+
+# Enable the vector extension (run once per database)
+psql -h pgvector -U postgres -d devdb -c "CREATE EXTENSION IF NOT EXISTS vector;"
+
+# Verify the extension is installed
+psql -h pgvector -U postgres -d devdb -c "SELECT * FROM pg_extension WHERE extname = 'vector';"
+```
+
+## Common Commands
+
+### Vector Operations in SQL
+
+```sql
+-- Enable the extension in your database
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Create a table with a vector column (1536 dimensions for OpenAI embeddings)
+CREATE TABLE documents (
+    id       SERIAL PRIMARY KEY,
+    content  TEXT,
+    embedding vector(1536)
+);
+
+-- Insert a record with an embedding
+INSERT INTO documents (content, embedding)
+VALUES ('Hello, world!', '[0.1, 0.2, 0.3, ...]');
+
+-- Cosine similarity search (find closest neighbours)
+SELECT id, content, 1 - (embedding <=> '[0.1, 0.2, 0.3, ...]') AS similarity
+FROM documents
+ORDER BY embedding <=> '[0.1, 0.2, 0.3, ...]'
+LIMIT 5;
+
+-- Create an HNSW index for faster approximate search
+CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
+
+-- Create an IVFFlat index for large datasets
+CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+```
+
+### Database Management
+
+```bash
+# Connect interactively
+psql
+
+# Run a SQL file
+psql -f schema.sql
+
+# Dump the database
+pg_dump -h pgvector -U postgres devdb > backup.sql
+
+# Restore from dump
+psql -h pgvector -U postgres devdb < backup.sql
+```
+
+### Python Integration
+
+```bash
+pip install psycopg2-binary pgvector
+
+python - <<'EOF'
+import psycopg2
+from pgvector.psycopg2 import register_vector
+import numpy as np
+
+conn = psycopg2.connect(
+    host="pgvector", port=5432,
+    dbname="devdb", user="postgres", password="postgres"
+)
+register_vector(conn)
+cur = conn.cursor()
+
+cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+cur.execute("CREATE TABLE IF NOT EXISTS items (id serial PRIMARY KEY, embedding vector(3))")
+cur.execute("INSERT INTO items (embedding) VALUES (%s)", (np.array([1, 2, 3]),))
+conn.commit()
+
+cur.execute("SELECT * FROM items ORDER BY embedding <-> %s LIMIT 5", (np.array([1, 2, 4]),))
+print(cur.fetchall())
+conn.close()
+EOF
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable            | Default    | Description                                |
+| ------------------- | ---------- | ------------------------------------------ |
+| `PGVECTOR_VERSION`  | `pg16`     | pgvector image tag (e.g. `pg16`, `pg17`)   |
+| `PGVECTOR_DB`       | `devdb`    | Name of the database to create             |
+| `PGVECTOR_USER`     | `postgres` | PostgreSQL superuser name                  |
+| `PGVECTOR_PASSWORD` | `postgres` | PostgreSQL superuser password              |
+| `PGVECTOR_PORT`     | `5432`     | Host port mapped to the PostgreSQL service |
+
+Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize.
+
+## pgvector vs Qdrant
+
+| Feature              | pgvector (this overlay)         | Qdrant                   |
+| -------------------- | ------------------------------- | ------------------------ |
+| **Storage model**    | ✅ Relational + vector          | Vector-only              |
+| **SQL support**      | ✅ Full PostgreSQL SQL          | ❌ REST/gRPC API only    |
+| **Familiar tooling** | ✅ psql, ORMs, existing schema  | New client SDKs required |
+| **Query language**   | ✅ SQL with `<->`, `<=>`, `<#>` | ⚠️ JSON query DSL        |
+| **Filtering**        | ✅ SQL WHERE clause             | ✅ Payload-based filters |
+| **Scale**            | ⚠️ Vertical scaling preferred   | ✅ Distributed by design |
+| **Index types**      | IVFFlat, HNSW                   | HNSW                     |
+
+**Choose pgvector when:**
+
+- You already use PostgreSQL and want to add vectors to existing tables
+- You need to join vector results with relational data
+- Your team is comfortable with SQL
+
+**Choose Qdrant when:**
+
+- Vectors are your primary data model
+- You need purpose-built vector search performance at scale
+- You want advanced filtering and payload storage
+
+## Use Cases
+
+- **RAG pipelines** — Store document embeddings alongside metadata; retrieve context with SQL joins
+- **Semantic search** — Add vector search to an existing PostgreSQL application without a second database
+- **Hybrid search** — Combine full-text search (`tsvector`) with vector similarity in a single query
+- **Recommendation systems** — Store and query user or item embeddings with familiar SQL tooling
+
+**Integrates well with:**
+
+- `ollama` — Generate embeddings locally with `nomic-embed-text` or similar models
+- `python` — `psycopg2` + `pgvector` Python package for seamless integration
+- `nodejs` — `pg` driver with raw SQL for vector operations
+
+## Troubleshooting
+
+### Extension Not Found
+
+If `CREATE EXTENSION vector` fails:
+
+```bash
+# Confirm pgvector image (not plain postgres) is in use
+docker compose ps pgvector
+
+# Check available extensions
+psql -h pgvector -U postgres -c "SELECT name FROM pg_available_extensions WHERE name = 'vector';"
+```
+
+### Port Conflict with postgres Overlay
+
+The `pgvector` and `postgres` overlays both bind port 5432 and conflict with each other. Select only one.
+
+### Connection Refused
+
+```bash
+# Check service health
+docker compose ps pgvector
+docker compose logs pgvector
+```
+
+## References
+
+- [pgvector GitHub](https://github.com/pgvector/pgvector)
+- [pgvector Docker Image](https://hub.docker.com/r/pgvector/pgvector)
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/16/)
+- [pgvector Python package](https://github.com/pgvector/pgvector-python)
+- [pgvector Node.js package](https://github.com/pgvector/pgvector-node)
+
+**Related Overlays:**
+
+- [`postgres`](../postgres/README.md) — Plain PostgreSQL without pgvector (conflicts)
+- [`qdrant`](../qdrant/README.md) — Purpose-built vector database (alternative)
+- [`ollama`](../ollama/README.md) — Local embedding generation
+- [`python`](../python/README.md) — Python development environment

package/overlays/pgvector/devcontainer.patch.json

@@ -0,0 +1,23 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["pgvector"],
+    "forwardPorts": [5432],
+    "portsAttributes": {
+        "5432": {
+            "label": "pgvector database",
+            "onAutoForward": "notify"
+        }
+    },
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "postgresql-client",
+            "apk": "postgresql-client"
+        }
+    },
+    "containerEnv": {
+        "PGHOST": "pgvector",
+        "PGPORT": "5432",
+        "PGDATABASE": "devdb",
+        "PGUSER": "postgres"
+    }
+}

package/overlays/pgvector/docker-compose.yml

@@ -0,0 +1,32 @@
+version: '3.8'
+
+services:
+    pgvector:
+        image: pgvector/pgvector:${PGVECTOR_VERSION:-{{cs.PGVECTOR_VERSION}}}
+        restart: unless-stopped
+        volumes:
+            - pgvector-data:/var/lib/postgresql/data
+        environment:
+            POSTGRES_DB: ${PGVECTOR_DB:-{{cs.PGVECTOR_DB}}}
+            POSTGRES_USER: ${PGVECTOR_USER:-{{cs.PGVECTOR_USER}}}
+            POSTGRES_PASSWORD: ${PGVECTOR_PASSWORD:-{{cs.PGVECTOR_PASSWORD}}}
+        ports:
+            - '${PGVECTOR_PORT:-{{cs.PGVECTOR_PORT}}}:5432'
+        networks:
+            - devnet
+        healthcheck:
+            test:
+                [
+                    'CMD-SHELL',
+                    'pg_isready -U ${PGVECTOR_USER:-{{cs.PGVECTOR_USER}}} -d ${PGVECTOR_DB:-{{cs.PGVECTOR_DB}}}',
+                ]
+            interval: 10s
+            timeout: 5s
+            retries: 5
+            start_period: 10s
+
+volumes:
+    pgvector-data:
+
+networks:
+    devnet:

package/overlays/pgvector/overlay.yml

@@ -0,0 +1,44 @@
+id: pgvector
+name: pgvector (PostgreSQL + vector)
+description: PostgreSQL 16 with the pgvector extension for vector similarity search
+category: database
+supports:
+    - compose
+requires: []
+suggests:
+    - ollama
+    - python
+    - nodejs
+conflicts:
+    - postgres
+tags:
+    - database
+    - sql
+    - vector
+    - embeddings
+    - postgres
+    - pgvector
+ports:
+    - port: 5432
+      service: pgvector
+      protocol: tcp
+      description: pgvector database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'postgresql://{pgvector_user}:{pgvector_password}@{host}:{port}/{pgvector_db}'
+parameters:
+    PGVECTOR_DB:
+        description: Name of the database to create
+        default: devdb
+    PGVECTOR_USER:
+        description: PostgreSQL superuser name
+        default: postgres
+    PGVECTOR_PASSWORD:
+        description: PostgreSQL superuser password
+        default: postgres
+        sensitive: true
+    PGVECTOR_PORT:
+        description: Host port mapped to pgvector (5432 inside container)
+        default: '5432'
+    PGVECTOR_VERSION:
+        description: pgvector/pgvector image tag (e.g. pg16, pg17)
+        default: pg16

package/overlays/playwright/devcontainer.patch.json

@@ -5,5 +5,7 @@
             "version": "lts"
         }
     },
-    "postCreateCommand": "npx -y playwright install --with-deps chromium"
+    "postCreateCommand": {
+        "setup-playwright": "bash .devcontainer/scripts/setup-playwright.sh"
+    }
 }

package/overlays/playwright/setup.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Playwright setup script — Install Chromium browser + system dependencies
+
+set -e
+
+# Source shared setup utilities (provides load_nvm, acquire_apt_lock)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
+echo "🎭 Setting up Playwright..."
+
+# Suppress Playwright's "WARNING: no project dependencies" banner, apt output,
+# and download progress bars.
+export DEBIAN_FRONTEND=noninteractive
+export CI=1  # suppresses interactive warnings inside playwright install
+
+# Install Chromium and its system dependencies.
+# playwright install --with-deps calls apt-get internally; we must hold the
+# shared apt lock so it does not race with other parallel setup scripts.
+acquire_apt_lock
+npx -y playwright install --with-deps chromium 2>&1 \
+    | grep -vEe '^[╔║╚]' \
+               -e '^\|[[:space:]■]*\|' \
+               -e '^(Get:|Fetched|Reading|Building dependency|Processing triggers|Setting up|Preparing to|Selecting previously|Unpacking|Need to get|After this operation|The following )' \
+               -e '(is already the newest version|set to manually installed|npm notice|debconf:|update-alternatives:)' \
+               -e '^\(Reading database'
+rc=${PIPESTATUS[0]}
+release_apt_lock
+
+if [ "$rc" -ne 0 ]; then
+    echo "❌ Playwright browser installation failed (exit $rc)"
+    exit "$rc"
+fi
+
+echo "✓ Playwright setup complete"
+echo "ℹ️  Run 'npx playwright test' to execute tests"