From b2881880958c4d4f31c2148b06c59d11a6c839ea Mon Sep 17 00:00:00 2001 From: Svetlin Ralchev Date: Thu, 19 Nov 2026 12:31:17 +0400 Subject: [PATCH 1/4] feat: rewrite in bash, keep the zsh plugin as a thin installer The tool is now bin/devcontainer-sh, a bash 3.2 compatible executable that works from any shell and from CI. The zsh plugin only puts it on PATH and registers completions. Subcommands are now called commands. --- README.md | 8 +- bin/devcontainer-sh | 269 +++++++++++++++++++ completions/_devcontainer | 6 +- completions/_devcontainer-sh | 6 +- devcontainer-sh.plugin.zsh | 23 +- functions/_devcontainer_sh_dispatch | 30 --- functions/_devcontainer_sh_id_label | 11 - functions/_devcontainer_sh_pick_shell | 11 - functions/_devcontainer_sh_resolve_workspace | 25 -- subcommands/build.zsh | 31 --- subcommands/down.zsh | 35 --- subcommands/exec.zsh | 20 -- subcommands/help.zsh | 25 -- subcommands/shell.zsh | 36 --- subcommands/up.zsh | 27 -- subcommands/version.zsh | 11 - tests/build.bats | 17 +- tests/dispatch.bats | 32 ++- tests/down.bats | 31 ++- tests/exec.bats | 78 ++++++ tests/helpers.bash | 20 +- tests/id_label.bats | 24 -- tests/plugin.bats | 27 ++ tests/resolve_workspace.bats | 46 ---- tests/shell.bats | 18 +- tests/up.bats | 30 ++- 26 files changed, 491 insertions(+), 406 deletions(-) create mode 100755 bin/devcontainer-sh delete mode 100644 functions/_devcontainer_sh_dispatch delete mode 100644 functions/_devcontainer_sh_id_label delete mode 100644 functions/_devcontainer_sh_pick_shell delete mode 100644 functions/_devcontainer_sh_resolve_workspace delete mode 100644 subcommands/build.zsh delete mode 100644 subcommands/down.zsh delete mode 100644 subcommands/exec.zsh delete mode 100644 subcommands/help.zsh delete mode 100644 subcommands/shell.zsh delete mode 100644 subcommands/up.zsh delete mode 100644 subcommands/version.zsh create mode 100644 tests/exec.bats delete mode 100644 tests/id_label.bats create mode 100644 tests/plugin.bats delete mode 100644 tests/resolve_workspace.bats diff --git a/README.md b/README.md index d1a49ad..634a6a8 100644 --- a/README.md +++ b/README.md @@ -45,14 +45,14 @@ echo 'source ~/.zsh/devcontainer-sh/devcontainer-sh.plugin.zsh' >> ~/.zshrc - zsh 5.0+ - [`@devcontainers/cli`](https://github.com/devcontainers/cli) on `$PATH` (`npm i -g @devcontainers/cli`) -- Docker (for the `down` subcommand) +- Docker (for the `down` command) ## Usage ```text -Usage: devcontainer-sh [args...] +Usage: devcontainer-sh [args...] -Subcommands: +Commands: up Create and start the dev container for this workspace shell, sh Open an interactive shell inside the container exec Run a one-off command in the container @@ -102,7 +102,7 @@ devcontainer-sh down ### Workspace auto-detection -All subcommands walk up from `$PWD` looking for `.devcontainer/devcontainer.json` or `.devcontainer.json` and pass that directory as `--workspace-folder`. Pass `--workspace-folder` yourself to override. +All commands walk up from `$PWD` looking for `.devcontainer/devcontainer.json` or `.devcontainer.json` and pass that directory as `--workspace-folder`. Pass `--workspace-folder` yourself to override. ### Pass-through diff --git a/bin/devcontainer-sh b/bin/devcontainer-sh new file mode 100755 index 0000000..0ed3f6c --- /dev/null +++ b/bin/devcontainer-sh @@ -0,0 +1,269 @@ +#!/usr/bin/env bash +# +# devcontainer-sh — a thin wrapper around the devcontainer CLI. +# +# One dispatcher command, workspace auto-detection, and no --workspace-folder +# to type. Unknown flags pass straight through to the upstream CLI. +# +# Written for bash 3.2 (the macOS system bash): no associative arrays, no +# mapfile, no ${var,,}. + +DEVCONTAINER_SH_VERSION="0.1.0" # x-release-please-version + +die() { + printf 'devcontainer-sh: %s\n' "$*" >&2 + exit 1 +} + +# abs_path PATH +# +# Print PATH as an absolute path with symlinks resolved. A path that does not +# exist is made absolute without resolving it. +abs_path() { + local p="$1" + if [ -d "$p" ]; then + (cd -P -- "$p" && pwd -P) + else + case "$p" in + /*) printf '%s\n' "$p" ;; + *) printf '%s/%s\n' "$PWD" "$p" ;; + esac + fi +} + +# resolve_workspace [START_DIR] +# +# Print the workspace folder for the current context: the nearest ancestor of +# START_DIR (default $PWD) that contains a .devcontainer/devcontainer.json or +# .devcontainer.json. Falls back to START_DIR if no config is found, so commands +# still pass a valid --workspace-folder to the upstream CLI. +resolve_workspace() { + local dir start + dir="$(abs_path "${1:-$PWD}")" + start="$dir" + + while [ "$dir" != "/" ] && [ -n "$dir" ]; do + if [ -f "$dir/.devcontainer/devcontainer.json" ] || [ -f "$dir/.devcontainer.json" ]; then + printf '%s\n' "$dir" + return 0 + fi + dir="$(dirname -- "$dir")" + done + + printf '%s\n' "$start" +} + +# id_label WORKSPACE +# +# Print the id-label that `devcontainer up` infers when no --id-label is given. +# See @devcontainers/cli source: `devcontainer.local_folder=`. +id_label() { + [ -n "${1:-}" ] || die "id_label: workspace folder required" + printf 'devcontainer.local_folder=%s\n' "$(abs_path "$1")" +} + +# has_workspace_flag ARGS... +# +# Succeed if ARGS carry --workspace-folder. Arguments after a bare -- belong to +# the command being run and are not looked at. +has_workspace_flag() { + local arg + for arg in "$@"; do + case "$arg" in + --) return 1 ;; + --workspace-folder | --workspace-folder=*) return 0 ;; + esac + done + return 1 +} + +cmd_up() { + local -a args=() extras=() + local arg + for arg in "$@"; do + case "$arg" in + -r) extras+=(--remove-existing-container) ;; + -n) extras+=(--build-no-cache) ;; + -R) extras+=(--remove-existing-container --build-no-cache) ;; + -s) extras+=(--skip-post-create) ;; + *) args+=("$arg") ;; + esac + done + + if ! has_workspace_flag "${args[@]}"; then + args=(--workspace-folder "$(resolve_workspace)" "${args[@]}") + fi + + exec devcontainer up "${extras[@]}" "${args[@]}" +} + +cmd_build() { + local -a args=() extras=() + local arg capture_platform=0 + for arg in "$@"; do + if [ "$capture_platform" = 1 ]; then + extras+=(--platform "$arg") + capture_platform=0 + continue + fi + case "$arg" in + -n) extras+=(--no-cache) ;; + -p) capture_platform=1 ;; + *) args+=("$arg") ;; + esac + done + [ "$capture_platform" = 0 ] || die "build: -p requires a platform, e.g. -p linux/amd64" + + if ! has_workspace_flag "${args[@]}"; then + args=(--workspace-folder "$(resolve_workspace)" "${args[@]}") + fi + + exec devcontainer build "${extras[@]}" "${args[@]}" +} + +cmd_exec() { + local -a args=("$@") + + if ! has_workspace_flag "${args[@]}"; then + args=(--workspace-folder "$(resolve_workspace)" "${args[@]}") + fi + + exec devcontainer exec "${args[@]}" +} + +cmd_shell() { + local -a passthru=() + local arg requested_shell="" + + for arg in "$@"; do + case "$arg" in + --workspace-folder | --workspace-folder=*) passthru+=("$arg") ;; + -*) passthru+=("$arg") ;; + *) + if [ -z "$requested_shell" ]; then + requested_shell="$arg" + else + passthru+=("$arg") + fi + ;; + esac + done + + if ! has_workspace_flag "${passthru[@]}"; then + passthru=(--workspace-folder "$(resolve_workspace)" "${passthru[@]}") + fi + + if [ -n "$requested_shell" ]; then + exec devcontainer exec "${passthru[@]}" "$requested_shell" -l + fi + + # The container's own `command -v` picks the shell, which saves an extra exec + # round-trip to probe it from here. + # shellcheck disable=SC2016 + local picker='${SHELL:-$(command -v zsh || command -v bash || command -v sh)}' + exec devcontainer exec "${passthru[@]}" sh -c "exec ${picker} -l" +} + +cmd_down() { + local ws="" arg + while [ $# -gt 0 ]; do + arg="$1" + case "$arg" in + --workspace-folder) + [ $# -ge 2 ] || die "down: --workspace-folder requires a path" + ws="$2" + shift 2 + ;; + --workspace-folder=*) + ws="${arg#--workspace-folder=}" + shift + ;; + -h | --help) + printf 'Usage: devcontainer-sh down [--workspace-folder PATH]\n' + printf 'Stops and removes the dev container associated with the workspace.\n' + return 0 + ;; + *) shift ;; + esac + done + + [ -n "$ws" ] || ws="$(resolve_workspace)" + + local label out id + label="$(id_label "$ws")" + out="$(docker ps -aq --filter "label=${label}")" || die "down: docker ps failed" + + local -a ids=() + while IFS= read -r id; do + [ -z "$id" ] || ids+=("$id") + done < [args...] + +Commands: + up [opts] Create and start the dev container for this workspace + Shortcuts: -r remove-existing, -n build-no-cache, + -R both, -s skip-post-create + shell, sh [shell] Open an interactive shell inside the container + (auto-picks zsh > bash > sh, or pass a shell name) + exec [args] Run a one-off command in the container + build [opts] Build the container image (-n no-cache, -p PLATFORM) + down Stop and remove the container for this workspace + help Show this help + version Show wrapper and devcontainer CLI versions + +All commands auto-detect --workspace-folder by walking up from $PWD to find +the nearest .devcontainer/devcontainer.json. Pass --workspace-folder explicitly +to override. Unknown flags are passed straight through to the upstream CLI. +EOF +} + +cmd_version() { + printf 'devcontainer-sh %s\n' "$DEVCONTAINER_SH_VERSION" + if command -v devcontainer >/dev/null 2>&1; then + printf 'devcontainer ' + devcontainer --version + else + printf 'devcontainer CLI not found in PATH\n' >&2 + return 1 + fi +} + +main() { + if [ $# -eq 0 ]; then + cmd_help + return 1 + fi + + local name="$1" + shift + + case "$name" in + up) cmd_up "$@" ;; + shell | sh) cmd_shell "$@" ;; + exec) cmd_exec "$@" ;; + build) cmd_build "$@" ;; + down) cmd_down "$@" ;; + help | -h | --help) cmd_help ;; + version | -v | --version) cmd_version ;; + *) + printf 'devcontainer-sh: unknown command: %s\n' "$name" >&2 + printf "Run 'devcontainer-sh help' for usage.\n" >&2 + return 1 + ;; + esac +} + +main "$@" diff --git a/completions/_devcontainer b/completions/_devcontainer index 95b29d6..bb3d7fc 100644 --- a/completions/_devcontainer +++ b/completions/_devcontainer @@ -5,11 +5,11 @@ _devcontainer() { typeset -A opt_args _arguments -C \ - '1: :->subcmd' \ + '1: :->cmd' \ '*::arg:->args' case "$state" in - subcmd) + cmd) local -a subs=( 'up:Create and run dev container' 'set-up:Set up an existing container as a dev container' @@ -22,7 +22,7 @@ _devcontainer() { 'templates:Templates commands' 'exec:Execute a command on a running dev container' ) - _describe -t commands 'devcontainer subcommand' subs + _describe -t commands 'devcontainer command' subs ;; args) case "$line[1]" in diff --git a/completions/_devcontainer-sh b/completions/_devcontainer-sh index 1eb0786..c825c3c 100644 --- a/completions/_devcontainer-sh +++ b/completions/_devcontainer-sh @@ -5,11 +5,11 @@ _devcontainer_sh() { typeset -A opt_args _arguments -C \ - '1: :->subcmd' \ + '1: :->cmd' \ '*::arg:->args' case "$state" in - subcmd) + cmd) local -a subs=( 'up:Create and start the dev container' 'shell:Open an interactive shell in the container' @@ -20,7 +20,7 @@ _devcontainer_sh() { 'help:Show usage' 'version:Show plugin and devcontainer CLI versions' ) - _describe -t subcommands 'subcommand' subs + _describe -t commands 'command' subs ;; args) case "$line[1]" in diff --git a/devcontainer-sh.plugin.zsh b/devcontainer-sh.plugin.zsh index e984684..166bf31 100644 --- a/devcontainer-sh.plugin.zsh +++ b/devcontainer-sh.plugin.zsh @@ -1,7 +1,8 @@ -# devcontainer-sh — zsh wrapper around the devcontainer CLI. -# Works with oh-my-zsh, zinit, antidote, or plain `source`. - -DEVCONTAINER_SH_VERSION="0.1.0" +# devcontainer-sh — zsh plugin entry. +# +# The tool is the bash executable in bin/; this file only puts it on PATH and +# registers the zsh completions, so oh-my-zsh, zinit, antidote or a plain +# `source` keep working. 0="${${ZERO:-${0:#$ZSH_ARGZERO}}:-${(%):-%N}}" 0="${${(M)0:#/*}:-$PWD/$0}" @@ -11,16 +12,6 @@ DEVCONTAINER_SH_VERSION="0.1.0" local plugin_dir="${1:A:h}" - fpath=("$plugin_dir/functions" "$plugin_dir/completions" $fpath) - - autoload -Uz _devcontainer_sh_dispatch _devcontainer_sh_resolve_workspace _devcontainer_sh_pick_shell _devcontainer_sh_id_label - - local f - for f in "$plugin_dir"/subcommands/*.zsh(N); do - source "$f" - done + path=("$plugin_dir/bin" $path) + fpath=("$plugin_dir/completions" $fpath) } "$0" - -devcontainer-sh() { - _devcontainer_sh_dispatch "$@" -} diff --git a/functions/_devcontainer_sh_dispatch b/functions/_devcontainer_sh_dispatch deleted file mode 100644 index 6f937c5..0000000 --- a/functions/_devcontainer_sh_dispatch +++ /dev/null @@ -1,30 +0,0 @@ -#autoload -# -# _devcontainer_sh_dispatch SUBCOMMAND [ARGS...] -# -# Route to the matching _devcontainer_sh:: function. The short form `sh` maps to -# `shell`. Unknown or missing subcommands print help and exit 1. - -emulate -L zsh - -if (( $# == 0 )); then - _devcontainer_sh::help - return 1 -fi - -local sub="$1"; shift - -case "$sub" in - up) _devcontainer_sh::up "$@" ;; - shell|sh) _devcontainer_sh::shell "$@" ;; - exec) _devcontainer_sh::exec "$@" ;; - build) _devcontainer_sh::build "$@" ;; - down) _devcontainer_sh::down "$@" ;; - help|-h|--help) _devcontainer_sh::help "$@" ;; - version|-v|--version) _devcontainer_sh::version "$@" ;; - *) - print -ru2 -- "devcontainer-sh: unknown subcommand: $sub" - print -ru2 -- "Run 'devcontainer-sh help' for usage." - return 1 - ;; -esac diff --git a/functions/_devcontainer_sh_id_label b/functions/_devcontainer_sh_id_label deleted file mode 100644 index 82d8772..0000000 --- a/functions/_devcontainer_sh_id_label +++ /dev/null @@ -1,11 +0,0 @@ -#autoload -# -# _devcontainer_sh_id_label WORKSPACE -# -# Print the id-label that `devcontainer up` infers when no --id-label is given. -# See @devcontainers/cli source: `devcontainer.local_folder=`. - -emulate -L zsh - -local ws="${1:?_devcontainer_sh_id_label: workspace folder required}" -print -r -- "devcontainer.local_folder=${ws:A}" diff --git a/functions/_devcontainer_sh_pick_shell b/functions/_devcontainer_sh_pick_shell deleted file mode 100644 index 4fddb12..0000000 --- a/functions/_devcontainer_sh_pick_shell +++ /dev/null @@ -1,11 +0,0 @@ -#autoload -# -# _devcontainer_sh_pick_shell -# -# Print a sh expression that picks the best available shell inside the -# container at runtime. We can't probe the container without an extra exec -# round-trip, so we let the container's own `command -v` resolve it. - -emulate -L zsh - -print -r -- '${SHELL:-$(command -v zsh || command -v bash || command -v sh)}' diff --git a/functions/_devcontainer_sh_resolve_workspace b/functions/_devcontainer_sh_resolve_workspace deleted file mode 100644 index c0ef3f7..0000000 --- a/functions/_devcontainer_sh_resolve_workspace +++ /dev/null @@ -1,25 +0,0 @@ -#autoload -# -# _devcontainer_sh_resolve_workspace [START_DIR] -# -# Print the workspace folder for the current context: the nearest ancestor of -# START_DIR (default $PWD) that contains a .devcontainer/devcontainer.json or -# .devcontainer.json. Falls back to START_DIR if no config is found, so commands -# still pass a valid --workspace-folder to the upstream CLI. - -emulate -L zsh - -local dir="${1:-$PWD}" -dir="${dir:A}" -local start="$dir" - -while [[ "$dir" != "/" && -n "$dir" ]]; do - if [[ -f "$dir/.devcontainer/devcontainer.json" || -f "$dir/.devcontainer.json" ]]; then - print -r -- "$dir" - return 0 - fi - dir="${dir:h}" -done - -print -r -- "$start" -return 0 diff --git a/subcommands/build.zsh b/subcommands/build.zsh deleted file mode 100644 index 3859384..0000000 --- a/subcommands/build.zsh +++ /dev/null @@ -1,31 +0,0 @@ -_devcontainer_sh::build() { - emulate -L zsh - - local -a args extras - local arg - local has_ws=0 - local capture_platform=0 - for arg in "$@"; do - if (( capture_platform )); then - extras+=(--platform "$arg") - capture_platform=0 - continue - fi - case "$arg" in - -n) extras+=(--no-cache) ;; - -p) capture_platform=1 ;; - --workspace-folder|--workspace-folder=*) - has_ws=1 - args+=("$arg") - ;; - *) args+=("$arg") ;; - esac - done - - if (( ! has_ws )); then - local ws; ws="$(_devcontainer_sh_resolve_workspace)" - args=(--workspace-folder "$ws" $args) - fi - - command devcontainer build $extras $args -} diff --git a/subcommands/down.zsh b/subcommands/down.zsh deleted file mode 100644 index a0e56be..0000000 --- a/subcommands/down.zsh +++ /dev/null @@ -1,35 +0,0 @@ -_devcontainer_sh::down() { - emulate -L zsh - - local ws="" - local arg - local -a rest - while (( $# )); do - arg="$1" - case "$arg" in - --workspace-folder) ws="$2"; shift 2 ;; - --workspace-folder=*) ws="${arg#--workspace-folder=}"; shift ;; - -h|--help) - print -r -- "Usage: devcontainer-sh down [--workspace-folder PATH]" - print -r -- "Stops and removes the dev container associated with the workspace." - return 0 - ;; - *) rest+=("$arg"); shift ;; - esac - done - - [[ -z "$ws" ]] && ws="$(_devcontainer_sh_resolve_workspace)" - - local label; label="$(_devcontainer_sh_id_label "$ws")" - - local -a ids - ids=("${(@f)$(command docker ps -aq --filter "label=${label}")}") - ids=(${ids:#}) - - if (( ${#ids} == 0 )); then - print -ru2 -- "devcontainer-sh down: no container found for label ${label}" - return 1 - fi - - command docker rm -f $ids -} diff --git a/subcommands/exec.zsh b/subcommands/exec.zsh deleted file mode 100644 index f219795..0000000 --- a/subcommands/exec.zsh +++ /dev/null @@ -1,20 +0,0 @@ -_devcontainer_sh::exec() { - emulate -L zsh - - local -a args - local arg - local has_ws=0 - for arg in "$@"; do - case "$arg" in - --workspace-folder|--workspace-folder=*) has_ws=1 ;; - esac - args+=("$arg") - done - - if (( ! has_ws )); then - local ws; ws="$(_devcontainer_sh_resolve_workspace)" - args=(--workspace-folder "$ws" $args) - fi - - command devcontainer exec $args -} diff --git a/subcommands/help.zsh b/subcommands/help.zsh deleted file mode 100644 index 6d717aa..0000000 --- a/subcommands/help.zsh +++ /dev/null @@ -1,25 +0,0 @@ -_devcontainer_sh::help() { - emulate -L zsh - cat <<'EOF' -devcontainer-sh — zsh wrapper around the devcontainer CLI - -Usage: - devcontainer-sh [args...] - -Subcommands: - up [opts] Create and start the dev container for this workspace - Shortcuts: -r remove-existing, -n build-no-cache, - -R both, -s skip-post-create - shell, sh [shell] Open an interactive shell inside the container - (auto-picks zsh > bash > sh, or pass a shell name) - exec [args] Run a one-off command in the container - build [opts] Build the container image (-n no-cache, -p PLATFORM) - down Stop and remove the container for this workspace - help Show this help - version Show plugin and devcontainer CLI versions - -All subcommands auto-detect --workspace-folder by walking up from $PWD to find -the nearest .devcontainer/devcontainer.json. Pass --workspace-folder explicitly -to override. Unknown flags are passed straight through to the upstream CLI. -EOF -} diff --git a/subcommands/shell.zsh b/subcommands/shell.zsh deleted file mode 100644 index 09aff5a..0000000 --- a/subcommands/shell.zsh +++ /dev/null @@ -1,36 +0,0 @@ -_devcontainer_sh::shell() { - emulate -L zsh - - local -a passthru - local arg requested_shell="" - local has_ws=0 - - for arg in "$@"; do - case "$arg" in - --workspace-folder|--workspace-folder=*) - has_ws=1 - passthru+=("$arg") - ;; - -*) passthru+=("$arg") ;; - *) - if [[ -z "$requested_shell" ]]; then - requested_shell="$arg" - else - passthru+=("$arg") - fi - ;; - esac - done - - if (( ! has_ws )); then - local ws; ws="$(_devcontainer_sh_resolve_workspace)" - passthru=(--workspace-folder "$ws" $passthru) - fi - - if [[ -n "$requested_shell" ]]; then - command devcontainer exec $passthru "$requested_shell" -l - else - local picker; picker="$(_devcontainer_sh_pick_shell)" - command devcontainer exec $passthru sh -c "exec ${picker} -l" - fi -} diff --git a/subcommands/up.zsh b/subcommands/up.zsh deleted file mode 100644 index c12289a..0000000 --- a/subcommands/up.zsh +++ /dev/null @@ -1,27 +0,0 @@ -_devcontainer_sh::up() { - emulate -L zsh - - local -a args extras - local arg - local has_ws=0 - for arg in "$@"; do - case "$arg" in - -r) extras+=(--remove-existing-container) ;; - -n) extras+=(--build-no-cache) ;; - -R) extras+=(--remove-existing-container --build-no-cache) ;; - -s) extras+=(--skip-post-create) ;; - --workspace-folder|--workspace-folder=*) - has_ws=1 - args+=("$arg") - ;; - *) args+=("$arg") ;; - esac - done - - if (( ! has_ws )); then - local ws; ws="$(_devcontainer_sh_resolve_workspace)" - args=(--workspace-folder "$ws" $args) - fi - - command devcontainer up $extras $args -} diff --git a/subcommands/version.zsh b/subcommands/version.zsh deleted file mode 100644 index a719487..0000000 --- a/subcommands/version.zsh +++ /dev/null @@ -1,11 +0,0 @@ -_devcontainer_sh::version() { - emulate -L zsh - print -r -- "devcontainer-sh ${DEVCONTAINER_SH_VERSION:-0.1.0}" - if (( $+commands[devcontainer] )); then - print -rn -- "devcontainer " - command devcontainer --version - else - print -ru2 -- "devcontainer CLI not found in PATH" - return 1 - fi -} diff --git a/tests/build.bats b/tests/build.bats index 4fa96c9..07a9103 100644 --- a/tests/build.bats +++ b/tests/build.bats @@ -4,9 +4,8 @@ load helpers setup() { setup_stubs - WS_ROOT="$(mktemp -d)" - mkdir -p "$WS_ROOT/.devcontainer" - echo '{}' > "$WS_ROOT/.devcontainer/devcontainer.json" + make_workspace + cd "$WS_ROOT" } teardown() { @@ -15,19 +14,25 @@ teardown() { } @test "build -n expands to --no-cache" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh build -n" + run devcontainer-sh build -n [ "$status" -eq 0 ] [[ "$output" == *"--no-cache"* ]] } @test "build -p captures the next arg as --platform value" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh build -p linux/amd64" + run devcontainer-sh build -p linux/amd64 [ "$status" -eq 0 ] [[ "$output" == *"--platform linux/amd64"* ]] } +@test "build -p without a value fails" { + run devcontainer-sh build -p + [ "$status" -eq 1 ] + [[ "$output" == *"-p requires a platform"* ]] +} + @test "build injects workspace folder" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh build" + run devcontainer-sh build [ "$status" -eq 0 ] [[ "$output" == *"--workspace-folder $(realpath "$WS_ROOT")"* ]] } diff --git a/tests/dispatch.bats b/tests/dispatch.bats index 71c71bc..5086781 100644 --- a/tests/dispatch.bats +++ b/tests/dispatch.bats @@ -5,27 +5,39 @@ load helpers setup() { setup_stubs; } teardown() { teardown_stubs; } -@test "no subcommand prints help and exits 1" { - devcontainer_sh_run "devcontainer-sh" +@test "no command prints help and exits 1" { + run devcontainer-sh [ "$status" -eq 1 ] [[ "$output" == *"Usage:"* ]] } -@test "unknown subcommand exits 1 with hint" { - devcontainer_sh_run "devcontainer-sh bogus" +@test "unknown command exits 1 with hint" { + run devcontainer-sh bogus [ "$status" -eq 1 ] - [[ "$output" == *"unknown subcommand: bogus"* ]] + [[ "$output" == *"unknown command: bogus"* ]] } -@test "help subcommand exits 0" { - devcontainer_sh_run "devcontainer-sh help" +@test "help command exits 0" { + run devcontainer-sh help [ "$status" -eq 0 ] - [[ "$output" == *"Subcommands:"* ]] + [[ "$output" == *"Commands:"* ]] } -@test "version subcommand prints plugin and upstream versions" { - devcontainer_sh_run "devcontainer-sh version" +@test "version command prints wrapper and upstream versions" { + run devcontainer-sh version [ "$status" -eq 0 ] [[ "$output" == *"devcontainer-sh"* ]] [[ "$output" == *"devcontainer --version"* ]] } + +@test "version fails when the devcontainer CLI is missing" { + rm "$STUB_DIR/devcontainer" + PATH="$PLUGIN_ROOT/bin:$STUB_DIR:/usr/bin:/bin" run devcontainer-sh version + [ "$status" -eq 1 ] + [[ "$output" == *"CLI not found"* ]] +} + +@test "runs without a login or interactive shell" { + run env -i PATH="$PATH" HOME="$HOME" bash -c 'devcontainer-sh help' + [ "$status" -eq 0 ] +} diff --git a/tests/down.bats b/tests/down.bats index 1acab9c..9166bab 100644 --- a/tests/down.bats +++ b/tests/down.bats @@ -4,9 +4,8 @@ load helpers setup() { setup_stubs - WS_ROOT="$(mktemp -d)" - mkdir -p "$WS_ROOT/.devcontainer" - echo '{}' > "$WS_ROOT/.devcontainer/devcontainer.json" + make_workspace + cd "$WS_ROOT" } teardown() { @@ -15,15 +14,35 @@ teardown() { } @test "down removes containers matching the workspace label" { - export DEVCONTAINER_SH_TEST_DOCKER_PS_OUT="abc123def456" - devcontainer_sh_run "cd '$WS_ROOT'; export DEVCONTAINER_SH_TEST_DOCKER_PS_OUT=abc123def456; devcontainer-sh down" + DEVCONTAINER_SH_TEST_DOCKER_PS_OUT="abc123def456" run devcontainer-sh down [ "$status" -eq 0 ] [[ "$output" == *"docker rm -f abc123def456"* ]] } +@test "down removes every matching container" { + DEVCONTAINER_SH_TEST_DOCKER_PS_OUT=$'abc123\ndef456' run devcontainer-sh down + [ "$status" -eq 0 ] + [[ "$output" == *"docker rm -f abc123 def456"* ]] +} + @test "down exits non-zero when no container matches" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh down" + run devcontainer-sh down [ "$status" -eq 1 ] [[ "$output" == *"no container found"* ]] +} + +@test "down looks up the devcontainer.local_folder label with an absolute path" { + run devcontainer-sh down [[ "$output" == *"devcontainer.local_folder=$(realpath "$WS_ROOT")"* ]] } + +@test "down uses --workspace-folder for the label" { + run devcontainer-sh down --workspace-folder "$WS_ROOT/.devcontainer/.." + [[ "$output" == *"devcontainer.local_folder=$(realpath "$WS_ROOT")"* ]] +} + +@test "down --help prints usage and exits 0" { + run devcontainer-sh down --help + [ "$status" -eq 0 ] + [[ "$output" == *"Usage: devcontainer-sh down"* ]] +} diff --git a/tests/exec.bats b/tests/exec.bats new file mode 100644 index 0000000..5f3e317 --- /dev/null +++ b/tests/exec.bats @@ -0,0 +1,78 @@ +#!/usr/bin/env bats + +load helpers + +setup() { + setup_stubs + make_workspace + mkdir -p "$WS_ROOT/src/nested" +} + +teardown() { + teardown_stubs + rm -rf "$WS_ROOT" +} + +@test "exec forwards the command after --" { + cd "$WS_ROOT" + run devcontainer-sh exec -- bash -lc 'make test' + [ "$status" -eq 0 ] + [[ "$output" == "devcontainer exec --workspace-folder $(realpath "$WS_ROOT") -- bash -lc make test" ]] +} + +@test "exec injects the workspace folder" { + cd "$WS_ROOT" + run devcontainer-sh exec -- true + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder $(realpath "$WS_ROOT")"* ]] +} + +@test "exec respects user-provided --workspace-folder" { + cd "$WS_ROOT" + run devcontainer-sh exec --workspace-folder /elsewhere -- true + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder /elsewhere"* ]] + [[ "$output" != *"$(realpath "$WS_ROOT")"* ]] +} + +@test "exec does not mistake the command's own --workspace-folder for ours" { + cd "$WS_ROOT" + run devcontainer-sh exec -- some-tool --workspace-folder /other + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder $(realpath "$WS_ROOT") -- some-tool --workspace-folder /other"* ]] +} + +@test "exec passes the command's exit status through" { + cd "$WS_ROOT" + printf '#!/bin/sh\nexit 7\n' > "$STUB_DIR/devcontainer" + run devcontainer-sh exec -- false + [ "$status" -eq 7 ] +} + +@test "exec walks up several levels to find the workspace" { + cd "$WS_ROOT/src/nested" + run devcontainer-sh exec -- true + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder $(realpath "$WS_ROOT") "* ]] +} + +@test "exec falls back to PWD when no devcontainer config is found" { + local elsewhere + elsewhere="$(mktemp -d)" + cd "$elsewhere" + run devcontainer-sh exec -- true + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder $(realpath "$elsewhere") "* ]] + rm -rf "$elsewhere" +} + +@test "exec recognises a top-level .devcontainer.json file" { + local alt + alt="$(mktemp -d)" + echo '{}' > "$alt/.devcontainer.json" + cd "$alt" + run devcontainer-sh exec -- true + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder $(realpath "$alt") "* ]] + rm -rf "$alt" +} diff --git a/tests/helpers.bash b/tests/helpers.bash index 882af20..cc60e61 100644 --- a/tests/helpers.bash +++ b/tests/helpers.bash @@ -1,8 +1,8 @@ # Shared bats helpers. # -# Each test runs zsh in a clean environment with stubbed `devcontainer` and -# `docker` binaries on PATH. The stubs echo whatever args they receive so we -# can assert what the plugin dispatches. +# Each test runs the real bin/devcontainer-sh with stubbed `devcontainer` and +# `docker` binaries first on PATH. The stubs echo whatever args they receive so +# we can assert what the wrapper dispatches. PLUGIN_ROOT="${BATS_TEST_DIRNAME}/.." @@ -20,17 +20,17 @@ case "$1" in esac STUB chmod +x "$STUB_DIR/devcontainer" "$STUB_DIR/docker" - export PATH="$STUB_DIR:$PATH" + export PATH="$PLUGIN_ROOT/bin:$STUB_DIR:$PATH" } teardown_stubs() { [ -n "${STUB_DIR-}" ] && rm -rf "$STUB_DIR" + return 0 } -# Run a zsh snippet with the plugin sourced. Captures stdout via bats `run`. -devcontainer_sh_run() { - run zsh -f -c " - source '${PLUGIN_ROOT}/devcontainer-sh.plugin.zsh' - $1 - " +# A temporary workspace with a .devcontainer/devcontainer.json, in WS_ROOT. +make_workspace() { + WS_ROOT="$(mktemp -d)" + mkdir -p "$WS_ROOT/.devcontainer" + echo '{}' > "$WS_ROOT/.devcontainer/devcontainer.json" } diff --git a/tests/id_label.bats b/tests/id_label.bats deleted file mode 100644 index 9676e98..0000000 --- a/tests/id_label.bats +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env bats - -load helpers - -setup() { setup_stubs; } -teardown() { teardown_stubs; } - -@test "id-label uses devcontainer.local_folder with absolute path" { - local ws - ws="$(mktemp -d)" - devcontainer_sh_run "_devcontainer_sh_id_label '$ws'" - [ "$status" -eq 0 ] - [ "$output" = "devcontainer.local_folder=$(realpath "$ws")" ] - rm -rf "$ws" -} - -@test "id-label resolves a relative path to absolute" { - local ws - ws="$(mktemp -d)" - devcontainer_sh_run "cd '$ws'; _devcontainer_sh_id_label ." - [ "$status" -eq 0 ] - [ "$output" = "devcontainer.local_folder=$(realpath "$ws")" ] - rm -rf "$ws" -} diff --git a/tests/plugin.bats b/tests/plugin.bats new file mode 100644 index 0000000..dcea758 --- /dev/null +++ b/tests/plugin.bats @@ -0,0 +1,27 @@ +#!/usr/bin/env bats + +load helpers + +setup() { + command -v zsh >/dev/null || skip "zsh is not installed" + setup_stubs +} +teardown() { teardown_stubs; } + +@test "sourcing the zsh plugin puts devcontainer-sh on PATH" { + run env PATH="$STUB_DIR:/usr/bin:/bin:$(dirname "$(command -v zsh)")" zsh -f -c " + source '$PLUGIN_ROOT/devcontainer-sh.plugin.zsh' + command -v devcontainer-sh + " + [ "$status" -eq 0 ] + [[ "$output" == *"/bin/devcontainer-sh" ]] +} + +@test "sourcing the zsh plugin registers the completions" { + run zsh -f -c " + source '$PLUGIN_ROOT/devcontainer-sh.plugin.zsh' + print -rl -- \$fpath + " + [ "$status" -eq 0 ] + [[ "$output" == *"/completions"* ]] +} diff --git a/tests/resolve_workspace.bats b/tests/resolve_workspace.bats deleted file mode 100644 index 8c72dd4..0000000 --- a/tests/resolve_workspace.bats +++ /dev/null @@ -1,46 +0,0 @@ -#!/usr/bin/env bats - -load helpers - -setup() { - setup_stubs - WS_ROOT="$(mktemp -d)" - mkdir -p "$WS_ROOT/.devcontainer" "$WS_ROOT/src/nested" - echo '{}' > "$WS_ROOT/.devcontainer/devcontainer.json" -} - -teardown() { - teardown_stubs - rm -rf "$WS_ROOT" -} - -@test "resolves workspace from inside .devcontainer parent" { - devcontainer_sh_run "cd '$WS_ROOT'; _devcontainer_sh_resolve_workspace" - [ "$status" -eq 0 ] - [ "$(realpath "$output")" = "$(realpath "$WS_ROOT")" ] -} - -@test "resolves workspace by walking up several levels" { - devcontainer_sh_run "cd '$WS_ROOT/src/nested'; _devcontainer_sh_resolve_workspace" - [ "$status" -eq 0 ] - [ "$(realpath "$output")" = "$(realpath "$WS_ROOT")" ] -} - -@test "falls back to PWD when no .devcontainer is found" { - local elsewhere - elsewhere="$(mktemp -d)" - devcontainer_sh_run "cd '$elsewhere'; _devcontainer_sh_resolve_workspace" - [ "$status" -eq 0 ] - [ "$(realpath "$output")" = "$(realpath "$elsewhere")" ] - rm -rf "$elsewhere" -} - -@test "recognises a top-level .devcontainer.json file" { - local alt - alt="$(mktemp -d)" - echo '{}' > "$alt/.devcontainer.json" - devcontainer_sh_run "cd '$alt'; _devcontainer_sh_resolve_workspace" - [ "$status" -eq 0 ] - [ "$(realpath "$output")" = "$(realpath "$alt")" ] - rm -rf "$alt" -} diff --git a/tests/shell.bats b/tests/shell.bats index 04db1d4..250a4b5 100644 --- a/tests/shell.bats +++ b/tests/shell.bats @@ -4,9 +4,8 @@ load helpers setup() { setup_stubs - WS_ROOT="$(mktemp -d)" - mkdir -p "$WS_ROOT/.devcontainer" - echo '{}' > "$WS_ROOT/.devcontainer/devcontainer.json" + make_workspace + cd "$WS_ROOT" } teardown() { @@ -15,7 +14,7 @@ teardown() { } @test "shell with no arg invokes sh -c with shell-picker expression" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh shell" + run devcontainer-sh shell [ "$status" -eq 0 ] [[ "$output" == *"sh -c"* ]] [[ "$output" == *"command -v zsh"* ]] @@ -23,13 +22,18 @@ teardown() { } @test "shell bash invokes the named shell as login shell" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh shell bash" + run devcontainer-sh shell bash [ "$status" -eq 0 ] [[ "$output" == *"bash -l"* ]] } -@test "shell short form `sh` works" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh sh fish" +@test "shell short form sh works" { + run devcontainer-sh sh fish [ "$status" -eq 0 ] [[ "$output" == *"fish -l"* ]] } + +@test "shell injects the workspace folder" { + run devcontainer-sh shell bash + [[ "$output" == *"--workspace-folder $(realpath "$WS_ROOT")"* ]] +} diff --git a/tests/up.bats b/tests/up.bats index 6622420..8586685 100644 --- a/tests/up.bats +++ b/tests/up.bats @@ -4,9 +4,8 @@ load helpers setup() { setup_stubs - WS_ROOT="$(mktemp -d)" - mkdir -p "$WS_ROOT/.devcontainer" - echo '{}' > "$WS_ROOT/.devcontainer/devcontainer.json" + make_workspace + cd "$WS_ROOT" } teardown() { @@ -15,40 +14,53 @@ teardown() { } @test "up injects --workspace-folder when missing" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh up" + run devcontainer-sh up [ "$status" -eq 0 ] [[ "$output" == *"--workspace-folder $(realpath "$WS_ROOT")"* ]] } @test "up -R expands to --remove-existing-container --build-no-cache" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh up -R" + run devcontainer-sh up -R [ "$status" -eq 0 ] [[ "$output" == *"--remove-existing-container"* ]] [[ "$output" == *"--build-no-cache"* ]] } @test "up -r expands only to --remove-existing-container" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh up -r" + run devcontainer-sh up -r [ "$status" -eq 0 ] [[ "$output" == *"--remove-existing-container"* ]] [[ "$output" != *"--build-no-cache"* ]] } +@test "up -n expands to --build-no-cache" { + run devcontainer-sh up -n + [ "$status" -eq 0 ] + [[ "$output" == *"--build-no-cache"* ]] +} + @test "up -s expands to --skip-post-create" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh up -s" + run devcontainer-sh up -s [ "$status" -eq 0 ] [[ "$output" == *"--skip-post-create"* ]] } @test "up respects user-provided --workspace-folder" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh up --workspace-folder /elsewhere" + run devcontainer-sh up --workspace-folder /elsewhere [ "$status" -eq 0 ] [[ "$output" == *"--workspace-folder /elsewhere"* ]] [[ "$output" != *"$(realpath "$WS_ROOT")"* ]] } +@test "up respects --workspace-folder=PATH" { + run devcontainer-sh up --workspace-folder=/elsewhere + [ "$status" -eq 0 ] + [[ "$output" == *"--workspace-folder=/elsewhere"* ]] + [[ "$output" != *"$(realpath "$WS_ROOT")"* ]] +} + @test "up passes through unknown flags" { - devcontainer_sh_run "cd '$WS_ROOT'; devcontainer-sh up --log-level=debug" + run devcontainer-sh up --log-level=debug [ "$status" -eq 0 ] [[ "$output" == *"--log-level=debug"* ]] } From 1857a19f827383daada0dcff4aa5d8712435069b Mon Sep 17 00:00:00 2001 From: Svetlin Ralchev Date: Thu, 19 Nov 2026 12:36:44 +0400 Subject: [PATCH 2/4] feat: add a GitHub Action and a Nix package, move the script to the root - action.yml puts devcontainer-sh on PATH and installs the devcontainer CLI - flake package with the zsh completions - CI: shellcheck, actionlint, nix build, tests on Linux and macOS (also with the system bash 3.2), an integration job that uses the action, and the major version tag moved on release - release-please keeps the version in the script current --- .github/actionlint.yaml | 7 ++ .github/config/release-please-config.json | 8 +- .github/workflows/ci.yml | 87 +++++++++++++++++-- README.md | 80 ++++++++++++----- action.yml | 35 ++++++++ bin/devcontainer-sh => devcontainer-sh | 0 devcontainer-sh.plugin.zsh | 8 +- flake.nix | 38 +++++++- tests/dispatch.bats | 2 +- .../workspace/.devcontainer/devcontainer.json | 4 + tests/helpers.bash | 4 +- tests/plugin.bats | 2 +- 12 files changed, 234 insertions(+), 41 deletions(-) create mode 100644 .github/actionlint.yaml create mode 100644 action.yml rename bin/devcontainer-sh => devcontainer-sh (100%) create mode 100644 tests/fixtures/workspace/.devcontainer/devcontainer.json diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 0000000..567d7ef --- /dev/null +++ b/.github/actionlint.yaml @@ -0,0 +1,7 @@ +paths: + # actionlint 1.7.12 knows actions/create-github-app-token@v3 by its older + # inputs; v3 itself takes client-id and deprecates app-id. + .github/workflows/update.yml: + ignore: + - 'missing input "app-id"' + - 'input "client-id" is not defined' diff --git a/.github/config/release-please-config.json b/.github/config/release-please-config.json index affa12d..21a6e48 100644 --- a/.github/config/release-please-config.json +++ b/.github/config/release-please-config.json @@ -1,7 +1,13 @@ { "packages": { ".": { - "release-type": "simple" + "release-type": "simple", + "extra-files": [ + { + "type": "generic", + "path": "devcontainer-sh" + } + ] } } } diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index be9dd0f..ebd2381 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,13 +10,13 @@ concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +permissions: + contents: read + jobs: - test: + lint: runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: write - timeout-minutes: 30 + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@v7 @@ -24,13 +24,75 @@ jobs: - name: Install Nix uses: DeterminateSystems/nix-installer-action@v23 + - name: Run ShellCheck + run: nix develop --command shellcheck --shell=bash devcontainer-sh + + - name: Run actionlint + run: nix develop --command actionlint + + - name: Build the Nix package + run: nix build + + test: + strategy: + fail-fast: false + matrix: + # macOS runs the macOS system bash, 3.2, through /bin/bash first on PATH. + os: [ubuntu-latest, macos-latest] + runs-on: ${{ matrix.os }} + timeout-minutes: 30 + steps: + - name: Checkout + uses: actions/checkout@v7 + + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@v23 - name: Run Tests + run: nix develop --command bats tests/ + + - name: Run Tests with the system bash + if: runner.os == 'macOS' + run: | + mkdir -p "$RUNNER_TEMP/bash32" + ln -s /bin/bash "$RUNNER_TEMP/bash32/bash" + bash_version="$(PATH="$RUNNER_TEMP/bash32:$PATH" bash --version | head -1)" + echo "$bash_version" + nix develop --command env PATH="$RUNNER_TEMP/bash32:$PATH" bats tests/ + + # The action, used the way a workflow would use it, against a real container. + action: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout + uses: actions/checkout@v7 + + - name: Use the action + uses: ./ + + - name: Start the dev container + run: devcontainer-sh up --workspace-folder tests/fixtures/workspace + + - name: Run a command in it + run: | + out="$(devcontainer-sh exec --workspace-folder tests/fixtures/workspace -- sh -c 'echo ok && id -un')" + echo "$out" + test "$(printf '%s\n' "$out" | head -1)" = ok + + - name: The exit status comes through run: | - nix develop --command bats tests/ + if devcontainer-sh exec --workspace-folder tests/fixtures/workspace -- false; then + echo "expected a failure" >&2 + exit 1 + fi + + - name: Remove the dev container + if: always() + run: devcontainer-sh down --workspace-folder tests/fixtures/workspace release: - needs: test + needs: [lint, test, action] if: github.event_name == 'push' runs-on: ubuntu-latest outputs: @@ -54,3 +116,14 @@ jobs: manifest-file: .github/config/release-please-manifest.json config-file: .github/config/release-please-config.json target-branch: main + + # Callers pin the major version, e.g. @v1, so it follows every release. + - name: Move the major version tag + if: steps.release.outputs.release_created + env: + TAG: ${{ steps.release.outputs.tag_name }} + MAJOR: v${{ steps.release.outputs.major }} + run: | + git fetch --tags --quiet + git tag --force "$MAJOR" "$TAG" + git push --force origin "$MAJOR" diff --git a/README.md b/README.md index 634a6a8..15405e3 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,81 @@ # devcontainer-sh -> Zsh plugin for the devcontainer CLI — one dispatcher command, workspace auto-detection, and tab completion. Stop typing `--workspace-folder`. +> A thin wrapper around the devcontainer CLI — one command, workspace auto-detection, tab completion, and a GitHub Action for CI. Stop typing `--workspace-folder`. [![CI](https://github.com/devcontainer-env/devcontainer-sh/actions/workflows/ci.yml/badge.svg)](https://github.com/devcontainer-env/devcontainer-sh/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/devcontainer-env/devcontainer-sh)](https://github.com/devcontainer-env/devcontainer-sh/releases/latest) -[![Shell: zsh](https://img.shields.io/badge/shell-zsh-1793D1.svg)](https://www.zsh.org/) +[![Shell: bash](https://img.shields.io/badge/shell-bash-4EAA25.svg?logo=gnubash&logoColor=white)](https://www.gnu.org/software/bash/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -The upstream [`@devcontainers/cli`](https://github.com/devcontainers/cli) is powerful but verbose — nearly every invocation needs `--workspace-folder`, there's no first-class "shell into the container" verb, and rebuild-and-recreate is a stack of flags. This plugin smooths those edges without hiding the underlying CLI: unknown flags pass straight through. +The upstream [`@devcontainers/cli`](https://github.com/devcontainers/cli) is powerful but verbose — nearly every invocation needs `--workspace-folder`, there's no first-class "shell into the container" verb, and rebuild-and-recreate is a stack of flags. This tool smooths those edges without hiding the underlying CLI: unknown flags pass straight through. + +It is one bash script, so the same commands work in your terminal and in CI. ## Installation -### oh-my-zsh +### GitHub Actions -```bash -git clone https://github.com/devcontainer-env/devcontainer-sh \ - "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/devcontainer-sh" +```yaml +steps: + - uses: actions/checkout@v7 + - uses: devcontainer-env/devcontainer-sh@v1 + - run: devcontainer-sh up + - run: devcontainer-sh exec -- make test ``` -Then add `devcontainer-sh` to the `plugins=(...)` line in your `.zshrc`. +The action puts `devcontainer-sh` on `PATH` and installs the `devcontainer` CLI when it isn't already there. It doesn't start anything, so you choose when to `up`. GitHub-hosted runners are discarded after the job, so no cleanup is needed there. On self-hosted runners, add a step that always runs: -### zinit +```yaml + - run: devcontainer-sh down + if: always() +``` -```zsh -zinit light devcontainer-env/devcontainer-sh +| Input | Description | Default | +| ------------- | ----------------------------------------------------- | -------- | +| `cli-version` | `@devcontainers/cli` version, if none is on `PATH` | `latest` | + +### Nix + +```bash +nix run github:devcontainer-env/devcontainer-sh -- up +nix profile install github:devcontainer-env/devcontainer-sh ``` -### antidote +The package includes the zsh completions. It doesn't bundle the `devcontainer` CLI or Docker. -Add to your `.zsh_plugins.txt`: +### Any shell -```text -devcontainer-env/devcontainer-sh +Put the `devcontainer-sh` script on your `PATH`: + +```bash +git clone https://github.com/devcontainer-env/devcontainer-sh ~/.devcontainer-sh +echo 'export PATH="$HOME/.devcontainer-sh:$PATH"' >> ~/.bashrc ``` -### Manual +### zsh plugin managers + +The plugin puts the script on `PATH` and registers the completions. + +```bash +# oh-my-zsh +git clone https://github.com/devcontainer-env/devcontainer-sh \ + "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/devcontainer-sh" +# then add devcontainer-sh to plugins=(...) in ~/.zshrc +``` ```zsh -git clone https://github.com/devcontainer-env/devcontainer-sh ~/.zsh/devcontainer-sh -echo 'source ~/.zsh/devcontainer-sh/devcontainer-sh.plugin.zsh' >> ~/.zshrc +# zinit +zinit light devcontainer-env/devcontainer-sh +``` + +```text +# antidote (.zsh_plugins.txt) +devcontainer-env/devcontainer-sh ``` ## Requirements -- zsh 5.0+ +- bash 3.2+ (the macOS system bash is enough) - [`@devcontainers/cli`](https://github.com/devcontainers/cli) on `$PATH` (`npm i -g @devcontainers/cli`) - Docker (for the `down` command) @@ -59,7 +91,7 @@ Commands: build Build the dev container image down Stop and remove the container associated with this workspace help Show usage - version Plugin version + upstream CLI version + version Wrapper version + upstream CLI version ``` **devcontainer-sh up** — Create and start the dev container. Auto-detects `--workspace-folder` by walking up from `$PWD` to find `.devcontainer/devcontainer.json` or `.devcontainer.json`. @@ -79,7 +111,7 @@ devcontainer-sh shell bash # force bash devcontainer-sh sh fish # short form ``` -**devcontainer-sh exec** — Run a one-off command in the container. Everything is forwarded to `devcontainer exec`. +**devcontainer-sh exec** — Run a one-off command in the container. Everything is forwarded to `devcontainer exec`, and its exit status is passed through. ```bash devcontainer-sh exec -- bash -lc 'pnpm test' @@ -102,15 +134,15 @@ devcontainer-sh down ### Workspace auto-detection -All commands walk up from `$PWD` looking for `.devcontainer/devcontainer.json` or `.devcontainer.json` and pass that directory as `--workspace-folder`. Pass `--workspace-folder` yourself to override. +All commands walk up from `$PWD` looking for `.devcontainer/devcontainer.json` or `.devcontainer.json` and pass that directory as `--workspace-folder`. Pass `--workspace-folder` yourself to override. A `--workspace-folder` after a bare `--` belongs to the command you're running and is left alone. ### Pass-through -Unknown flags are forwarded to the upstream CLI untouched, so anything documented in `devcontainer up --help` / `exec --help` / `build --help` still works (`--log-level`, `--remote-env`, `--mount`, `--id-label`, …). +Unknown flags are forwarded to the upstream CLI untouched, so anything documented in `devcontainer up --help` / `exec --help` / `build --help` still works (`--log-level`, `--remote-env`, `--mount`, `--id-label`, `--secrets-file`, …). ### Tab completion -The plugin ships `_devcontainer-sh` (dispatcher) and `_devcontainer` (upstream binary) completion files. Both are added to `$fpath` on load — make sure `compinit` has been called in your `.zshrc` (oh-my-zsh / zinit / antidote do this for you). +Zsh completions ship for `devcontainer-sh` and for the upstream `devcontainer` binary (`completions/_devcontainer-sh` and `completions/_devcontainer`). The zsh plugin and the Nix package both put them on `$fpath`; make sure `compinit` has been called in your `.zshrc`. ## License diff --git a/action.yml b/action.yml new file mode 100644 index 0000000..4f9f553 --- /dev/null +++ b/action.yml @@ -0,0 +1,35 @@ +name: devcontainer-sh +description: >- + Put devcontainer-sh on PATH and install the devcontainer CLI, so later steps + can run devcontainer-sh up, exec and down. +author: devcontainer-env +branding: + icon: box + color: blue + +inputs: + cli-version: + description: Version of @devcontainers/cli to install when none is on PATH. + required: false + default: latest + +runs: + using: composite + steps: + - name: Add devcontainer-sh to PATH + shell: bash + env: + ACTION_PATH: ${{ github.action_path }} + run: echo "$ACTION_PATH" >> "$GITHUB_PATH" + + - name: Install the devcontainer CLI + shell: bash + env: + CLI_VERSION: ${{ inputs.cli-version }} + run: | + if command -v devcontainer >/dev/null 2>&1; then + echo "devcontainer CLI already installed: $(devcontainer --version)" + exit 0 + fi + npm install --global "@devcontainers/cli@${CLI_VERSION}" + devcontainer --version diff --git a/bin/devcontainer-sh b/devcontainer-sh similarity index 100% rename from bin/devcontainer-sh rename to devcontainer-sh diff --git a/devcontainer-sh.plugin.zsh b/devcontainer-sh.plugin.zsh index 166bf31..f742d2d 100644 --- a/devcontainer-sh.plugin.zsh +++ b/devcontainer-sh.plugin.zsh @@ -1,8 +1,8 @@ # devcontainer-sh — zsh plugin entry. # -# The tool is the bash executable in bin/; this file only puts it on PATH and -# registers the zsh completions, so oh-my-zsh, zinit, antidote or a plain -# `source` keep working. +# The tool is the bash executable devcontainer-sh next to this file. This file +# only puts it on PATH and registers the zsh completions, so oh-my-zsh, zinit, +# antidote or a plain `source` keep working. 0="${${ZERO:-${0:#$ZSH_ARGZERO}}:-${(%):-%N}}" 0="${${(M)0:#/*}:-$PWD/$0}" @@ -12,6 +12,6 @@ local plugin_dir="${1:A:h}" - path=("$plugin_dir/bin" $path) + path=("$plugin_dir" $path) fpath=("$plugin_dir/completions" $fpath) } "$0" diff --git a/flake.nix b/flake.nix index 27ee74b..0770109 100644 --- a/flake.nix +++ b/flake.nix @@ -1,5 +1,5 @@ { - description = "devcontainer-sh development shell"; + description = "A thin wrapper around the devcontainer CLI: one command, workspace auto-detection"; inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; @@ -16,14 +16,50 @@ system: let pkgs = nixpkgs.legacyPackages.${system}; + lib = pkgs.lib; + + # The version lives in the script, where release-please keeps it. + version = lib.pipe (builtins.readFile ./devcontainer-sh) [ + (lib.splitString "\n") + (lib.findFirst (lib.hasPrefix "DEVCONTAINER_SH_VERSION=") null) + (builtins.match "DEVCONTAINER_SH_VERSION=\"([^\"]+)\".*") + builtins.head + ]; + + devcontainer-sh = pkgs.stdenvNoCC.mkDerivation { + pname = "devcontainer-sh"; + inherit version; + src = lib.fileset.toSource { + root = ./.; + fileset = lib.fileset.unions [ + ./devcontainer-sh + ./completions + ]; + }; + dontBuild = true; + # The devcontainer CLI and docker are the user's, not wrapped in. + installPhase = '' + install -Dm0755 devcontainer-sh $out/bin/devcontainer-sh + install -Dm0644 -t $out/share/zsh/site-functions \ + completions/_devcontainer-sh completions/_devcontainer + ''; + meta = { + description = "A thin wrapper around the devcontainer CLI"; + mainProgram = "devcontainer-sh"; + license = lib.licenses.mit; + }; + }; in { + packages.default = devcontainer-sh; + devShells.default = pkgs.mkShell { name = "devcontainer-sh"; packages = with pkgs; [ zsh bats shellcheck + actionlint ]; }; } diff --git a/tests/dispatch.bats b/tests/dispatch.bats index 5086781..711d5f4 100644 --- a/tests/dispatch.bats +++ b/tests/dispatch.bats @@ -32,7 +32,7 @@ teardown() { teardown_stubs; } @test "version fails when the devcontainer CLI is missing" { rm "$STUB_DIR/devcontainer" - PATH="$PLUGIN_ROOT/bin:$STUB_DIR:/usr/bin:/bin" run devcontainer-sh version + PATH="$PLUGIN_ROOT:$STUB_DIR:/usr/bin:/bin" run devcontainer-sh version [ "$status" -eq 1 ] [[ "$output" == *"CLI not found"* ]] } diff --git a/tests/fixtures/workspace/.devcontainer/devcontainer.json b/tests/fixtures/workspace/.devcontainer/devcontainer.json new file mode 100644 index 0000000..e3558af --- /dev/null +++ b/tests/fixtures/workspace/.devcontainer/devcontainer.json @@ -0,0 +1,4 @@ +{ + "name": "devcontainer-sh-fixture", + "image": "mcr.microsoft.com/devcontainers/base:bookworm" +} diff --git a/tests/helpers.bash b/tests/helpers.bash index cc60e61..1d7a3b1 100644 --- a/tests/helpers.bash +++ b/tests/helpers.bash @@ -1,6 +1,6 @@ # Shared bats helpers. # -# Each test runs the real bin/devcontainer-sh with stubbed `devcontainer` and +# Each test runs the real devcontainer-sh with stubbed `devcontainer` and # `docker` binaries first on PATH. The stubs echo whatever args they receive so # we can assert what the wrapper dispatches. @@ -20,7 +20,7 @@ case "$1" in esac STUB chmod +x "$STUB_DIR/devcontainer" "$STUB_DIR/docker" - export PATH="$PLUGIN_ROOT/bin:$STUB_DIR:$PATH" + export PATH="$PLUGIN_ROOT:$STUB_DIR:$PATH" } teardown_stubs() { diff --git a/tests/plugin.bats b/tests/plugin.bats index dcea758..dd6be08 100644 --- a/tests/plugin.bats +++ b/tests/plugin.bats @@ -14,7 +14,7 @@ teardown() { teardown_stubs; } command -v devcontainer-sh " [ "$status" -eq 0 ] - [[ "$output" == *"/bin/devcontainer-sh" ]] + [[ "$output" == */devcontainer-sh ]] } @test "sourcing the zsh plugin registers the completions" { From bb88684c7d4beae6bd7591aa2dfbd0deb3536e24 Mon Sep 17 00:00:00 2001 From: Svetlin Ralchev Date: Thu, 19 Nov 2026 12:48:13 +0400 Subject: [PATCH 3/4] fix(ci): ignore the App token false positive in merge.yml, keep PATH inside the dev shell on macOS --- .github/actionlint.yaml | 4 ++++ .github/workflows/ci.yml | 11 ++++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml index 567d7ef..0c73141 100644 --- a/.github/actionlint.yaml +++ b/.github/actionlint.yaml @@ -5,3 +5,7 @@ paths: ignore: - 'missing input "app-id"' - 'input "client-id" is not defined' + .github/workflows/merge.yml: + ignore: + - 'missing input "app-id"' + - 'input "client-id" is not defined' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ebd2381..01c976b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,9 +56,14 @@ jobs: run: | mkdir -p "$RUNNER_TEMP/bash32" ln -s /bin/bash "$RUNNER_TEMP/bash32/bash" - bash_version="$(PATH="$RUNNER_TEMP/bash32:$PATH" bash --version | head -1)" - echo "$bash_version" - nix develop --command env PATH="$RUNNER_TEMP/bash32:$PATH" bats tests/ + # PATH is changed inside the dev shell, so bats and the rest of its + # tools are still found; only `bash` now resolves to the system one. + # shellcheck disable=SC2016 # the inner sh expands these, on purpose + nix develop --command sh -c ' + PATH="$1:$PATH" + bash --version | head -1 + bats tests/ + ' _ "$RUNNER_TEMP/bash32" # The action, used the way a workflow would use it, against a real container. action: From aa647377d28f9c75a130b798e05fed5e31667268 Mon Sep 17 00:00:00 2001 From: Svetlin Ralchev Date: Thu, 19 Nov 2026 12:59:59 +0400 Subject: [PATCH 4/4] test: keep the non-interactive test away from the user's ~/.bashrc --- tests/dispatch.bats | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tests/dispatch.bats b/tests/dispatch.bats index 711d5f4..4c5a475 100644 --- a/tests/dispatch.bats +++ b/tests/dispatch.bats @@ -38,6 +38,11 @@ teardown() { teardown_stubs; } } @test "runs without a login or interactive shell" { - run env -i PATH="$PATH" HOME="$HOME" bash -c 'devcontainer-sh help' - [ "$status" -eq 0 ] + # An empty HOME and a closed stdin: bash reads ~/.bashrc even for `-c` when + # its stdin is a socket (as under sshd), and that is not what is tested here. + run env -i PATH="$PATH" HOME="$BATS_TEST_TMPDIR" bash -c 'devcontainer-sh help' < /dev/null + [ "$status" -eq 0 ] || { + echo "status=$status bash=$(command -v bash) output=$output" >&2 + return 1 + } }