feat(SwapTokenPositions): Version 2.1.0 - Added explicit token targeting

SwapTokenPositions/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to the **SwapTokenPositions** script will be documented in this file.
 
+## [2.1.0] - 2026-05-19 · [Milestone](https://github.com/steverobertsuk/roll20-api-scripts/milestone/4)
+
+### Added
+
+- Explicit token targeting via `--token1 <id|name>` and `--token2 <id|name>` flags.
+  - Both flags must be provided together; omitting one produces a clear usage error.
+  - Each input resolves by token ID first, then by token name on the active page.
+  - Ambiguous name matches (multiple tokens with the same name) are rejected with guidance to use a token ID.
+  - Cross-page explicit pairs are rejected the same as cross-page selection pairs.
+- `parseFreeStringFlag` parser utility to handle quoted (space-containing) and unquoted string values.
+- Explicit token access control via three new GM-only management commands (take effect immediately, no `--save` required):
+  - `--token-input-access <gm-only|all-players|selected-users>` — sets who may use `--token1` and `--token2`.
+  - `--token-input-users <id|name,...>` — replaces the allow-list with the specified players (resolved by ID then display name).
+  - `--token-input-users-remove <id|name,...>` — removes specific players from the allow-list.
+  - Default mode is `gm-only`. The GM is always permitted regardless of mode.
+  - `--show-settings` now includes `Token Input Access` and (in `selected-users` mode) `Token Input Users`.
+- `parseCommaListFlag` parser utility for comma-separated quoted and bare values.
+
+### Developer
+
+- Build process now automatically syncs `package.json` version from `script.json` on each build.
+- Build process now auto-increments the trailing build number on pre-release versions (e.g. `2.1.0.beta.0` → `2.1.0.beta.1`) so the version is always up to date after each `npm run build`. Release versions (`major.minor.patch`) are not auto-incremented.
+- Versioned archive folder now uses the base semver (`major.minor.patch`) rather than the full pre-release string, so pre-release builds update the same folder in place.
+
 ## [2.0.0] - 2026-04-24
 
 ### Added

SwapTokenPositions/README.md

@@ -5,6 +5,8 @@
 ## Features
 
 - **Seamless Swapping**: Select exactly two tokens on the same page and run `!swap-tokens` to switch their positions.
+- **Explicit Token Targeting**: Target tokens directly by ID or name using `--token1` and `--token2` — no selection required, ideal for macros.
+- **Explicit Token Access Control**: GMs can restrict `--token1`/`--token2` usage to GM-only, all players, or a named allow-list.
 - **Staged Animation Pipeline**:
   - `origin`: Point FX at starting positions.
   - `travel`: Beam FX and optional travel visibility behavior.
@@ -44,10 +46,42 @@ The v2 series keeps the same core command (`!swap-tokens`) but changes how anima
 `!swap-tokens`
 Swaps the two currently selected tokens using the default settings.
 
+### Explicit Token Targeting (Macro-Friendly)
+
+`!swap-tokens --token1 <id|name> --token2 <id|name>`
+Swaps two specific tokens without requiring them to be selected. Both flags must be provided together.
+
+**Token resolution order (per flag):**
+
+1. Resolve as a token ID.
+2. If not found, resolve as a token name on the active page.
+
+**Rules:**
+
+- Quoted names support spaces: `--token1 "Goblin A"`
+- When a name matches multiple tokens on the active page, the command fails with an ambiguity error. Use the token ID instead.
+- Cross-page pairs are rejected the same as cross-page selections.
+- Providing only `--token1` or only `--token2` is an error.
+
+**Examples:**
+
+- `!swap-tokens --token1 -Kabc123 --token2 -Kdef456` — swap by token ID
+- `!swap-tokens --token1 "Goblin A" --token2 "Goblin B"` — swap by unique name
+- `!swap-tokens --token1 -Kabc123 --token2 "Goblin B"` — mixed ID and name
+- `!swap-tokens --token1 "Goblin A" --token2 "Goblin B" --preset portal` — explicit targeting with FX
+
+**Advanced macro example:**
+
+```
+!swap-tokens --token1 @{selected|token_id} --token2 @{target|token_id} --preset portal
+```
+
 ### Acceptable Parameters for Customization (Available to Everyone)
 
 - `--help`: Displays the help menu.
 - `--instant`: Skips all FX and timing and swaps immediately.
+- `--token1 <id|name>`: First token for explicit targeting (must be paired with `--token2`).
+- `--token2 <id|name>`: Second token for explicit targeting (must be paired with `--token1`).
 - `--preset <value>`: Applies a preset.
   - Values: `portal`, `lightning`, `shadow`, `fire`, `magic`, `transport`, `none`
 - `--origin-fx <value>`: Point FX at both origin positions.
@@ -80,6 +114,28 @@ Swaps the two currently selected tokens using the default settings.
 - `--reset-settings`: Restores the script to its factory defaults.
 - `--install-macro`: Automatically creates a global "SwapTokens" macro in your campaign.
 
+### Explicit Token Access Control (GM Only)
+
+These commands take effect immediately — `--save` is not required.
+
+- `--token-input-access <mode>`: Sets who may use `--token1` and `--token2`.
+  - `gm-only` (default): Only the GM can use explicit token targeting.
+  - `all-players`: Any player can use explicit token targeting.
+  - `selected-users`: Only players on the allow-list (and the GM) can use explicit token targeting.
+- `--token-input-users <id|name,...>`: Replaces the allow-list with the specified players (comma-separated, quoted names supported).
+- `--token-input-users-remove <id|name,...>`: Removes specific players from the allow-list.
+
+The GM is always permitted regardless of the configured mode.
+
+**Examples:**
+
+```
+!swap-tokens --token-input-access all-players
+!swap-tokens --token-input-access selected-users
+!swap-tokens --token-input-users "Alice","Bob"
+!swap-tokens --token-input-users-remove Alice
+```
+
 ### Deprecated Flags
 
 The following flags are still supported for backward compatibility but are deprecated: