diff --git a/docs/how-to/update.md b/docs/how-to/update.md index ee47679..6a2ee1f 100644 --- a/docs/how-to/update.md +++ b/docs/how-to/update.md @@ -13,9 +13,20 @@ The kit ships from two refs; which one you use is stamped into | `master` | Development channel — moves with every merged PR | Testing the newest changes | | `` / `x.y.z` | Any feature branch, or an exact version tag (e.g. `0.0.29`) | Testing a PR, pinning a version | -`opk update` follows the stamped channel automatically. Switch explicitly -with the `KIT_BRANCH` environment variable — install or update, same -mechanism: +`opk update` follows the stamped channel automatically. The easy switch is +the `--channel` flag — updates from the given ref and re-stamps +`KIT_CHANNEL` in one go, so subsequent plain `opk update` runs stay on the +new channel: + +```bash +sudo opk update --channel stable # release mirror (recommended default) +sudo opk update --channel master # development channel +sudo opk update --channel feature/wsl-conf-user-consent # test a branch +sudo opk update --channel 0.0.29 # pin an exact version +``` + +The `KIT_BRANCH` environment variable does the same for every entry point +(curl-streamed install or update, `opk update`): ```bash # update from the stable release mirror (recommended default) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index cfba229..868b8a2 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -148,7 +148,12 @@ curl -fsSL https://raw.githubusercontent.com/steffenmaechtel/opencode-permission ``` Without `KIT_BRANCH` set, the deployed `update.sh` follows the channel -stamped in `install.conf` (`KIT_CHANNEL`, shown by `opk status`). +stamped in `install.conf` (`KIT_CHANNEL`, shown by `opk status`). Switch +channels without editing `install.conf`: + +```bash +sudo opk update --channel stable # or master, a feature branch, or a tag +``` | Flag | Meaning | |---|---| @@ -157,6 +162,7 @@ stamped in `install.conf` (`KIT_CHANNEL`, shown by `opk status`). | `--binary` | Also upgrade the opencode binary to the latest release | | `--only-binary` | Skip every kit step, only upgrade the opencode binary | | `--binary-path ` | Install a specific binary file instead | +| `--channel ` | Switch the tracking ref for this and every future update (re-stamps `KIT_CHANNEL`) | `opk upgrade-opencode` is the shorthand for `update --yes --only-binary` — extra flags (e.g. `--binary-path`) pass diff --git a/files/opencode-permissions-kit-lib/bin/opk b/files/opencode-permissions-kit-lib/bin/opk index 12b09c1..a4f6726 100755 --- a/files/opencode-permissions-kit-lib/bin/opk +++ b/files/opencode-permissions-kit-lib/bin/opk @@ -60,8 +60,11 @@ Commands: ddev-settings on|off|status (dev-owned projects) update [--yes] [--refresh] Re-deploy the kit; --binary / --binary-path - upgrade the opencode binary; --only-binary - skips every kit step and only upgrades it + upgrade the opencode binary; --only-binary + skips every kit step and only upgrades it; + --channel switches the tracking ref + (stable, master, a branch, a tag) for this + and every future update upgrade-opencode [flags...] Just upgrade the opencode binary — shorthand for 'update --yes --only-binary' (extra flags pass through, e.g. --binary-path) diff --git a/files/opencode-permissions-kit-lib/management/update.sh b/files/opencode-permissions-kit-lib/management/update.sh index 7cb4519..a00cfa4 100755 --- a/files/opencode-permissions-kit-lib/management/update.sh +++ b/files/opencode-permissions-kit-lib/management/update.sh @@ -34,11 +34,26 @@ set -e # Ref the kit updates from. Resolution (issue #38, docs/design/ -# release-handling.md): explicit KIT_BRANCH env > KIT_CHANNEL stamp in -# install.conf (the channel this machine installed/last updated from) > -# master (development channel; 'stable' is the release mirror the docs -# one-liners use). Must run BEFORE the self-fetch below. Overridable for -# testing: KIT_BASE_URL=https://example.invalid/ +# release-handling.md): --channel flag (pre-scanned below) > explicit +# KIT_BRANCH env > KIT_CHANNEL stamp in install.conf (the channel this +# machine installed/last updated from) > master (development channel; +# 'stable' is the release mirror the docs one-liners use). Must run BEFORE +# the self-fetch below. Overridable for testing: +# KIT_BASE_URL=https://example.invalid/ +# +# --channel pre-scan: 'opk update --channel ' switches the +# tracking ref for THIS update and every future one — update.sh re-stamps +# KIT_CHANNEL at the end, so the switch persists. The scan must happen +# before the resolution below and before the fetch; the regular arg loop +# below consumes and validates the flag again. +_prev_arg="" +for _arg in "$@"; do + if [ "$_prev_arg" = "--channel" ]; then + [ -n "$_arg" ] || { echo "error: --channel requires a ref (stable, master, a branch, or a tag)" >&2; exit 1; } + KIT_BRANCH="$_arg" + fi + _prev_arg="$_arg" +done _kit_stamped_channel="$(sed -n 's/^KIT_CHANNEL=//p' /etc/opencode-permissions-kit/install.conf 2>/dev/null | tail -1)" KIT_BRANCH="${KIT_BRANCH:-${_kit_stamped_channel:-master}}" KIT_BASE_URL="${KIT_BASE_URL:-https://raw.githubusercontent.com/steffenmaechtel/opencode-permissions-kit/$KIT_BRANCH}" @@ -244,16 +259,24 @@ while [ "$#" -gt 0 ]; do BINARY_PATH="$2" shift ;; + --channel) + # consumed by the pre-scan above (before the self-fetch); + # accepted here so it never reaches the unknown-option trap + [ "$#" -ge 2 ] || { echo "error: --channel requires a ref (stable, master, a branch, or a tag)" >&2; exit 1; } + shift + ;; -h|--help) cat <] +Usage: ./update.sh [--yes] [--refresh] [--binary] [--only-binary] [--binary-path ] [--channel ] --yes skip the confirmation prompt --refresh also re-apply the group baseline (chgrp/setgid/default ACLs) --binary also upgrade the opencode binary to the latest release --only-binary skip every kit step, ONLY upgrade the opencode binary --binary-path install the given binary file instead of downloading + --channel switch the tracking ref for this and every future update + (stable, master, a feature branch, or a pinned tag) EOF exit 0 ;; diff --git a/tests/unit/test-update-flags.sh b/tests/unit/test-update-flags.sh index 40fb8a3..38e81c7 100755 --- a/tests/unit/test-update-flags.sh +++ b/tests/unit/test-update-flags.sh @@ -169,6 +169,25 @@ check "ddev stamp: old stamp survives when no binary answers" \ check "ddev stamp: summary line reports the refreshed value" \ sh -c "grep -q 'DDEV_VERSION=\$NEW_DDEV_VERSION' \"\$1\"" _ "$UPDATE" +# --- 7. --channel (switch the tracking ref without editing install.conf) -------- +_prescan_ln=$(grep -n '_prev_arg' "$UPDATE" | head -1 | cut -d: -f1) +_resolv_ln=$(grep -n '_kit_stamped_channel=' "$UPDATE" | head -1 | cut -d: -f1) +if [ -n "$_prescan_ln" ] && [ -n "$_resolv_ln" ] && [ "$_prescan_ln" -lt "$_resolv_ln" ]; then + pass "channel: pre-scan runs before the stamp resolution (fetch uses the new ref)" +else + fail "channel: pre-scan runs before the stamp resolution (fetch uses the new ref)" +fi +check "channel: arg loop accepts --channel with a value (not 'unknown option')" \ + sh -c "grep -q -- '--channel)' \"\$1\" && grep -qF -- '--channel requires a ref' \"\$1\"" _ "$UPDATE" +check "channel: help text documents --channel" \ + sh -c "grep -q -- '--channel ' \"\$1\"" _ "$UPDATE" +check "channel: switch persists via the KIT_CHANNEL re-stamp" \ + sh -c "grep -qF 'KIT_CHANNEL=\$KIT_BRANCH' \"\$1\"" _ "$UPDATE" +check "channel: missing ref is rejected (arg loop, from a checkout)" \ + sh -c "! sh \"\$1\" --channel >/dev/null 2>&1" _ "$UPDATE" +check "channel: --help with --channel still works (pre-scan is silent)" \ + sh -c "sh \"\$1\" --channel testref --help >/dev/null 2>&1" _ "$UPDATE" + # --- Summary ---------------------------------------------------------------------- echo "" echo "===================================="