feat: opk update --channel <ref> — switch the tracking ref without editing install.conf

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 |
 | `<branch>` / `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)

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 <file>` | Install a specific binary file instead |
+| `--channel <ref>` | 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

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 <ref> 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)

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/<branch>
+# 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/<branch>
+#
+# --channel <ref> pre-scan: 'opk update --channel <ref>' 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 <<EOF
 opencode permissions kit -- update.sh  v$VERSION
 Re-deploys the kit on an already-installed system. No prompts by default.
-Usage: ./update.sh [--yes] [--refresh] [--binary] [--only-binary] [--binary-path <file>]
+Usage: ./update.sh [--yes] [--refresh] [--binary] [--only-binary] [--binary-path <file>] [--channel <ref>]
   --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
             ;;

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 <ref>' \"\$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 "===================================="