Makefile.toml

###############################################################################
# cargo-make tasks
#
# Usage:
#   cargo make diagrams           # generate all diagrams
#   cargo make diagram-algorithm  # generate the algorithm diagram only
#
# This uses mermaid-cli (mmdc). If you don't have it installed, the task will
# try to use npx to run @mermaid-js/mermaid-cli without a global install.
###############################################################################

[config]
skip_core_tasks = true

[tasks.default]
description = "Generate diagrams and VHS demo tapes"
category = "Documentation"
dependencies = ["diagrams", "tapes"]

[tasks.diagrams]
description = "Generate all diagrams (SVG, transparent)"
category = "Documentation"
dependencies = ["diagram-algorithm"]

[tasks.diagram-algorithm]
description = "Render diagrams/algorithm.mmd -> assets/algorithm.svg"
category = "Documentation"
script_runner = "bash"
script = [
    """
    set -euo pipefail
    echo "[diagram] generating docs/assets/algorithm.svg from docs/diagrams/algorithm.mmd"
    mkdir -p docs/assets
    if ! command -v npx >/dev/null 2>&1; then
      echo "Error: 'npx' not found. Please install Node.js (which provides npx)." >&2
      exit 1
    fi
    npx -y @mermaid-js/mermaid-cli@10 mmdc -i docs/diagrams/algorithm.mmd -o docs/assets/algorithm.svg --backgroundColor transparent --configFile docs/diagrams/mermaid.config.json --cssFile docs/diagrams/mermaid.css
    test -s docs/assets/algorithm.svg || { echo "Error: docs/assets/algorithm.svg not generated" >&2; exit 1; }
    if command -v node >/dev/null 2>&1; then
      node docs/diagrams/postprocess.js docs/assets/algorithm.svg || echo "[diagram] postprocess skipped/failed, continuing"
    else
      echo "[diagram] node not found; skipping SVG post-process for layering"
    fi
    echo "[diagram] generated docs/assets/algorithm.svg"
    """,
]

# ---------------------------------------------------------------------------
# VHS terminal demo tapes -> GIF/MP4/WebM
#
# Usage:
#   cargo make tapes           # render all docs/tapes/*.tape to docs/assets/tapes
#   cargo make tape-one        # example single-tape render (see task for env var)
#
# Requirements:
#   - vhs must be installed and available on PATH: https://github.com/charmbracelet/vhs
#     (If not present, the task will exit with an instructive error.)
# ---------------------------------------------------------------------------

[tasks.tapes]
description = "Render all VHS tapes in docs/tapes into docs/assets/tapes"
category = "Documentation"
script_runner = "bash"
script = [
    '''
    set -euo pipefail
    ROOT_DIR=$(pwd)
    echo "[tapes] building target/release/hson"
    cargo build --release --bin hson
    HSON_DIR="$ROOT_DIR/target/release"
    test -x "$HSON_DIR/hson" || { echo "Error: $HSON_DIR/hson not found after build" >&2; exit 1; }
    TAPES_DIR=docs/tapes
    OUT_DIR=docs/assets/tapes
    mkdir -p "$OUT_DIR"
    mkdir -p "$ROOT_DIR/.cache"
    if ! command -v vhs >/dev/null 2>&1; then
      echo "Error: 'vhs' not found on PATH. Install from https://github.com/charmbracelet/vhs" >&2
      exit 1
    fi
    shopt -s nullglob
    files=("$TAPES_DIR"/*.tape)
    if [ ${#files[@]} -eq 0 ]; then
      echo "[tapes] no .tape files found in $TAPES_DIR; nothing to do"
      exit 0
    fi
    for tape in "${files[@]}"; do
      echo "[tapes] rendering $tape"
      tape_dir=$(dirname "$tape")
      tape_base=$(basename "$tape")
      if [ "$tape_base" = "sort.tape" ]; then
        sort_repo=$(mktemp -d -t headson-sort-tape-XXXXXX)
        (
          set -euo pipefail
          cd "$sort_repo"
          git init -q
          git config user.email demo@example.com
          git config user.name demo
          git config commit.gpgsign false
          mkdir -p data src
          printf '%s\n' '{"alpha":1}' > data/alpha.json
          printf '%s\n' '{"zeta":0}' > data/zeta.json
          printf '%s\n' 'print("hello")' > src/main.py
          printf '%s\n' 'export function add(a: number, b: number) { return a + b; }' > src/util.ts
          git add .
          git commit -qm 'init'
          printf '%s\n' '{"zeta":1}' > data/zeta.json
          git add data/zeta.json
          git commit -qm 'touch zeta'
          printf '%s\n' '{"zeta":2}' > data/zeta.json
          git add data/zeta.json
          git commit -qm 'touch zeta again'
        )
      fi
      # Collect declared outputs from the tape (relative to tape_dir)
      mapfile -t outputs < <(sed -n 's/^Output[[:space:]]\+//p' "$tape") || true
      # Run vhs from the tape directory so relative Output paths land there
      (
        cd "$tape_dir"
        PATH="$HSON_DIR:$PATH" \
        R="${sort_repo:-}" \
        GIT_TERMINAL_PROMPT=0 \
        vhs "$tape_base"
      )
      # Move declared outputs to OUT_DIR (if any declared); else try a sane default GIF name
      if [ ${#outputs[@]} -gt 0 ]; then
        for o in "${outputs[@]}"; do
          # Only move known media types
          case "$o" in
            *.gif|*.mp4|*.webm)
              src="$tape_dir/$o"
              if [ -f "$src" ]; then
                echo "[tapes] -> $OUT_DIR/$(basename "$o")"
                mv -f "$src" "$OUT_DIR/$(basename "$o")"
              else
                echo "[tapes] warning: declared output not found: $src" >&2
              fi
              ;;
            *) ;;
          esac
        done
      else
        # Fallback: if the tape name is demo.tape, try demo.gif
        guess="$tape_dir/${tape_base%.tape}.gif"
        if [ -f "$guess" ]; then
          echo "[tapes] -> $OUT_DIR/$(basename "$guess")"
          mv -f "$guess" "$OUT_DIR/$(basename "$guess")"
        fi
      fi
      if [ "${tape_base}" = "sort.tape" ]; then
        rm -rf "$sort_repo"
      fi
    done
    echo "[tapes] done"
    ''',
]



[tasks.tape-one]
description = "Render a single VHS tape (env TAPE=<path>)"
category = "Documentation"
script_runner = "bash"
script = [
    '''
    set -euo pipefail
    ROOT_DIR=$(pwd)
    echo "[tape-one] building target/release/hson"
    cargo build --release --bin hson
    HSON_DIR="$ROOT_DIR/target/release"
    test -x "$HSON_DIR/hson" || { echo "Error: $HSON_DIR/hson not found after build" >&2; exit 1; }
    : "${TAPE:?Set TAPE to a .tape file, e.g., TAPE=docs/tapes/demo.tape}"
    OUT_DIR=docs/assets/tapes
    mkdir -p "$OUT_DIR"
    mkdir -p "$ROOT_DIR/.cache"
    if ! command -v vhs >/dev/null 2>&1; then
      echo "Error: 'vhs' not found on PATH. Install from https://github.com/charmbracelet/vhs" >&2
      exit 1
    fi
    tape="$TAPE"
    tape_dir=$(dirname "$tape")
    tape_base=$(basename "$tape")
    if [ "$tape_base" = "sort.tape" ]; then
      sort_repo=$(mktemp -d -t headson-sort-tape-XXXXXX)
      (
        set -euo pipefail
        cd "$sort_repo"
        git init -q
        git config user.email demo@example.com
        git config user.name demo
        git config commit.gpgsign false
        mkdir -p data src
        printf '%s\n' '{"alpha":1}' > data/alpha.json
        printf '%s\n' '{"zeta":0}' > data/zeta.json
        printf '%s\n' 'print("hello")' > src/main.py
        printf '%s\n' 'export function add(a: number, b: number) { return a + b; }' > src/util.ts
        git add .
        git commit -qm 'init'
        printf '%s\n' '{"zeta":1}' > data/zeta.json
        git add data/zeta.json
        git commit -qm 'touch zeta'
        printf '%s\n' '{"zeta":2}' > data/zeta.json
        git add data/zeta.json
        git commit -qm 'touch zeta again'
      )
    fi
    mapfile -t outputs < <(sed -n 's/^Output[[:space:]]\+//p' "$tape") || true
    (
      cd "$tape_dir"
      PATH="$HSON_DIR:$PATH" \
      R="${sort_repo:-}" \
      GIT_TERMINAL_PROMPT=0 \
      vhs "$tape_base"
    )
    if [ ${#outputs[@]} -gt 0 ]; then
      for o in "${outputs[@]}"; do
        case "$o" in
          *.gif|*.mp4|*.webm)
            [ -f "$tape_dir/$o" ] && mv -f "$tape_dir/$o" "$OUT_DIR/$(basename "$o")" || echo "[tape-one] missing: $o" >&2
            ;;
          *) ;;
        esac
      done
    fi
    if [ "${tape_base}" = "sort.tape" ]; then
      rm -rf "$sort_repo"
    fi
    echo "[tape-one] done"
    ''',
]