Prompt hydrator example from Incus Codex jail blog post

0000-hydrate_prompt.py

#!/usr/bin/env python3
import argparse
import re
import sys
from pathlib import Path

# Platzhalter-Syntax: {{ include:... }}
PLACEHOLDER_RE = re.compile(r'{{\s*include\s*:\s*([^}]+?)\s*}}')

def hydrate(prompt_path: Path, output_path: Path, src_dir_name: str) -> None:
    base_dir = prompt_path.parent
    src_dir = (base_dir / src_dir_name).resolve()
    text = prompt_path.read_text(encoding="utf-8")

    def resolve_include(rel_name: str) -> Path:
        rel_name = rel_name.strip()
        path = Path(rel_name)

        # 1. Absoluter Pfad?
        if path.is_absolute():
            return path

        # 2. Pfad enthält bereits einen Slash → relativ zum Prompt-Verzeichnis
        if "/" in rel_name or "\\" in rel_name:
            return (base_dir / rel_name).resolve()

        # 3. Sonst: Datei im src_dir
        return (src_dir / rel_name).resolve()

    def replace(match: re.Match) -> str:
        rel_name = match.group(1).strip()
        file_path = resolve_include(rel_name)

        if not file_path.exists():
            print(
                f"[WARN] Included file not found: {file_path} (from '{rel_name}')",
                file=sys.stderr,
            )
            return match.group(0)

        try:
            content = file_path.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            print(
                f"[WARN] Could not read {file_path} as UTF-8. "
                "Leaving placeholder unchanged.",
                file=sys.stderr,
            )
            return match.group(0)

        # Für die Kommentare einen hübschen, relativen Pfad erzeugen
        try:
            rel_display = file_path.relative_to(base_dir)
        except ValueError:
            rel_display = file_path

        return (
            f"\n<!-- BEGIN include:{rel_display} -->\n"
            f"{content.rstrip()}\n"
            f"<!-- END include:{rel_display} -->\n"
        )

    hydrated = PLACEHOLDER_RE.sub(replace, text)
    output_path.write_text(hydrated, encoding="utf-8")


def main():
    parser = argparse.ArgumentParser(
        description="Hydrate a prompt.md by inlining external Markdown snippets."
    )
    parser.add_argument(
        "prompt",
        nargs="?",
        default="prompt.md",
        help="Base prompt file (default: prompt.md)",
    )
    parser.add_argument(
        "-o",
        "--output",
        default=None,
        help="Output file (default: <prompt>.hydrated.md)",
    )
    parser.add_argument(
        "--src-dir",
        default="0000-source",
        help="Directory where included files live (default: 0000-source)",
    )

    args = parser.parse_args()
    prompt_path = Path(args.prompt).resolve()

    if not prompt_path.exists():
        print(f"[ERROR] Prompt file not found: {prompt_path}", file=sys.stderr)
        raise SystemExit(1)

    if args.output:
        output_path = Path(args.output).resolve()
    else:
        # prompt.md → prompt.md.hydrated.md
        output_path = prompt_path.with_suffix(prompt_path.suffix + ".hydrated.md")

    hydrate(prompt_path, output_path, args.src_dir)

    print(
        f"[OK] Wrote hydrated prompt to: {output_path} "
        f"(src-dir: {args.src_dir})",
        file=sys.stderr,
    )


if __name__ == "__main__":
    main()

2026-02-23-example.1.prompt.md

// ./0000-hydrate_prompt.py 2026-02-23-example.1.prompt.md -o 2026-02-23-example.1.prompt.hydrated.md --src-dir ./

This is an example prompt file just to demonstrate the use of the ./0000-hydrate_prompt.py script:

{{ include:./.context/sources.md }}

README.md

Prompt Hydrator

This repository is a small example used in the blog post Incus System-Container Jail for the Codex Coding Agent / MCP Servers.
It shows a simple prompt hydration workflow that inlines {{ include:... }} placeholders into a Markdown prompt.

More background and context are in the blog post.

Usage

python 0000-hydrate_prompt.py 2026-02-23-example.1.prompt.md -o 2026-02-23-example.1.prompt.hydrated.md --src-dir ./

Optional Context Hub integration:

make ctx-install  # network required
make ctx

Optional repomix bundle generation:

make repomix
# or pass through repomix flags:
make repomix REPOMIX_ARGS="--output repomix-output.txt"

ctx.sh

#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CTX_BIN="${CTX_BIN:-$ROOT/.bin/ctx}"
if [ ! -x "$CTX_BIN" ]; then
  if command -v ctx >/dev/null 2>&1; then
    CTX_BIN="$(command -v ctx)"
  else
    echo "ctx binary not found. Run ./scripts/install_ctx.sh (network required) or set CTX_BIN to an existing ctx." >&2
    exit 1
  fi
fi
cd "$ROOT"
"$CTX_BIN" build --config-file ctx.yaml "$@"

ctx.yaml

$schema: 'https://raw.githubusercontent.com/context-hub/generator/refs/heads/main/json-schema.json'
documents:
  - description: "Sources"
    outputPath: "sources.md"
    sources:
      - type: file
        sourcePaths: ["./"]
        filePattern:
          - "0000-*.py"

install_ctx.sh

#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
DEST="${CTX_BIN_DIR:-$ROOT/.bin}"
mkdir -p "$DEST"
echo "Installing ctx to $DEST ..."
curl -sSL https://raw.githubusercontent.com/context-hub/generator/main/download-latest.sh | bash -s "$DEST"
echo "ctx installed at $DEST/ctx"

Makefile

# Makefile for prompt hydration + ctx/repomix helpers

SHELL := /bin/bash
.SHELLFLAGS := -eu -o pipefail -c
.NOTPARALLEL:
.DEFAULT_GOAL := help

CTX_CONFIG  ?= ctx.yaml
CTX_LOCAL   ?= ./.bin/ctx
CTX_INSTALL ?= ./scripts/install_ctx.sh
REPOMIX_RUN ?= ./scripts/repomix.sh
REPOMIX_ARGS ?=

.PHONY: help ctx ctx-check ctx-install repomix

help:
	@echo "Available targets:"
	@echo "  make repomix      Build repomix output (uses scripts/repomix.sh)"
	@echo "  make ctx-check    Verify ctx is available"
	@echo "  make ctx-install  Install ctx to ./.bin (network required)"
	@echo "  make ctx          Build context docs from ctx.yaml"

repomix:
	@set -e; \
	if [ ! -x "$(REPOMIX_RUN)" ]; then \
	  echo "ERROR: repomix script not found or not executable at '$(REPOMIX_RUN)'"; \
	  exit 1; \
	fi; \
	bash "$(REPOMIX_RUN)" $(REPOMIX_ARGS)


## CTX integration (optional)
ctx-check:
	@set -e; \
	CTX_BIN="$(CTX_LOCAL)"; \
	if [ ! -x "$$CTX_BIN" ]; then \
	  if command -v ctx >/dev/null 2>&1; then \
	    CTX_BIN="$$(command -v ctx)"; \
	  else \
	    echo "ERROR: CTX binary not found at '$(CTX_LOCAL)' and 'ctx' is not in PATH."; \
	    if [ -f "$(CTX_INSTALL)" ]; then \
	      echo "Fix: run 'make ctx-install' (network required)"; \
	    fi; \
	    exit 1; \
	  fi; \
	fi

ctx: ctx-check
	@set -e; \
	CTX_BIN="$(CTX_LOCAL)"; \
	if [ ! -x "$$CTX_BIN" ]; then \
	  CTX_BIN="$$(command -v ctx)"; \
	fi; \
	"$$CTX_BIN" build --config-file "$(CTX_CONFIG)"

ctx-install:
	@set -e; \
	if [ ! -f "$(CTX_INSTALL)" ]; then \
	  echo "ERROR: install script not found at '$(CTX_INSTALL)'"; \
	  exit 1; \
	fi; \
	bash "$(CTX_INSTALL)"

repomix.sh

#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
IGNORE="node_modules,.git,.uv-cache,.mypy_cache,__pycache__,.pytest_cache,report.xlsx,.ipynb_checkpoints,scaffolding,nbs"
cd "$ROOT"
npx repomix@1.7.0 --ignore "$IGNORE" "$@"