#!/usr/bin/env bash
# vim: filetype=bash :  -*- mode: sh; sh-shell: bash; -*-

set -euo pipefail

define() { IFS= read -rd '' "$1" || : ; }

myname="${0##*/}"

define pod <<"=cut"

=encoding utf-8

=for html <p align="center"><img src="https://raw.githubusercontent.com/tecolicom/App-dozo/main/images/dozo-logo.png" width="400"></p>

=head1 NAME

dozo - Dôzo, Docker with Zero Overhead

=head1 SYNOPSIS

dozo -I IMAGE [ options ] [ command ... ]

    -h, --help         show help
        --version      show version
        --bundle       print a self-contained dozo
    -d, --debug        debug mode (show full command)
    -x, --trace        trace mode (set -x)
    -q, --quiet        quiet mode
    -n, --dryrun       dry-run mode

    -I, --image=#      Docker image (required unless -D)
    -D, --default      use default image
    -A, --auto-pull    pull newer image before running
    -F, --with=#       add features to the image (repeatable)
    -E, --env=#        environment variable to inherit (repeatable)
    -W, --mount-cwd    mount current working directory
    -H, --mount-home   mount home directory
    -U, --unmount      do not mount any directory
        --mount-mode=# mount mode (rw or ro, default: rw)
    -R, --mount-ro     mount read-only (shortcut for --mount-mode=ro)
    -V, --volume=#     additional volume to mount (repeatable)
    -B, --batch        batch mode (non-interactive)
    -L, --live         use live (persistent) container
    -N, --name=#       live container name
    -K, --kill         kill and remove existing container
    -P, --port=#       port mapping (repeatable)
    -O, --other=#      additional docker options (repeatable)
    -S, --status       show live containers and derived images

=head1 VERSION

Version 1.03

=head1 USAGE

When executed without arguments, Dôzo starts an interactive shell
inside the container.  When arguments are given, they are executed as
a command.

    dozo -I alpine                  # start shell
    dozo -I alpine ls -la           # run command

By setting C<-D> or your favorite image with C<-I> in F<~/.dozorc>,
you can simply run Dôzo without specifying an image.  Since the git
top directory is automatically mounted, git commands work as expected
from anywhere in the tree.

    $ dozo                          # start shell
    $ dozo git log -p               # run git log -p

With C<-L> option, you can use a persistent container.  Tools
installed in the container will remain available for subsequent use.

    $ dozo -L                       # start shell and create container
    # apt update && apt install -y cowsay
    # exit
    $ dozo -L /usr/games/cowsay Dôzo
     ______
    < Dôzo >
     ------
            \   ^__^
             \  (oo)\_______
                (__)\       )\/\
                    ||----w |
                    ||     ||

=cut

[[ $pod =~ Version\ +([0-9.]+) ]] && my_version=${BASH_REMATCH[1]}

# -h callback: show help from POD
help() {
    sed -E \
        -e '/^$/N' \
        -e 's/^(\n*)=head[0-9]* */\1/' \
        -e '/^\n*[#=]/d' \
        -e '/Version/q' \
        <<< "$pod"
    exit 0
}

# --version callback: show version
version() {
    echo "$my_version"
    exit 0
}

# --bundle callback: print this script with getoptlong.sh inserted
# after the first line, so that the result runs as a single file.  It
# exits while the options are parsed, before the buffered messages are
# printed.  A script that is bundled already (it has the mark) is
# printed as it is.
GOL_MARK='# getoptlong.sh embedded by dozo --bundle'
bundle() {
    local self=${BASH_SOURCE[0]} gol= dir
    if grep -qxF "$GOL_MARK" "$self"; then
        cat "$self"
        exit 0
    fi
    local IFS=:
    for dir in $PATH; do
        [[ -r ${dir:-.}/getoptlong.sh ]] && { gol=${dir:-.}/getoptlong.sh; break; }
    done
    unset IFS
    # like ".", fall back to the current directory
    [[ $gol || ! -r getoptlong.sh ]] || gol=./getoptlong.sh
    [[ $gol ]] || die "getoptlong.sh not found in PATH"
    head -n 1 "$self"
    echo "$GOL_MARK"
    echo "# getoptlong.sh version $GOL_VERSION"
    sed -e 1d "$gol"
    echo "# end of getoptlong.sh"
    sed -e 1d "$self"
    exit 0
}

# -x callback: trace mode
trace() { [[ $2 ]] && set -x || set +x; }

##############################################################################
# Utility functions
##############################################################################

_warn_buffer=()
warn() { _warn_buffer+=("$*"); }

debug() {
    [[ $debug ]] && echo "debug: $*" >&2 || true
}

die() {
    echo "$myname: $*" >&2
    exit 1
}

# Check bash version (4.4+ required for getoptlong.sh)
if ((BASH_VERSINFO[0] < 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] < 4))); then
    die "bash 4.4+ required (found $BASH_VERSION)"
fi

git_topdir() {
    [[ $(git rev-parse --is-inside-work-tree 2>/dev/null) == true ]] || return
    local dir="$(git rev-parse --show-superproject-working-tree)"
    [[ $dir ]] || dir="$(git rev-parse --show-toplevel)"
    echo "$dir"
}

# Address of the interface used for the default route
get_ip() {
    local ip= dev=
    if command -v ip > /dev/null 2>&1; then
        ip=$(ip -4 route get 1.1.1.1 2>/dev/null |
                 sed -n 's/.* src \([0-9.]*\).*/\1/p')
    elif command -v ipconfig > /dev/null 2>&1; then
        dev=$(route -n get default 2>/dev/null | sed -n 's/.*interface: *//p')
        [[ $dev ]] && { ip=$(ipconfig getifaddr "$dev" 2>/dev/null) || ip= ; }
    fi
    echo "$ip"
}

# -N NAME, or the image name followed by the mounted directory name
container_name() {
    [[ $name ]] && { echo "$name"; return; }
    local base=$myname dir=${mount_dir:-$cwd}
    [[ $image =~ (.*/)?([-_.a-zA-Z0-9]+) ]] && base=${BASH_REMATCH[2]}
    echo "$base${dir:+.${dir##*/}}"
}

docker_find() {
    local OPT OPTARG OPTIND status=() id
    while getopts "s:" OPT; do
        case $OPT in
            s) status+=("$OPTARG") ;;
        esac
    done
    shift $((OPTIND - 1))
    id=$(command docker ps -a -q ${status[@]/#/-f status=} -f name="^/$1\$")
    [[ $id ]] && echo "$id" || return 1
}

docker_status() {
    command docker inspect --format='{{.State.Status}}' "$1"
}

docker() {
    debug "docker $*"
    [[ $dryrun ]] && { echo docker "$@"; return; }
    command docker "$@"
}

# -A: the command runs on the local image when the pull fails, as it
# does when offline.  Standard output belongs to the command.
# With --with, with_image tells when there is no local image either.
pull_image() {
    if [[ $quiet ]]; then
        docker pull --quiet "$image" > /dev/null
    else
        docker pull "$image" >&2
    fi || {
        pull_failed=1
        (( ${#with_names[@]} > 0 )) || warn "cannot pull $image, using the local image"
    }
}

##############################################################################
# --with: features
##############################################################################

# Path of the feature NAME (a file, or a directory with a Dockerfile)
feature_path() {
    local n=$1
    [[ ! $n || $n == */* || $n == .* ]] && die "invalid feature name: $n"
    [[ -e $feature_dir/$n ]] || die "feature $n not found in $feature_dir"
    echo "$feature_dir/$n"
}

# cksum of the content of a feature: the file, or the names and
# contents of all files in the directory
# Files made by Finder and editors do not count
feature_sum() {
    local p=$1 f
    if [[ -d $p ]]; then
        (
            cd "$p" || exit 1
            find . \( -name .DS_Store -o -name '*~' -o -name '.*.sw?' \
                      -o -name '#*#' -o -name '.#*' \) -prune \
                   -o -type f -print |
            LC_ALL=C sort | while IFS= read -r f; do
                printf '%s\n' "$f"
                cat "$f"
            done
        ) | cksum
    else
        cksum < "$p"
    fi
}

image_id() { command docker image inspect --format '{{.Id}}' "$1" 2>/dev/null; }

# Find the user and the home directory of the base image, once
feature_env() {
    [[ ${build_home:-} ]] && return
    [[ $dryrun ]] && return    # nothing is run, and the build is only shown
    orig_user=$(command docker image inspect --format '{{.Config.User}}' "$image" 2>/dev/null) || orig_user=
    build_user=${orig_user:-root}
    build_home=$(command docker run --rm --entrypoint sh \
                     ${orig_user:+--user "$orig_user"} "$image" -c 'echo "$HOME"') \
        || die "cannot find the home directory of $image (sh is required)"
    [[ $build_home ]] || die "cannot find the home directory of $image"
}

# feature_build FROM_NAME TAG NAME PATH
# FROM_NAME is the image name for FROM: BuildKit does not take an ID
feature_build() {
    local parent=$1 tag=$2 name=$3 path=$4 arg=${5:-} src args
    src=$path
    [[ -d $path ]] && src=$path/Dockerfile
    [[ -r $src ]] || die "cannot read $src"
    feature_env
    # the argument is given by --build-arg, not written in the Dockerfile
    args=(build --label "dozo.base=$image" --label "dozo.with=${with_chain:-$name}"
          --build-arg "DOZO_ARG=$arg" -t "$tag")
    if [[ -d $path ]]; then args+=(-f - "$path"); else args+=(-); fi
    {
        printf 'FROM %s\nARG DOZO_USER=%s\nARG DOZO_HOME=%s\nARG DOZO_ARG\n' \
               "$parent" "${build_user:-}" "${build_home:-}"
        printf '%s\n' "$(cat "$src")"
        if [[ ${orig_user:-} ]]; then printf 'USER %s\n' "$orig_user"; fi
    } | if [[ $dryrun ]]; then
        cat > /dev/null    # the Dockerfile is not used: keep the writer from SIGPIPE
        if [[ $quiet ]]; then docker "${args[@]}" > /dev/null; else docker "${args[@]}"; fi
    elif [[ $quiet ]]; then
        docker "${args[@]:0:1}" --quiet "${args[@]:1}" > /dev/null
    else
        docker "${args[@]}" >&2
    fi || die "cannot build feature $name"
}

# Make the image with the features on $image, and set run_image to it.
# -c: do not build, return 1 when an image is missing.
with_image() {
    local check= n i from path parent_id tag sum base part value arg
    local paths=() names=() fargs=()
    [[ ${1:-} == -c ]] && check=1
    # NAME/ARG: the argument is all after the first slash
    for n in "${with_names[@]}"; do
        arg=
        [[ $n == */* ]] && arg=${n#*/}
        n=${n%%/*}
        path=$(feature_path "$n") || exit 1
        paths+=("$path") names+=("$n${arg:+/$arg}") fargs+=("$arg")
    done
    base=$myname
    [[ $image =~ (.*/)?([-_.a-zA-Z0-9]+) ]] && base=${BASH_REMATCH[2]}
    if parent_id=$(image_id "$image"); then
        [[ $auto_pull && ${pull_failed:-} ]] && warn "cannot pull $image, using the local image"
    else
        [[ $check ]] && return 1
        if [[ $auto_pull ]]; then
            # -A has pulled it already: do not try again
            [[ $dryrun ]] && parent_id=$image \
                || die "cannot find image $image (the pull failed)"
        else
            pull_image
            # dryrun: the pull was only shown, the image ID stays unknown
            parent_id=$(image_id "$image") || { [[ $dryrun ]] && parent_id=$image; } \
                || die "cannot find image $image"
        fi
    fi
    with_chain=
    from=$image
    for i in "${!with_names[@]}"; do
        n=${names[i]} path=${paths[i]} arg=${fargs[i]}
        with_chain+=${with_chain:+,}$n
        sum=$(feature_sum "$path") || exit 1
        # without an argument, the tag is the same as before arguments
        sum=$(printf '%s\n' "$parent_id" "$sum" ${arg:+"$arg"} | cksum)
        value=${sum%% *}
        part=${n//[^A-Za-z0-9_.-]/_}
        [[ $part == [-.]* ]] && part=_${part:1}
        (( ${#part} + 1 + ${#value} > 128 )) && part=${part:0:127-${#value}}
        tag=dozo/$base:$part-$value
        # one inspect finds the stage and gives the ID for the next parent
        if ! parent_id=$(image_id "$tag"); then
            # -c: run_image tells the stage which is missing
            [[ $check ]] && { run_image=$tag; return 1; }
            feature_build "$from" "$tag" "$n" "$path" "$arg"
            # dryrun: the stage was only shown, the tag stands for its ID
            parent_id=$(image_id "$tag") || { [[ $dryrun ]] && parent_id=$tag; } \
                || die "cannot find image $tag"
        fi
        from=$tag
        run_image=$tag
    done
}

##############################################################################
# Main
##############################################################################

# Default environment variables to inherit
DEFAULT_ENV=(
    LANG TZ
    HTTP_PROXY HTTPS_PROXY
    http_proxy https_proxy
    TERM_PROGRAM TERM_BGCOLOR COLORTERM
    DEEPL_AUTH_KEY
    OPENAI_API_KEY
    ANTHROPIC_API_KEY
    LLM_PERPLEXITY_KEY
)

# Initialize variables
top_dir=$(git_topdir) || top_dir=
cwd=$(pwd)
default_image=tecolicom/xlate
export DOCKER_CLI_HINTS=false
workdir=/work
# decided from the host's HOME, before -H can change anything
feature_dir=${XDG_CONFIG_HOME:-$HOME/.config}/dozo/features
localtime=/etc/localtime
mount_dir=
mounting=
container=
container_status=
relative=
display=

# Set default volume based on git directory
[[ $top_dir && $top_dir != "$cwd" ]] && mount_dir="$top_dir"

##############################################################################
# Read .dozorc
##############################################################################

# Collect .dozorc paths in reverse priority order (lowest first)
declare -a rcpath=()
[[ $HOME != "$cwd" ]] && rcpath+=("$HOME")
[[ $top_dir && $top_dir != "$cwd" && $top_dir != "$HOME" ]] && rcpath+=("$top_dir")
rcpath+=(.)

# Collect options from .dozorc files; rc_files and rc_counts keep the
# file and the number of words of each, to tell where an option is from
declare -a rc_opts=() rc_files=() rc_counts=()
for dir in "${rcpath[@]}"; do
    rc="$dir/.dozorc"
    [[ -r $rc ]] || continue
    rc_files+=("$( [[ $dir == . ]] && echo "$cwd" || echo "$dir" )/.dozorc")
    rc_n=${#rc_opts[@]}
    warn "reading $rc"
    lineno=0
    while IFS= read -r line || [[ $line ]]; do
        ((++lineno))
        [[ $line && $line != \#* ]] || continue
        err=$(xargs printf '%s\0' <<< "$line" 2>&1 > /dev/null) \
            || die "$rc line $lineno: ${err:-parse error}: $line"
        while IFS= read -r -d '' arg; do
            rc_opts+=("$arg")
        done < <(xargs printf '%s\0' <<< "$line")
    done < "$rc"
    rc_counts+=($(( ${#rc_opts[@]} - rc_n )))
done

##############################################################################
# Option definitions
##############################################################################

define USAGE <<END
Dôzo - Generic Docker Runner

Usage: $myname [ options ] [ command ... ]
END

default() { image="${DOZO_DEFAULT_IMAGE:-$default_image}"; image_set; }
# image_from: where -I or -D is given, a .dozorc or "command line"
# image_given: -I or -D is on the command line, not only in .dozorc
image_set() {
    image_from=$in_from image_given=
    [[ $in_from == "command line" ]] && image_given=1
    return 0
}

declare -A OPTS=(
    [&USAGE]="$USAGE" [&PERMUTE]= [&REQUIRE]=1.1.0 [&DELIM]=,
    [       help | h ! # show help                       ]=
    [    version |   ! # show version                    ]=
    [     bundle |   ! # print self-contained dozo       ]=
    [      debug | d   # debug mode                      ]=
    [      trace | x ! # trace mode (set -x)             ]=
    [      quiet | q   # quiet mode                      ]=
    [     dryrun | n   # dry-run mode                    ]=
    [      image | I : # Docker image                    ]=
    [    default | D ! # use default image               ]=
    [  auto-pull | A   # pull newer image before running ]=
    [        env | E @ # environment variable to inherit ]=
    [  mount-cwd | W   # mount current working directory ]=
    [ mount-home | H   # mount home directory            ]=
    [    unmount | U   # do not mount any directory      ]=
    [ mount-mode |   : # mount mode (rw or ro)           ]=rw
    [   mount-ro | R   # mount read-only                 ]=
    [     volume | V @ # additional volume to mount      ]=
    [      batch | B   # batch mode (non-interactive)    ]=
    [       live | L   # use live container              ]=
    [       name | N : # live container name             ]=
    [       kill | K   # kill existing container         ]=
    [       port | P @ # port mapping                    ]=
    [      other | O @ # additional docker option        ]=
    [       with | F @ # add features to the image        ]=
    [     status | S   # show the status, change nothing ]=
)

##############################################################################
# Parse options
##############################################################################

# getoptlong.sh is loaded unless dozo --bundle has embedded it; "-"
# keeps the arguments of dozo away from it meanwhile
declare -F getoptlong >/dev/null || . getoptlong.sh -
# Each .dozorc, then the command line, to tell where the image is from
args=("$@") in_from= image_from= image_given= rc_stop=
getoptlong init OPTS && getoptlong callback image image_set
rc_i=0
for rc_k in "${!rc_files[@]}"; do
    in_from=${rc_files[rc_k]}
    # "getoptlong set" takes the rest from the positional parameters
    set -- "${rc_opts[@]:rc_i:rc_counts[rc_k]}"
    (( rc_i += rc_counts[rc_k] )) || :
    getoptlong parse "$@" && eval "$(getoptlong set)"
    if (( $# > 0 )); then rc_stop=1; break; fi
done
if [[ $rc_stop ]]; then
    # a word in .dozorc ends the options: the rest is the command
    set -- "$@" "${rc_opts[@]:rc_i}" "${args[@]}"
else
    in_from="command line"
    set -- "${args[@]}"
    getoptlong parse "$@" && eval "$(getoptlong set)"
fi

# Flush buffered warnings
warn() { [[ $quiet ]] || echo "$*" >&2; }
for _m in "${_warn_buffer[@]}"; do warn "$_m"; done; _warn_buffer=()

# List options are split at commas only ([&DELIM] above), so that -E,
# -V and --with can take a value with spaces.  Trim each element, and
# split -P and -O at spaces too, but not at a space escaped with a
# backslash (read without -r), as before.
list_trim() {
    local -n _list=$1
    local _v _new=()
    for _v in "${_list[@]}"; do
        _v=${_v#"${_v%%[![:space:]]*}"}
        _v=${_v%"${_v##*[![:space:]]}"}
        [[ $_v ]] && _new+=("$_v")
    done
    _list=("${_new[@]}")
}
list_split() {
    local -n _list=$1
    local _v _w _new=()
    for _v in "${_list[@]}"; do
        read -a _w <<< "$_v"
        _new+=("${_w[@]}")
    done
    _list=("${_new[@]}")
}
list_trim env; list_trim volume; list_trim with
list_split port; list_split other
# --with: names separated by commas, in the order given
with_names=("${with[@]}")

# Apply options
[[ $mount_cwd ]] && mount_dir="$cwd"
[[ $mount_home ]] && { mount_dir="$HOME"; DEFAULT_ENV+=(HOME=$workdir); }
[[ $mount_ro ]] && mount_mode=ro  # -R overrides --mount-mode

# env_opts and tty_opts are used by both docker run and docker exec (-L)

# Merge environment variables
ENV=("${DEFAULT_ENV[@]}" "${env[@]}")
env_opts=()
for e in "${ENV[@]}"; do env_opts+=(-e "$e"); done

# -B: do not wait for a terminal, but pass piped input
tty_opts=()
[[ ! $batch || ! -t 0 ]] && tty_opts+=(--interactive)
[[ ! $batch && -t 0 ]] && tty_opts+=(--tty)

# Determine working directory in the container
if [[ ! $unmount && $mount_dir && $mount_dir != "$cwd" ]]; then
    mounting=1
    [[ ${cwd#"$mount_dir"/} != "$cwd" ]] && relative="${cwd#"$mount_dir"/}"
fi
container_workdir="${workdir}${relative:+/${relative}}"

##############################################################################
# Find the live container of this directory
##############################################################################

# A live container has the label dozo.mount of the directory mounted.
# Without an image on the command line and a name, -L and -K use the
# container of this directory.  A name made from -I must not be of another directory:
# the container would run the command on the files of that directory.
# The physical path, so that a directory reached through a symlink is
# the same directory
live_mount=$(cd "${mount_dir:-$cwd}" 2>/dev/null && pwd -P) || live_mount=${mount_dir:-$cwd}
name_given=$name

# -S: the errors of finding the container are told in the status
status_notes=()
live_fail() {
    [[ $status ]] || die "$@"
    status_notes+=("$*")
    return 1
}
if [[ $status ]]; then
    (( $# == 0 )) || die "--status takes no command"
    command docker ps -a -q > /dev/null || die "cannot ask docker"
fi

# An image in .dozorc is a default: the container of this directory is
# used before it, but not before -I or -D on the command line
# (-S shows what -L would do)
found=()
if [[ ($live || $kill || $status) && ! ($image && $image_given) && ! $name ]]; then
    while IFS= read -r _n; do [[ $_n ]] && found+=("$_n"); done < <(
        command docker ps -a --filter "label=dozo.mount=$live_mount" --format '{{.Names}}')
    if (( ${#found[@]} > 1 )); then
        live_fail "containers for $live_mount: ${found[*]}; choose one with -I or -N" || :
    fi
    if (( ${#found[@]} == 1 )); then
        name=${found[0]} name_given=$name image=
        # -KL makes it again: from the image it was made from
        if [[ $kill && $live ]]; then
            image=$(command docker inspect \
                        --format '{{index .Config.Labels "dozo.image"}}' "$name") || image=
            [[ $image ]] || live_fail "the image of container $name is unknown; give it with -I" || :
        fi
    fi
fi

# die if the container ID is of another directory
live_check_mount() {
    [[ $name_given ]] && return 0
    local mount
    mount=$(command docker inspect --format '{{index .Config.Labels "dozo.mount"}}' "$1") || return 0
    [[ ! $mount || $mount == "$live_mount" ]] \
        || live_fail "container $container is for $mount, not $live_mount; give another name with -N"
}

# live_notices ID FUNC [BASE]: tell with FUNC what does not change the
# existing container ID (-L, and the notes of -S).  --with is checked
# on BASE, $image by default
live_notices() {
    local id=$1 tell=$2 base=${3-$image}
    [[ $auto_pull ]] && $tell "-A does not change existing container $container, use -K to recreate it"
    if (( ${#with_names[@]} > 0 )); then
        local image=$base
        if ! with_image -c || [[ $(command docker inspect --format '{{.Image}}' "$id") \
                               != $(image_id "$run_image") ]]; then
            $tell "--with does not change existing container $container, use -K to recreate it"
        fi
    elif [[ $image && ! $auto_pull ]]; then
        # the container name does not tell the tag or the owner of the image
        if [[ $(command docker inspect --format '{{.Image}}' "$id") != $(image_id "$image") ]]; then
            $tell "existing container $container is not made from $image, use -K to recreate it"
        fi
    fi
    return 0
}

##############################################################################
# Show the status
##############################################################################

# -S prints these parts in order, and changes nothing:
#
#   status_here        what -L (and -K, -A, --with) would do here, and why
#   status_containers  the live containers made by dozo
#   status_images      the derived images made by --with
#   to clean up:       the commands collected in status_cleanup
#
# The parts pass on what a later one needs:
#
#   status_with_image  the image --with would run here (marks an image)
#   status_used        the images containers use (cannot be removed)
#   status_cleanup     the commands to remove what is not needed
#
# The notes of status_here are the errors live_fail has kept, and the
# notices of live_notices: the same as -L would tell.

status_with_image= status_used=() status_cleanup=()

status_main() {
    local c
    status_here
    echo
    status_containers
    echo
    status_images
    if (( ${#status_cleanup[@]} > 0 )); then
        echo
        echo "to clean up:"
        for c in "${status_cleanup[@]}"; do echo "  $c"; done
    fi
}

#
# Output helpers
#

# status_line LABEL TEXT
status_line() { printf '  %-10s %s\n' "$1" "$2"; }
status_note() { status_line note "$*"; }

# ~ for the home directory
status_path() {
    local p=$1
    [[ $p == "$HOME" || $p == "$HOME"/* ]] && p="~${p#"$HOME"}"
    echo "$p"
}

# split_tab ARRAY LINE: fields separated by tabs, empty ones kept
# ("read" with IFS=$'\t' would join empty fields)
split_tab() {
    local -n _f=$1
    local _l=$2
    _f=()
    while [[ $_l == *$'\t'* ]]; do _f+=("${_l%%$'\t'*}"); _l=${_l#*$'\t'}; done
    _f+=("$_l")
}

# status_table HEADER ROW...: columns of tab separated fields, the
# first field is the mark (* or empty)
status_table() {
    local row i w=() f
    for row in "$@"; do
        split_tab f "$row"
        for i in "${!f[@]}"; do (( ${#f[i]} > ${w[i]:-0} )) && w[i]=${#f[i]}; done
    done
    for row in "$@"; do
        split_tab f "$row"
        printf '%-1s' "${f[0]}"
        for i in "${!f[@]}"; do
            (( i )) || continue
            # one space after the mark, two between the columns
            printf '%*s%-*s' "$(( i > 1 ? 2 : 1 ))" '' \
                   "$(( i < ${#f[@]} - 1 ? w[i] : 0 ))" "${f[i]}"
        done
        echo
    done | sed 's/ *$//'
}

#
# Here: the directory, image, container, --with, -K and -A, notes
#

# The pieces share the locals of status_here:
#   shown, from  the image of the container and where it is given
#   how          how the container is found
#   id           the ID of the container, empty when there is none
#   stop         -L and -K would stop with the error of a note
status_here() {
    local shown from how id= stop= note kl=
    [[ $kill && $live ]] && kl=1
    echo "$live_mount:"
    status_here_image
    status_here_container
    status_here_with
    status_here_kill
    for note in "${status_notes[@]}"; do status_note "$note"; done
    # in a subshell: an unknown feature is told by status_here_with
    if [[ $id && ! $kill && ! $stop ]]; then
        ( live_notices "$id" status_note "$shown" ) 2>/dev/null || :
    fi
}

status_here_image() {
    shown=$image from=$image_from
    if (( ${#found[@]} == 1 )); then
        how="found by label" from="label of $name"
        # -KL has the image of the label already
        if [[ ! $kl ]]; then
            shown=$(command docker inspect \
                        --format '{{index .Config.Labels "dozo.image"}}' "$name") || shown=
        fi
    elif [[ $name ]]; then
        how="found by name, -N"
    elif [[ $image_given ]]; then
        how="found by name, from -I"
    else
        how="found by name, from .dozorc"
    fi
    if [[ $shown ]]; then status_line image "$shown ($from)"; else status_line image none; fi
}

status_here_container() {
    local cstatus
    if (( ${#found[@]} > 1 )); then
        status_line container "several containers: ${found[*]}"
        stop=1
        return 0
    fi
    container=$(container_name)
    if id=$(docker_find "$container"); then
        live_check_mount "$id" || stop=1
        cstatus=$(docker_status "$id") || cstatus=unknown
        status_line container "$container, $cstatus ($how)"
    elif [[ $image ]]; then
        status_line container "$container, none: would create from $image"
    else
        status_line container "no live container for $live_mount; an image must be specified with -I"
    fi
    # -KL without the image of the label
    [[ $kl && ${#found[@]} == 1 && ! $image ]] && stop=1
    return 0
}

# --with: the image with the features, on the image of the container
status_here_with() {
    (( ${#with_names[@]} > 0 )) || return 0
    local check
    check=$( (
        image=$shown run_image=
        if [[ ! $image ]]; then echo "the image is not decided"
        elif with_image -c; then echo "$run_image (exists)"
        elif [[ $run_image ]]; then echo "$run_image, not built yet: made when used"
        else echo "$image is not here yet: made when used"
        fi
    ) 2>&1 ) || :
    status_line --with "$(IFS=,; echo "${with_names[*]}"): ${check#"$myname: "}"
    [[ $check == *" (exists)" ]] && status_with_image=${check% (exists)}
    return 0
}

status_here_kill() {
    if [[ $stop ]]; then
        # -L and -K stop with the error of the note: nothing is removed
        [[ $kill ]] && status_line -K "would stop: see the note, nothing is removed"
    elif [[ $id ]]; then
        [[ $kill ]] || return 0
        status_line -K "would remove $container"
        if [[ $live && $image ]]; then
            status_line '' "then create from $image"
        elif [[ $live ]]; then
            status_line '' "then no live container for $live_mount; an image must be specified with -I"
        fi
        [[ $auto_pull && $live && $image ]] && status_line -A "would pull $image"
    else
        [[ $kill ]] && status_line -K "nothing to remove"
        [[ $auto_pull && $image ]] && status_line -A "would pull $image"
    fi
    return 0
}

#
# Live containers
#

# dozo's live containers: with the label dozo.mount, or with
# DOZO_RUNNING_ON_DOCKER (made before the labels); not those of --rm
status_containers() {
    local ids=() line f rows=() mark dir phys notes img id
    local cname cstate autorm cid cimage lmount limage marker source
    local fmt='{{.Name}}	{{.State.Status}}	{{.HostConfig.AutoRemove}}	{{.Image}}	{{.Config.Image}}	{{index .Config.Labels "dozo.mount"}}	{{index .Config.Labels "dozo.image"}}	{{range .Config.Env}}{{if eq . "DOZO_RUNNING_ON_DOCKER=1"}}dozo{{end}}{{end}}	{{range .Mounts}}{{if eq .Destination "/work"}}{{.Source}}{{end}}{{end}}'
    echo "live containers:"
    while IFS= read -r line; do [[ $line ]] && ids+=("$line"); done < <(command docker ps -a -q)
    if (( ${#ids[@]} > 0 )); then
        while IFS= read -r line; do
            [[ $line ]] || continue
            split_tab f "$line"
            cname=${f[0]#/} cstate=${f[1]} autorm=${f[2]} cid=${f[3]} cimage=${f[4]}
            lmount=${f[5]} limage=${f[6]} marker=${f[7]} source=${f[8]}
            # an image a container uses cannot be removed
            status_used+=("$cimage")
            [[ $autorm == true ]] && continue
            [[ $lmount || $marker ]] || continue
            notes=() mark=
            dir=${lmount:-$source}
            img=${limage:-$cimage}
            [[ $lmount ]] || notes+=("no label")
            if [[ ! $dir ]]; then
                # made with -U, or the mount is not known: not gone
                notes+=("directory unknown")
            elif phys=$(cd "$dir" 2>/dev/null && pwd -P); then
                [[ $phys == "$live_mount" ]] && mark='*'
            else
                notes+=(gone)
                status_cleanup+=("docker rm $cname")
            fi
            # made with --with: run from the derived image
            [[ $limage && $cimage != "$limage" ]] && notes+=("with $cimage")
            if id=$(image_id "$cimage") && [[ $id != "$cid" ]]; then
                notes+=("image updated, -KL to recreate")
            fi
            rows+=("$mark	$cname	$cstate	$img	$(status_path "$dir")	$(IFS=,; echo "${notes[*]}" | sed 's/,/, /g')")
        done < <(command docker inspect --format "$fmt" "${ids[@]}")
    fi
    if (( ${#rows[@]} > 0 )); then
        status_table "	NAME	STATUS	IMAGE	DIRECTORY	NOTE" "${rows[@]}"
    else
        echo "  none"
    fi
}

#
# Derived images
#

# The images made by --with (label dozo.base), and whether --with would
# use them now: made from the features and the base images as they are
status_images() {
    local line f tags=() ids=() created=() labels=() rows=() i state mark tag u used
    local base with
    echo "derived images:"
    while IFS= read -r line; do
        [[ $line ]] || continue
        split_tab f "$line"
        tags+=("${f[0]}") ids+=("${f[1]}") created+=("${f[2]}")
    done < <(command docker image ls --filter label=dozo.base \
                 --format '{{.Repository}}:{{.Tag}}	{{.ID}}	{{.CreatedSince}}')
    if (( ${#ids[@]} > 0 )); then
        # by ID: an image whose tag is taken by a newer one is <none>:<none>
        while IFS= read -r line; do labels+=("$line"); done < <(
            command docker image inspect \
                --format '{{index .Config.Labels "dozo.base"}}	{{index .Config.Labels "dozo.with"}}' \
                "${ids[@]}")
    fi
    for i in "${!ids[@]}"; do
        split_tab f "${labels[i]:-}"
        base=${f[0]} with=${f[1]:-} tag=${tags[i]} mark=
        state=$(status_image_state "$base" "$with" "$tag") || state="feature gone"
        [[ $tag == "$status_with_image" ]] && mark='*'
        if [[ $state != current ]]; then
            used=
            for u in "${status_used[@]}"; do [[ $u == "$tag" ]] && used=1; done
            [[ $tag == "<none>:<none>" ]] && tag=${ids[i]}
            [[ $used ]] || status_cleanup+=("docker image rm $tag")
        fi
        rows+=("$mark	${tags[i]}	$base	$with	$state	${created[i]}")
    done
    if (( ${#rows[@]} > 0 )); then
        status_table "	IMAGE	BASE	WITH	STATE	CREATED" "${rows[@]}"
    else
        echo "  none"
    fi
}

# status_image_state BASE WITH TAG: current, outdated or base gone;
# fails when a feature is gone.  In a subshell: with_image exits then.
status_image_state() (
    image=$1 run_image=
    IFS=, read -ra with_names <<< "$2"
    image_id "$image" > /dev/null || { echo "base gone"; exit; }
    with_image -c > /dev/null 2>&1 || :
    [[ $run_image ]] || exit 1
    [[ $run_image == "$3" ]] && echo current || echo outdated
)

[[ $status ]] && { status_main; exit 0; }

##############################################################################
# Kill container
##############################################################################

if [[ $kill ]]; then
    container=$(container_name)
    if id=$(docker_find "$container"); then
        live_check_mount "$id"
        docker rm -f "$container" | sed -e "s/\$/ ($id) is removed/"
    fi
    [[ $live ]] || exit 0
fi

##############################################################################
# Live container handling
##############################################################################

# Run the command in the running container ID, or attach to it
live_exec() {
    local id=$1; shift
    if (( $# > 0 )); then
        local exec_opts=("${tty_opts[@]}")
        [[ ! $unmount && $relative ]] && exec_opts+=(--workdir "$container_workdir")
        docker exec "${exec_opts[@]}" "${env_opts[@]}" "$id" "$@"
    else
        warn "attaching to container $container ($id)"
        docker attach "$id"
    fi
}

if [[ $live ]]; then
    container=$(container_name)
    if id=$(docker_find "$container"); then
        live_check_mount "$id"
        live_notices "$id" warn
        container_status=$(docker_status "$id")
        case $container_status in
            created|exited)
                action=starting
                [[ $container_status == exited ]] && action=restarting
                warn "$action $container_status container $container ($id)"
                docker start "$id" > /dev/null || exit 1
                [[ $dryrun ]] && container_status=running && debug "fake container_status=running"
                ;;
            paused)
                warn "unpausing container $container ($id)"
                docker unpause "$id" || exit 1
                [[ $dryrun ]] && container_status=running && debug "fake container_status=running"
                ;;
            running)
                ;;
            *)
                warn "unknown status $container_status of $container ($id)"
                ;;
        esac
    else
        debug "container not found"
    fi
    if [[ $container_status == running ]] || id=$(docker_find -s running "$container"); then
        live_exec "$id" "$@"
        exit
    fi
    [[ $image ]] || die "no live container for $live_mount; an image must be specified with -I"
    warn "create live container \"$container\""
fi

##############################################################################
# Run container
##############################################################################

[[ $image ]] || die "Docker image must be specified with -I option"

[[ $auto_pull ]] && pull_image

# --with: the image to run is the one with the features added
run_image=$image
if (( ${#with_names[@]} > 0 )); then with_image; fi

[[ $mounting ]] && warn "mount $mount_dir to $workdir"

if [[ ${DISPLAY:-} ]]; then
    ip=$(get_ip)
    [[ $ip ]] && display="$ip:0"
fi
hostname=${image##*/}
hostname=${hostname%%:*}

# -L with a command: start the default command (shell) in the
# background and exec the command in it, so that the container keeps
# running after the command.  An image with an entrypoint is run with
# the command as before, because the command is its argument.
detach=
if [[ $live ]] && (( $# > 0 )); then
    # an image which is not here yet is pulled by docker run below
    entrypoint=$(command docker image inspect \
                     --format '{{json .Config.Entrypoint}}' "$run_image" 2>/dev/null) \
        || entrypoint=
    [[ $entrypoint == @(|null|\[\]) ]] && detach=1
fi

declare -a dockopt=(
    -e DOZO_RUNNING_ON_DOCKER=1
    -e XLATE_RUNNING_ON_DOCKER=1
    --init
)
if [[ $detach ]]; then
    dockopt+=(--detach --interactive --tty)
else
    dockopt+=("${tty_opts[@]}")
fi
[[ ! $live       ]] && dockopt+=(--rm)
[[   $live       ]] && dockopt+=(--name "$container"
                         --label "dozo.mount=$live_mount" --label "dozo.image=$image"
                         --label "dozo.version=$my_version")
[[ -e $localtime ]] && dockopt+=(-v $localtime:$localtime:ro)
[[ ! $unmount    ]] && dockopt+=(
        -v "${mount_dir:-$cwd}:${workdir}:${mount_mode}"
        -w "$container_workdir"
    )
for v in "${volume[@]}"; do
    if [[ $v != *:* ]]; then
        [[ $v == /* ]] || v="$cwd/$v"
        v="$v:$v"
    fi
    dockopt+=(-v "$v")
done
for p in "${port[@]}"; do
    [[ $p == *:* ]] || p="${p%/*}:$p"
    dockopt+=(-p "$p")
done
dockopt+=(
    "${env_opts[@]}"
    ${hostname:+--hostname "$hostname"}
    ${display:+-e DISPLAY="$display"}
    "${other[@]}"
)

# Display docker run info
if [[ ! $quiet ]]; then
    info="image=${image} env=${#ENV[@]}"
    [[ $live ]] && info+=" container=${container}"
    (( $# > 0 )) && info+=" command=$*"
    warn "docker run ${info}"
fi

if [[ $detach ]]; then
    # standard output belongs to the command, not to the container ID
    if [[ $dryrun ]]; then
        docker run "${dockopt[@]}" "${run_image}"
    else
        docker run "${dockopt[@]}" "${run_image}" > /dev/null || exit 1
    fi
    live_exec "$container" "$@"
    exit
fi

docker run "${dockopt[@]}" "${run_image}" "$@"
exit

: <<'=cut'

=head1 INSTALLATION

Using L<cpanminus|https://metacpan.org/pod/App::cpanminus>:

    cpanm -n App::dozo

To install the latest version from GitHub:

    cpanm -n https://github.com/tecolicom/App-dozo.git

Alternatively, you can simply place C<dozo> and C<getoptlong.sh> in
your PATH.

A self-contained single file, which needs no other part of the
distribution, is attached to each release on GitHub; download it and
place it in your PATH:

    curl -fsSLo ~/.local/bin/dozo \
        https://github.com/tecolicom/App-dozo/releases/download/VERSION/dozo
    chmod +x ~/.local/bin/dozo

The same file is made by C<dozo --bundle> from an installed B<Dôzo>,
also inside the default image once it carries a B<Dôzo> with this
option:

    docker run --rm tecolicom/xlate dozo --bundle > dozo

B<Dôzo> requires Bash 4.4 or later, as does the C<getoptlong.sh>
script it uses.

=head1 DESCRIPTION

B<Dôzo> is a generic Docker runner that simplifies running commands in
Docker containers.  The name comes from the Japanese word "dôzo"
(どうぞ) meaning "please" or "go ahead", and also stands for "B<D>ocker
with B<Z>ero B<O>verhead".  The command name is C<dozo> for ease of
typing.

It automatically configures the tedious Docker options such as volume
mounts, environment variables, working directories, and interactive
terminal settings, so you can focus on the command you want to run.

B<Dôzo> is distributed as a standalone module and can be used as a
general-purpose Docker runner. It was originally developed as part of
L<App::Greple::xlate> and is used by L<xlate> for Docker operations.

B<Dôzo> uses L<getoptlong.sh|https://github.com/tecolicom/getoptlong>
for option parsing.

=head2 Key Features

=over 4

=item B<Git Friendly>

If you are working in a git environment, the git top directory is
automatically mounted. Otherwise the current directory is mounted.
When the current directory is under the git top directory, the
corresponding subdirectory in the container is used as the working
directory.

=item B<Live Container>

Use C<-L> to create or attach to a persistent container that survives
between invocations. Container names are automatically generated from
the image name and mount directory.

=item B<Environment Inheritance>

Common environment variables are automatically inherited: C<LANG>,
C<TZ>, proxy settings, terminal settings, and API keys for AI/LLM
services (DeepL, OpenAI, Anthropic, Perplexity).

=item B<Flexible Mounting>

The directory is mounted on F</work> in the container, and it is used
as the working directory. Various mount options are available: current
directory (C<-W>), home directory (C<-H>), additional volumes (C<-V>),
read-only mode (C<-R>), or no mount (C<-U>).

=item B<X11 Support>

When C<DISPLAY> is set, the address of the interface used for the
default route is detected and passed to the container as C<DISPLAY>,
enabling GUI applications.

=item B<Configuration File>

Use C<.dozorc> to set default options. Loaded from the home directory,
the git top directory, and the current directory, in that order, so
that a closer file takes precedence.

=item B<Standalone Operation>

B<Dôzo> can operate independently of L<xlate>. The C<getoptlong.sh>
script is provided by the L<Getopt::Long::Bash> CPAN distribution,
which is installed as a dependency. Alternatively, you can place
C<getoptlong.sh> in your C<PATH> manually.

=back

=head1 OPTIONS

Repeatable options (B<-E>, B<-V>, B<-P>, B<-O> and B<--with>) can be
given more than once, and a single value is also split into multiple
elements at commas; spaces around a comma are ignored.  Thus
C<-P 8000,9000> gives two port mappings.  B<-P> and B<-O> are split
at spaces and tabs as well, so B<-O> with the value C<--memory 2g>
gives two docker options.  The others keep spaces in a value: B<-E>
with the value C<MSG=hello world> defines one variable.  Use
B<--no->I<option> (e.g. B<--no-with>) to discard the values given so
far, including those in F<.dozorc>.

=over 7

=item B<-h>, B<--help>

Show help message.

=item B<--version>

Show version number.

=item B<--bundle>

Print a self-contained B<Dôzo>, which includes what it needs from
the distribution, and exit without running Docker.  The result is a
single file that runs where only Bash 4.4 or later and Docker are
available:

    dozo --bundle > ~/.local/bin/dozo-single

A file made this way prints itself again.

=item B<-d>, B<--debug>

Enable debug mode. Shows the full docker command line that will be executed.

=item B<-x>, B<--trace>

Enable trace mode (set -x).

=item B<-q>, B<--quiet>

Quiet mode. Suppress the informational line printed to standard error
before the container is started:

    docker run image=alpine env=13 command=echo hi

It summarizes the image name, the number of environment variables to be
inherited, the container name (with B<-L>) and the command to be
executed. This line is shown regardless of B<-n>; use B<-d> to see the
whole docker command line instead.

=item B<-n>, B<--dryrun>

Dry-run mode. Show docker commands without executing them.
Useful for testing and debugging.

=item B<-I> I<image>, B<--image>=I<image>

Specify Docker image. Required unless C<-D> is given, but you can put
it in F<.dozorc> so you don't have to type it every time.

=item B<-D>, B<--default>

Use the default Docker image. If C<DOZO_DEFAULT_IMAGE> environment
variable is set, use that image. Otherwise, use C<tecolicom/xlate>,
that is, its C<latest> tag. See L</DEFAULT IMAGE> section for details
about the default image.

=item B<-A>, B<--auto-pull>

Run C<docker pull> before running the command, so that a newer image
is downloaded when the registry has one.  Nothing is downloaded
without this option once the image is on the machine.  When the pull
fails, as it does when offline, a warning is shown and the command
runs on the local image.

An existing live container stays as it is, on the image it was created
from; use C<-KL> to recreate it.

=item B<-E> I<name>[=I<value>], B<--env>=I<name>[=I<value>]

Specify environment variable to pass to the container. If I<value> is
omitted, the value is inherited from the host environment. Repeatable.

=item B<-W>, B<--mount-cwd>

Mount current working directory.

=item B<-H>, B<--mount-home>

Mount home directory. The C<HOME> environment variable in the
container is set to the mount point (F</work>).

=item B<-U>, B<--unmount>

Do not mount any directory.

=item B<--mount-mode>=I<mode>

Set mount mode of the automatically mounted directory. I<mode> is
either C<rw> (read-write, default) or C<ro> (read-only). This does not
affect volumes given by B<-V>; append C<:ro> to them instead.

=item B<-R>, B<--mount-ro>

Mount directory as read-only. Shortcut for C<--mount-mode=ro>.

=item B<-V> I<path>, B<-V> I<from>:I<to>, B<--volume>=I<from>:I<to>

Specify additional directory to mount. If only I<path> is given
(without C<:>), it is mounted to the same path in the container; a
relative path is resolved against the current directory. Repeatable.

=item B<-B>, B<--batch>

Run in batch mode (non-interactive): the container gets no terminal
and does not wait for input from one.  Input from a pipe or a file is
still passed to the command, as in C<git diff | dozo -B cdif>.

=item B<-L>, B<--live>

Use live (persistent) container.

=item B<-N> I<name>, B<--name>=I<name>

Specify container name explicitly.

=item B<-K>, B<--kill>

Kill and remove existing container.

=item B<-P> I<port>, B<-P> I<host>:I<container>, B<--port>=I<host>:I<container>

Specify port mapping. If only I<port> is given (without C<:>), it is
mapped to the same port in the container (e.g., C<-P 8000> becomes
C<8000:8000>, and C<-P 8000/udp> becomes C<8000:8000/udp>).
Repeatable.

=item B<-O> I<option>, B<--other>=I<option>

Specify additional docker options. Repeatable.

=item B<-F> I<name>[/I<arg>][,...], B<--with>=I<name>[/I<arg>][,...]

Run the image with the named features added.  A feature is a piece of
Dockerfile kept in F<~/.config/dozo/features/> (or under
C<XDG_CONFIG_HOME>), and the image made from the base image with the
features applied in order is used instead of the base image.  A name
may be followed by C</> and an argument for the feature.  Names are
separated by comma, and the option is repeatable: values given in
F<.dozorc> and on the command line accumulate (F<.dozorc> first).
See L</FEATURES> section for details.

=item B<-S>, B<--status>

Show the status, and change nothing: what B<-L> would do here and
why (the mounted directory, the image and where it is given, the
container it would use or make, the image of B<--with>), the live
containers and the derived images made by B<dozo>, and the commands
to remove those which are no longer used.  Nothing is pulled, built,
started or removed.  It takes no command.  Give it with other options
to see what they would do: C<dozo -I alpine -S>, C<dozo --with locale
-S>, C<dozo -KL -S>.  See L</Show the status>.

=back

=head1 INTERACTIVE MODE

The container is started with Docker's C<--interactive> option, and
C<--tty> is added as well when the standard input is a terminal (TTY).
With the B<-B> (batch) option, neither is given when the standard
input is a terminal, so that nothing waits for keyboard input; when
the standard input is a pipe or a file, C<--interactive> is still
given so that the input reaches the command.  The same rule is
applied to C<docker exec> in live container mode.

This allows seamless interactive use when attaching to containers or
running interactive commands.

=head1 LIVE CONTAINER

The C<-L> option enables live (persistent) container mode. Unlike
normal mode where containers are removed after execution (C<--rm>),
live containers persist between invocations, allowing you to maintain
state and reduce startup overhead.

=head2 Container Lifecycle

When C<-L> is specified, B<Dôzo> behaves as follows:

=over 4

=item 1. B<Container does not exist>

Create a new persistent container (without C<--rm> flag).  Without a
command, the container is started with the image's default command
(usually a shell) and you are connected to it.  With a command, the
container is started in the background with the default command,
and then the command is executed in it as in case 2.  So you can
build up an environment from the first invocation, even in batch
mode:

    dozo -L -B apt-get install -y foo
    dozo -L -B pip install bar

If the image has an entrypoint, the command is given to it as
arguments, and the container stops when it finishes.

=item 2. B<Container exists and is running>

If a command is given, execute it using C<docker exec>. Otherwise,
attach to the container using C<docker attach>.

=item 3. B<Container exists but is paused>

Unpause the container with C<docker unpause>, then proceed as above.

=item 4. B<Container exists but is not started>

If the container is in the C<created> or C<exited> state, start it
with C<docker start>, then proceed as above.

=back

=head2 Container Naming

Container names are automatically generated in the format:

    <image_name>.<mount_directory>

For example, if you run:

    dozo -I tecolicom/xlate -L

from C</home/user/project>, the container name would be
C<xlate.project>.

The name is made from the last part of the image name only, without
the tag, the owner or the registry: C<alpine> and C<alpine:3.18>, or
C<tecolicom/xlate> and C<other/xlate>, give the same name, and an
existing container is used for both.  When the image of the existing
container differs from the one given by B<-I>, B<dozo> tells so; use
B<-K> to recreate the container, or B<-N> to give another name.

You can override the auto-generated name using the C<-N> option:

    dozo -I tecolicom/xlate -L -N mycontainer

The name also has only the last part of the mounted directory, so
F</a/project> and F</b/project> give the same name.  A live container
has the label C<dozo.mount> with the full physical path of the
mounted directory (a directory reached through a symlink is the same
directory), C<dozo.image> with the image given by B<-I>, and
C<dozo.version> with the version of B<dozo> that made it.  If the
container found by a name made from B<-I> is of another
directory, B<dozo> stops instead of running the command on the files
of that directory; give another name with B<-N>.  A name given by
B<-N> is not checked, and nor is a container made by an older
B<dozo>, which has no label.

=head2 Managing Live Containers

=over 4

=item B<Use the container of this directory>

    dozo -I myimage -L          # start working
    dozo -L                     # later: connect to the same container
    dozo -L make test           # run a command in it
    dozo -KL                    # make it again from the same image
    dozo -K                     # remove it

When neither B<-I>, B<-D> nor B<-N> is on the command line, B<-L>
and B<-K> use the container made for the mounted directory, found by
its C<dozo.mount> label.  In a git repository this is the top
directory, so the same container is used from any subdirectory.  If
there are several of them (made from different images), B<dozo> lists
them; choose one with B<-I> or B<-N>.  B<-KL> makes the container
again from the image in its C<dozo.image> label.

An image set in F<.dozorc> (by B<-I> or B<-D>) is a default: it is
used only when there is no container for the directory.  So with
B<-D> in F<~/.dozorc>, B<dozo -L> connects to the container started
by B<dozo -I myimage -L> in this directory, and to the one of the
default image elsewhere.  B<-I> or B<-D> on the command line always
chooses the container of that image.

=item B<Attach to existing container>

    dozo -I myimage -L

If no command is given, attaches to the container's main process.

=item B<Execute command in existing container>

    dozo -I myimage -L ls -la

Runs the command in the existing container using C<docker exec>.
Environment variables are passed just as for a new container, and when
the current directory is under the mounted directory, the
corresponding subdirectory is used as the working directory.

=item B<Kill and recreate container>

    dozo -I myimage -KL

The C<-K> option removes the existing container before C<-L> creates
a new one. Useful when you need a fresh container state.

=item B<Kill container only>

    dozo -I myimage -K

Without C<-L>, the container is removed and the command exits.

=item B<Show the status>

    dozo -S

Shows what B<dozo -L> would do in this directory, and lists the live
containers and the derived images (see L</Derived Images>):

    /home/me/project:
      image      tecolicom/xlate (/home/me/.dozorc)
      container  xlate.project, exited (found by label)
      --with     locale: dozo/xlate:locale-3580643729 (exists)

    live containers:
      NAME           STATUS  IMAGE            DIRECTORY   NOTE
    * xlate.project  exited  tecolicom/xlate  ~/project   with dozo/xlate:locale-3580643729
      xlate.old      exited  tecolicom/xlate  ~/old       no label, gone

    derived images:
      IMAGE                         BASE             WITH    STATE     CREATED
    * dozo/xlate:locale-3580643729  tecolicom/xlate  locale  current   2 hours ago
      dozo/brew:locale-2017098170   homebrew/brew    locale  outdated  3 days ago

    to clean up:
      docker rm xlate.old
      docker image rm dozo/brew:locale-2017098170

C<*> marks what this directory uses.  The containers are those made
by B<dozo> (also those made before the C<dozo.mount> label, shown with
C<no label>), and not those run without B<-L>.  A container whose
directory does not exist any more (C<gone>) is to clean up; one whose
image has been updated since it was made can be made again with
B<-KL>.  Where B<-L> would stop with an error (several containers for
the directory, a container of another directory), the status tells it
as a C<note> instead.  B<dozo> removes nothing: copy the commands
under C<to clean up> to remove them.

=back

=head1 FEATURES

A I<feature> is a named piece of Dockerfile that is added to any
image.  It is a way to bring your usual setup (locale, dot files,
environment variables, ...) to an image made by someone else:

    dozo -I homebrew/brew --with locale,home make test

Features are not bundled with B<dozo>; you write your own.

=head2 Feature Directory

Features are looked up in
F<${XDG_CONFIG_HOME:-$HOME/.config}/dozo/features/>.  A name which
contains C</> or starts with C<.> is rejected, and a missing feature
is an error.  A feature takes one of two forms.

=over 4

=item B<File>

F<features/NAME> is a fragment of Dockerfile (C<RUN>, C<ENV>, C<USER>,
and so on).

=item B<Directory>

F<features/NAME/Dockerfile> is the fragment, and the directory itself
is the build context, so C<COPY> can copy files in it.  Files made by
Finder and editors (F<.DS_Store>, F<*~>, F<.*.sw?>, F<#*#>, F<.#*>)
do not cause a rebuild, but they are still in the context, and so is
F<Dockerfile> itself; C<COPY . ...> copies them too.  To keep them
out of the image, list them in F<.dockerignore>:

    Dockerfile
    .dockerignore
    .DS_Store
    *~
    .*.sw?

=back

B<dozo> gives these values as Dockerfile C<ARG>:

=over 4

=item C<DOZO_USER>

The user of the base image (C<root> if the image sets none).

=item C<DOZO_HOME>

The home directory of that user.

=item C<DOZO_ARG>

The argument given as I<name>C</>I<arg> (empty without it).

=back

A feature may switch to C<USER root>.  At the end of each feature,
B<dozo> restores the original user of the base image (nothing is done
if the image sets none).

=head2 Arguments

A feature can take an argument, given after the first C</> of the
name: C<--with locale/ja_JP> passes C<ja_JP> to the feature
F<locale> as C<DOZO_ARG>.  Everything after the first C</> is the
argument, so it may contain C</> itself (C<zone/Asia/Tokyo>), and
spaces when quoted, but not a comma, which separates features.
C<locale/> is the same as C<locale>.  The argument is given by
C<docker build --build-arg>, and is available as C<$DOZO_ARG> in the
feature.

Different arguments make different images, and each of them is
reused.  B<dozo> does not split the argument; to take several values,
pick a separator and split it with C<IFS> in the feature (see
F<features/locale> below):

    dozo -I homebrew/brew --with locale/ja_JP+en_US make test

=head2 Examples

F<features/locale>, which makes UTF-8 locales on Debian and Ubuntu
based images: C<--with locale> makes C<ja_JP.UTF-8>, and
C<--with locale/ja_JP+en_US> makes C<ja_JP.UTF-8> and
C<en_US.UTF-8>.  B<dozo> gives C<LANG> of the host to the container,
so making the locale is enough.  It does nothing when the image has
the locales already, or has neither C<locale-gen> nor C<apt-get>
(such as alpine), so it can be given always in F<~/.dozorc>:

    --with locale

It is included in the distribution, in F<share/features/locale>.
B<dozo> does not look there: copy it to the feature directory.  For
an installed distribution (with L<File::ShareDir>):

    mkdir -p ~/.config/dozo/features
    cp "$(perl -MFile::ShareDir=dist_dir -E 'say dist_dir "App-dozo"')"/features/locale \
       ~/.config/dozo/features/

The comments in the file tell how it works.

F<features/home/Dockerfile>, with other files in F<features/home/>:

    COPY --chown=$DOZO_USER . $DOZO_HOME/
    RUN exec >> $DOZO_HOME/.inputrc \
        && echo Control-n: history-search-forward \
        && echo Control-p: history-search-backward

=head2 Derived Images

Each feature makes one image on top of the previous one, tagged
C<dozo/>I<base>C<:>I<name>C<->I<cksum>.  The checksum is made from
the parent image, the content of the feature (for a directory, the
names and contents of all files in it) and its argument.  An image
which already exists is reused and nothing is built, so the second and
later runs only add one image check per stage (a few tens of
milliseconds).  When a feature or the base image (for example updated
by B<-A>) changes, the image is made again from that feature on, and
earlier images are reused.  Put heavy features first.

A base image which is not found locally is pulled automatically.
Build output goes to the standard error, and is not shown with
B<-q>.  If a build fails, the command is not run.  With B<-n>, the
C<docker build> and C<docker run> commands are shown but nothing is
built.

With B<-L>, a new container is made from the derived image, but an
existing container is not changed.  B<dozo> warns about it when its
image differs; use B<-K> to recreate it:

    dozo -I homebrew/brew --with locale -KL

Derived images are not removed automatically.  They have the labels
C<dozo.base> (the base image) and C<dozo.with> (the features applied
so far).  B<dozo -S> lists them with their state: C<current> (used
by B<--with> now), C<outdated> (the feature or the base image has
changed since), C<feature gone> or C<base gone>, and shows the
commands to remove those not current and not used by a container (see
L</Show the status>).  To list and remove all of them:

    docker image ls --filter label=dozo.base
    docker image rm $(docker image ls -q --filter label=dozo.base)

=head1 CONFIGURATION FILE

C<.dozorc> files are loaded from the following locations in order:

=over 4

=item 1. Home directory C<.dozorc>

=item 2. Git top directory C<.dozorc> (if different)

=item 3. Current directory C<.dozorc>

=item 4. Command line arguments

=back

For single-value options (like C<-I>, C<-N>), later values override
earlier ones. For repeatable options (like C<-E>, C<-V>, C<-P>, C<-O>),
all values are accumulated in order.

You can use any command line option in the configuration file:

    # Example .dozorc
    -I tecolicom/xlate:latest
    -E CUSTOM_VAR=value
    -V /data:/data

Lines starting with C<#> are treated as comments.  A C<#> in the middle
of a line does B<not> start a comment, and a trailing comment is not
supported.

Each line is split into arguments in the same way as the shell does, so
quotation marks have to be balanced.  A line which cannot be parsed is
an error, and B<Dôzo> stops after showing the file name, the line
number and the line itself.

Write nothing but options in the configuration file.  Its contents are
placed before the command line arguments, and option parsing stops at
the first argument which is not an option.  Everything after it,
including options given on the command line, is passed to the container
as the command to execute.  This is the rule which lets you write
C<dozo -I alpine ls -la> without C<-la> being taken as an option of
B<Dôzo>, but it also means that a stray word in F<.dozorc> disables
option parsing altogether.  With a trailing comment like this:

    -I alpine  # use alpine

C<dozo -n ls> does not show the docker command line but runs
C<# use alpine -n ls> in the container.

=head1 DOCKER-IN-DOCKER

To use Docker commands inside the container, mount the host's Docker
socket:

    # .dozorc for Docker-in-Docker
    -I docker
    -V /var/run/docker.sock

This allows you to run Docker commands from within the container using
the host's Docker daemon:

    $ dozo docker run --rm alpine uname -a

Or run it as a one-liner without C<.dozorc>:

    $ dozo -I docker -V /var/run/docker.sock docker run --rm alpine uname -a

=head1 DEFAULT IMAGE

The C<tecolicom/xlate> image is specifically designed for document
translation and text processing tasks, providing a comprehensive
environment with the following features:

=head2 Translation and AI Tools

=over 4

=item * B<DeepL CLI> - Command-line interface for DeepL translation API

=item * B<gpty> - GPT command-line tool for AI-powered text processing

=item * B<llm> - Unified LLM interface with plugins for multiple providers:
Gemini, Claude 3, Perplexity, and OpenRouter

=back

=head2 Text Processing Tools

=over 4

=item * B<greple> with xlate module - Pattern-based text extraction and
translation

=item * B<sdif> - Side-by-side diff viewer with word-level highlighting

=item * B<ansicolumn>, B<ansifold>, B<ansiexpand> - ANSI-aware text
formatting tools

=item * B<optex textconv> - Document format converter (PDF, Office, etc.)

=back

=head2 Greple Extensions

Multiple L<App::Greple> extension modules are pre-installed:

=over 4

=item * B<msdoc> - Microsoft Office document support

=item * B<xp> - Extended pattern syntax

=item * B<subst> - Text substitution with dictionary

=item * B<frame> - Frame-style output formatting

=back

=head2 Git Integration

The image includes a pre-configured git environment optimized for
document comparison and review. Since B<Dôzo> automatically mounts
the git top directory by default, git commands work seamlessly with
full repository context:

=over 4

=item * B<Side-by-side diff> - C<git diff>, C<git log>, and C<git show>
use B<sdif> for word-level side-by-side comparison

=item * B<Colorful blame> - C<git blame> uses B<greple> for enhanced
label coloring

=item * B<Office document diff> - Compare Word (.docx), Excel (.xlsx),
and PowerPoint (.pptx) files directly with git

=item * B<PDF diff> - View PDF metadata changes

=item * B<JSON diff> - Normalized JSON comparison using B<jq>

=back

=head2 Additional Utilities

=over 4

=item * B<MeCab> - Japanese morphological analyzer with IPA dictionary

=item * B<poppler-utils> - PDF processing tools (pdftotext, etc.)

=item * B<jq>, B<yq> - JSON and YAML processors

=back

=head2 Environment

=over 4

=item * Based on Ubuntu with Japanese locale (ja_JP.UTF-8)

=item * Perl and Python3 runtime environments

=item * Common API keys are automatically inherited from host
(DEEPL_AUTH_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)

=back

=head1 ENVIRONMENT

=head2 Configuration Variables

=over 4

=item C<DOZO_DEFAULT_IMAGE>

Specifies the default Docker image used when C<-D> (C<--default>) option
is given. If not set, C<tecolicom/xlate> is used, which resolves to its
C<latest> tag.

=back

=head2 Inherited Variables

The following environment variables are inherited by default:

    LANG TZ
    HTTP_PROXY HTTPS_PROXY http_proxy https_proxy
    TERM_PROGRAM TERM_BGCOLOR COLORTERM
    DEEPL_AUTH_KEY OPENAI_API_KEY ANTHROPIC_API_KEY LLM_PERPLEXITY_KEY

=head2 Container Variables

The following environment variables are set inside the container:

=over 4

=item C<DOZO_RUNNING_ON_DOCKER=1>

Indicates the command is running inside a container started by Dôzo.

=item C<XLATE_RUNNING_ON_DOCKER=1>

For compatibility with xlate. Used to prevent recursive Docker
invocation when xlate is run inside the container.

=back

=head1 SEE ALSO

L<xlate>, L<App::Greple::xlate>

L<getoptlong.sh|https://github.com/tecolicom/getoptlong>

=head1 AUTHOR

Kazumasa Utashiro

=head1 LICENSE

Copyright © 2025-2026 Kazumasa Utashiro.

This software is released under the MIT License.
L<https://opensource.org/licenses/MIT>

=cut
