shiftcare-toolkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8197a28b179e8ad2102311ada3a7b15cfe01f95a0a81ff97937e3d9d682fef09
+  data.tar.gz: f490ba1cb22ae90e4b2dda411477193c835260b26c6ebb347e3a3e6c3ce2f06f
+SHA512:
+  metadata.gz: 5307120569d6c5d3fc493a13a71384e25f77533156b2658ef6695326fcf732ed88259f3f31f011e74146600d89654b35f21e85358c71b032bbbbf5b7c0be518b
+  data.tar.gz: 05baed828c4b22ebdf1941ca0e4d26ee31a8382b62bf1da38b7f6ae9b3bb7ee5ee9479c9cac916617221ef840c2265da0d9b74362f1d7ca2faf0a82f6ff780a3

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 - 2026-10-02
+
+- First release: `setup`, `regions` (`status`), `list`, `show`, `create`, `update` and `copy`
+  against `/internal/product_releases` in au, us, uk, ca and custom regions.
+- Custom `User-Agent`, 1 request/second per region, bounded retry on 429.
+- Config in `~/.config/shiftcare-toolkit/config.yml` (0600), `SHIFTCARE_TOOLKIT_TOKEN_<REGION>` overrides.

data/README.md

@@ -0,0 +1,246 @@
+# shiftcare-toolkit
+
+Internal ShiftCare command-line tools, one namespace per tool. Region tokens are set up
+once and shared by every tool.
+
+| Command | What it does |
+|---|---|
+| `shiftcare-toolkit setup` / `regions` | Save and check a token per region (au, us, uk, ca or custom) |
+| `shiftcare-toolkit releases ...` | Product Releases API (`/internal/product_releases`): list, show, create, update, copy between regions |
+
+Runtime is the Ruby standard library only. Ruby 3.1 or later.
+
+## Install
+
+```sh
+gem install shiftcare-toolkit
+shiftcare-toolkit setup
+```
+
+From the git repo:
+
+```sh
+git clone https://github.com/shiftcare/shiftcare-toolkit.git
+cd shiftcare-toolkit
+gem build shiftcare-toolkit.gemspec
+gem install ./shiftcare-toolkit-*.gem --local
+shiftcare-toolkit --help
+```
+
+If someone hands you a built `.gem`, `gem install ./shiftcare-toolkit-0.1.0.gem --local` is enough.
+
+To run from a checkout without installing: `bundle install && bundle exec exe/shiftcare-toolkit --help`.
+
+## Regions
+
+| Region | Base URL |
+|---|---|
+| `au` (default) | https://app.shiftcare.com |
+| `us` | https://us.shiftcare.com |
+| `uk` | https://uk.shiftcare.com |
+| `ca` | https://ca.shiftcare.com |
+
+Add a custom region, such as staging or local, with `setup --region NAME --url URL`.
+Every command takes `--region R`. Without it the CLI uses `default_region` from the
+config file (`au` until you change it).
+
+## Tokens
+
+Each region issues its own tokens, and **a token works only in the region that issued it**.
+You need one token per region you want to use.
+
+To create one, sign in to that region's super admin console and open
+**Admin -> Admin API tokens** (the key icon in the header) -> **Create token**:
+
+- Name: say what and where, for example `Release bot AU (yourname)`.
+- Scope: `product_releases:write`.
+- Expiry: 30 or 90 days.
+
+The token (`scadm_...`) is shown once. Copy it straight into `setup`.
+When it expires or is revoked, the CLI reports `401`; create a new one and run `setup` again.
+
+## Setup
+
+Interactive, walks au, us, uk and ca. Input is hidden; press Enter to skip a region.
+Each token is checked against the API before it is saved.
+
+```console
+$ shiftcare-toolkit setup
+Paste a token for each region (input is hidden), or press Enter to skip.
+au (https://app.shiftcare.com) token:
+  au: ok, saved scadm_7Hk2pQ…
+us (https://us.shiftcare.com) token:
+  us: skipped
+...
+```
+
+Non-interactive, one region at a time. The token comes from stdin, never from an argument,
+so it stays out of your shell history:
+
+```sh
+pbpaste | shiftcare-toolkit setup --region us --token-stdin
+shiftcare-toolkit setup --region uk --token-stdin < uk-token.txt
+```
+
+Custom region:
+
+```sh
+shiftcare-toolkit setup --region staging --url https://staging.example.com
+pbpaste | shiftcare-toolkit setup --region staging --token-stdin
+```
+
+The config lives in `~/.config/shiftcare-toolkit/config.yml` (or
+`$XDG_CONFIG_HOME/shiftcare-toolkit/config.yml`), mode 0600 in a 0700 directory:
+
+```yaml
+default_region: au      # edit to change the default
+regions:
+  au:
+    token: scadm_...
+  staging:
+    url: https://staging.example.com
+    token: scadm_...
+```
+
+`SHIFTCARE_TOOLKIT_TOKEN_<REGION>` overrides the stored token, for example
+`SHIFTCARE_TOOLKIT_TOKEN_AU` or `SHIFTCARE_TOOLKIT_TOKEN_STAGING`. Use it in CI.
+
+The CLI never prints a full token: output, errors and `--verbose` logs show the prefix only.
+
+## Commands
+
+Run `shiftcare-toolkit help COMMAND` or `shiftcare-toolkit COMMAND --help` for details.
+
+Global options: `--region R`, `--verbose` (logs each request to stderr), `--version`.
+
+### regions (alias: status)
+
+Every region with its URL, masked token, where the token came from, and a live check
+(`ok`, `401`, `403`, `unreachable`, `no token`).
+
+```console
+$ shiftcare-toolkit regions
+REGION  URL                        TOKEN                   CHECK
+au      https://app.shiftcare.com  scadm_7Hk2pQ… (config)  ok (42 releases)
+us      https://us.shiftcare.com   scadm_Lm9xQa… (env)     401
+uk      https://uk.shiftcare.com   -                       no token
+ca      https://ca.shiftcare.com   -                       no token
+default region: au
+```
+
+### releases list
+
+```sh
+shiftcare-toolkit releases list                                    # first page, table
+shiftcare-toolkit releases list --region us --status dev --visibility hidden
+shiftcare-toolkit releases list --page 2
+shiftcare-toolkit releases list --all --json > au-releases.json    # every page
+```
+
+The table shows key, status, visibility, updated_at and title. 50 releases per page.
+
+### releases show
+
+```sh
+shiftcare-toolkit releases show shift_swaps
+shiftcare-toolkit releases show shift_swaps --region uk --json
+```
+
+### releases create
+
+```sh
+shiftcare-toolkit releases create --region au --file release.json
+shiftcare-toolkit releases show shift_swaps --json | shiftcare-toolkit releases create --region us --file -
+```
+
+`release.json` holds `key` plus any writable fields. The file can be bare fields,
+`{"product_release": {...}}`, or `show --json` output; other fields are dropped.
+
+```json
+{
+  "key": "shift_swaps",
+  "title": "Shift swaps",
+  "summary": "Workers can swap shifts without calling the office.",
+  "categories": ["scheduling"],
+  "change_items": ["Request a swap from the app", "Approve swaps in one click"],
+  "links": [{ "label": "Help article", "url": "https://help.shiftcare.com/..." }]
+}
+```
+
+New releases are always `status: dev`, `visibility: hidden`. `409` if the key exists
+(including soft-deleted releases), `422` if the release is invalid.
+
+### releases update
+
+```sh
+shiftcare-toolkit releases update shift_swaps --set title="Shift swaps v2"
+shiftcare-toolkit releases update shift_swaps --set change_items="Swap a shift" --set change_items="Approve a swap"
+shiftcare-toolkit releases update shift_swaps --set 'links=[{"label":"Help","url":"https://help.shiftcare.com"}]'
+shiftcare-toolkit releases update shift_swaps --region us --file patch.json
+```
+
+Array fields (`categories`, `change_items`, `flag_keys`) take one item per `--set`, or a JSON
+array. `links` takes a JSON array. `video_duration_seconds` takes an integer. `--set` overrides
+fields from `--file`. Only hidden dev drafts can be updated; anything else is a `409`.
+
+### releases copy
+
+Copies releases (key + writable fields) from one region to others.
+
+```sh
+shiftcare-toolkit releases copy --from au --to us,uk,ca --dry-run          # see what would change
+shiftcare-toolkit releases copy --from au --to us,uk,ca                    # create what is missing
+shiftcare-toolkit releases copy --from au --to us,uk,ca --key shift_swaps --key rosters_v2
+shiftcare-toolkit releases copy --from au --to us --update-existing        # also update existing drafts
+```
+
+- Keys missing in the target are created as hidden dev drafts.
+- Keys that exist are skipped, unless `--update-existing`: then they are updated if their
+  fields differ. A target that is no longer a hidden dev draft answers `409`; it is reported and
+  skipped, so published releases are never overwritten.
+- Empty (null) source fields are not sent, so copy never clears a field on the target.
+- It ends with a summary per region and exits 1 if anything failed:
+
+```text
+us: created 3, updated 0, skipped 1, failed 0
+uk: created 4, updated 0, skipped 0, failed 0
+```
+
+## Writable fields
+
+`title summary rich_body owner icon tone help_url video_url video_title
+video_duration_seconds categories[] change_items[] flag_keys[] links[{label,url}]`
+
+## Limits
+
+- No delete, no publish, no status or visibility changes, no screenshots or announcements
+  through the API. Do those in the super admin console.
+- 60 requests per minute per token. The CLI sends at most one request per second per region
+  and retries `429` responses with backoff (up to 5 times).
+- Every write is recorded against the admin who created the token.
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| 401 | Token bad, expired or revoked, or used in the wrong region |
+| 403 | Token lacks the `product_releases:write` scope, or Cloudflare blocked the request (error 1010) |
+| 404 | No release with that key (or it was deleted) |
+| 409 | Key already taken (create), or the release is not a hidden dev draft (update) |
+| 422 | Invalid release or filter; the message lists the errors |
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # runs the tests; none touch the network
+```
+
+The HTTP layer is injected (`Client.new(http: ->(uri, request) { ... })`), and
+`test/test_helper.rb` has a small in-memory fake of the API.
+
+## Adding a tool
+
+Add a top-level entry to `COMMANDS` in `lib/shiftcare_toolkit/cli.rb` and dispatch its
+subcommands the way `releases` does (`RELEASE_COMMANDS`). Reuse `Config` for region URLs
+and tokens and `Client` for HTTP (user agent, throttle, 429 retry).

data/exe/shiftcare-toolkit

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "shiftcare_toolkit"
+
+exit ShiftcareToolkit::CLI.new.run(ARGV)

data/lib/shiftcare_toolkit/cli.rb

@@ -0,0 +1,577 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "json"
+require "optparse"
+require_relative "client"
+require_relative "config"
+require_relative "version"
+
+module ShiftcareToolkit
+  class CLI
+    class Error < StandardError; end
+
+    COMMANDS = {
+      "setup" => "Save a token per region, verified against the API first",
+      "regions" => "List regions, their URLs, masked tokens and a live check (alias: status)",
+      "releases" => "Product releases: list, show, create, update, copy",
+    }.freeze
+    RELEASE_COMMANDS = {
+      "list" => "List releases in a region",
+      "show" => "Show one release",
+      "create" => "Create a hidden dev release from a JSON file",
+      "update" => "Update a hidden dev release",
+      "copy" => "Copy releases from one region to others",
+    }.freeze
+    ARRAY_FIELDS = %w[categories change_items flag_keys links].freeze
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, config: nil, http: nil, min_interval: 1.0,
+                   sleeper: ->(s) { sleep(s) })
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @config = config
+      @http = http
+      @min_interval = min_interval
+      @sleeper = sleeper
+      @clients = {}
+    end
+
+    def run(argv)
+      argv = argv.dup
+      @opts = { region: nil, verbose: false }
+      while argv.first&.start_with?("-")
+        case argv.shift
+        when "-v", "--version" then return out(VERSION)
+        when "-h", "--help" then return out(usage)
+        when "--verbose" then @opts[:verbose] = true
+        when "--region" then @opts[:region] = argv.shift
+        else return fail_with("unknown option. Run `shiftcare-toolkit help`.", 2)
+        end
+      end
+
+      command = argv.shift
+      command = "regions" if command == "status"
+      return help(*argv.first(2)) if command.nil? || command == "help"
+      return out(VERSION) if command == "version"
+      return fail_with("unknown command #{command}. Run `shiftcare-toolkit help`.", 2) unless COMMANDS.key?(command)
+
+      if command == "releases"
+        command = argv.shift
+        return out(releases_usage) if command.nil? || %w[help -h --help].include?(command)
+        unless RELEASE_COMMANDS.key?(command)
+          return fail_with("unknown command releases #{command}. Run `shiftcare-toolkit releases help`.", 2)
+        end
+      end
+
+      parser = parser_for(command)
+      args = parser.parse(argv)
+      return out(parser.help) if @opts[:help]
+
+      send("cmd_#{command}", args)
+    rescue OptionParser::ParseError => e
+      fail_with("#{e.message}. Run `shiftcare-toolkit #{RELEASE_COMMANDS.key?(command) ? "releases " : ""}#{command} --help`.", 2)
+    rescue Error, Client::Error, Config::Error, JSON::ParserError, SystemCallError => e
+      fail_with(e.message, 1)
+    rescue Interrupt
+      fail_with("interrupted", 130)
+    end
+
+    private
+
+    # ---- commands ----
+
+    def cmd_setup(args)
+      raise Error, "setup takes no arguments; pipe the token in with --token-stdin" if args.any?
+
+      region = @opts[:region]
+      unless region
+        @stderr.puts "Paste a token for each region (input is hidden), or press Enter to skip."
+        @stderr.puts "Create tokens in each region's admin console: Admin -> Admin API tokens."
+        config.regions.each { |r| setup_interactive(r) }
+        return out("Saved to #{config.path}")
+      end
+
+      config.set(region, url: @opts[:url]) if @opts[:url]
+      config.url(region) # fails early for a custom region without a URL
+      if @opts[:token_stdin]
+        token = @stdin.read.to_s.strip
+        raise Error, "no token on stdin" if token.empty?
+
+        verify(region, token)
+        config.set(region, token: token)
+        config.save
+        out("#{region}: token #{Config.mask(token)} verified and saved to #{config.path}")
+      elsif @opts[:url]
+        config.save
+        out("#{region}: URL #{config.url(region)} saved to #{config.path}")
+      else
+        setup_interactive(region)
+        0
+      end
+    end
+
+    def cmd_regions(_args)
+      rows = config.regions.map do |region|
+        url = begin
+          config.url(region)
+        rescue Config::Error
+          "-"
+        end
+        token = config.token(region)
+        [region, url, token ? "#{Config.mask(token)} (#{config.token_source(region)})" : "-", check(region, token)]
+      end
+      table(%w[REGION URL TOKEN CHECK], rows)
+      @stdout.puts "default region: #{config.default_region}"
+      0
+    end
+
+    def cmd_list(_args)
+      filters = { status: @opts[:status], visibility: @opts[:visibility] }
+      if @opts[:all]
+        releases = client(region).list_all(**filters)
+        total = releases.size
+      else
+        body = client(region).list(page: @opts[:page] || 1, **filters)
+        releases = body["data"]
+        meta = body["meta"]
+        total = meta["total"]
+      end
+      return out(JSON.pretty_generate(releases)) if @opts[:json]
+
+      table(%w[KEY STATUS VISIBILITY UPDATED_AT TITLE],
+            releases.map { |r| [r["key"], r["status"], r["visibility"], r["updated_at"], truncate(r["title"], 60)] })
+      if meta && meta["page"] * meta["per_page"] < total
+        @stdout.puts "page #{meta["page"]}, #{releases.size} of #{total}. Use --page N or --all for more."
+      end
+      0
+    end
+
+    def cmd_show(args)
+      release = client(region).get(one_key(args))
+      return out(JSON.pretty_generate(release)) if @opts[:json]
+
+      release.each do |field, value|
+        @stdout.puts "#{field}: #{value.is_a?(Array) || value.is_a?(Hash) ? JSON.generate(value) : value}"
+      end
+      0
+    end
+
+    def cmd_create(args)
+      raise Error, "create takes no arguments; put the key in the file" if args.any?
+      raise Error, "--file is required" unless @opts[:file]
+
+      fields = read_release_file(@opts[:file])
+      raise Error, "the file needs a \"key\"" if fields["key"].to_s.empty?
+
+      release = client(region).create(release_fields(fields).merge("key" => fields["key"]))
+      out("#{region}: created #{release["key"]} (#{release["status"]}, #{release["visibility"]})")
+    end
+
+    def cmd_update(args)
+      key = one_key(args)
+      fields = @opts[:file] ? release_fields(read_release_file(@opts[:file])) : {}
+      items = Hash.new { |h, k| h[k] = [] }
+      (@opts[:set] || []).each do |field, value|
+        fields[field] = ARRAY_FIELDS.include?(field) && !value.is_a?(Array) ? (items[field] << value) : value
+      end
+      raise Error, "nothing to update: pass --file or --set" if fields.empty?
+
+      release = client(region).update(key, fields)
+      out("#{region}: updated #{release["key"]}")
+    end
+
+    def cmd_copy(_args)
+      from = @opts[:from] || raise(Error, "--from is required")
+      targets = @opts[:to] || raise(Error, "--to is required")
+      raise Error, "--to must not include the source region #{from}" if targets.include?(from)
+
+      source = client(from)
+      releases = if @opts[:keys]
+                   @opts[:keys].map do |key|
+                     source.get(key)
+                   rescue Client::Error => e
+                     raise Error, "#{key}: #{e.message}"
+                   end
+                 else
+                   source.list_all
+                 end
+      @stdout.puts "#{@opts[:dry_run] ? "[dry run] " : ""}copying #{releases.size} release(s) from #{from} to #{targets.join(", ")}"
+
+      summaries = targets.map { |target| [target, copy_to(target, releases)] }
+      @stdout.puts
+      summaries.each do |target, c|
+        @stdout.puts "#{target}: created #{c[:created]}, updated #{c[:updated]}, skipped #{c[:skipped]}, failed #{c[:failed]}"
+      end
+      summaries.sum { |_, c| c[:failed] }.zero? ? 0 : 1
+    end
+
+    # ---- copy ----
+
+    def copy_to(target, releases)
+      counts = { created: 0, updated: 0, skipped: 0, failed: 0 }
+      existing = begin
+        client(target).list_all.to_h { |r| [r["key"], r] }
+      rescue Client::Error, Config::Error => e
+        @stderr.puts "#{target}: #{e.message}"
+        counts[:failed] = releases.size
+        return counts
+      end
+
+      releases.each do |release|
+        key = release["key"]
+        fields = release_fields(release)
+        current = existing[key]
+        if current.nil?
+          write(target, key, counts, :created, "create") { client(target).create(fields.merge("key" => key)) }
+        elsif !@opts[:update_existing]
+          skip(target, key, counts, "exists (use --update-existing to overwrite)")
+        elsif release_fields(current) == fields
+          skip(target, key, counts, "unchanged")
+        else
+          write(target, key, counts, :updated, "update") { client(target).update(key, fields) }
+        end
+      end
+      counts
+    end
+
+    def write(target, key, counts, result, verb)
+      if @opts[:dry_run]
+        @stdout.puts "  #{target} #{key}: would #{verb}"
+      else
+        yield
+        @stdout.puts "  #{target} #{key}: #{result}"
+      end
+      counts[result] += 1
+    rescue Client::Error => e
+      if e.status == 409
+        skip(target, key, counts, "not a hidden dev draft, edit it in the super admin console")
+      else
+        @stdout.puts "  #{target} #{key}: FAILED #{e.message}"
+        counts[:failed] += 1
+      end
+    end
+
+    def skip(target, key, counts, reason)
+      @stdout.puts "  #{target} #{key}: skipped, #{reason}"
+      counts[:skipped] += 1
+    end
+
+    # ---- helpers ----
+
+    def setup_interactive(region)
+      url = config.url(region)
+      loop do
+        current = config.token(region)
+        @stderr.print "#{region} (#{url}) token#{current ? " [current #{Config.mask(current)}]" : ""}: "
+        token = read_secret
+        if token.empty?
+          @stderr.puts "  #{region}: skipped"
+          return
+        end
+        begin
+          verify(region, token)
+          config.set(region, token: token)
+          config.save
+          @stderr.puts "  #{region}: ok, saved #{Config.mask(token)}"
+          return
+        rescue Client::Error => e
+          @stderr.puts "  #{e.message}. Not saved; try again or press Enter to skip."
+        end
+      end
+    end
+
+    def read_secret
+      line = @stdin.tty? && @stdin.respond_to?(:getpass) ? @stdin.getpass("") : @stdin.gets
+      line.to_s.strip
+    end
+
+    def verify(region, token)
+      @clients.delete(region)
+      build_client(region, token).list(page: 1)
+    end
+
+    def check(region, token)
+      return "no token" unless token
+
+      total = client(region).list(page: 1).dig("meta", "total")
+      "ok (#{total} releases)"
+    rescue Client::Error => e
+      e.status ? e.status.to_s : "unreachable"
+    rescue Config::Error
+      "no url"
+    end
+
+    def region
+      @opts[:region] || config.default_region
+    end
+
+    def client(region)
+      @clients[region] ||= build_client(region, config.token(region))
+    end
+
+    def build_client(region, token)
+      log = @opts[:verbose] ? ->(message) { @stderr.puts(message) } : nil
+      Client.new(base_url: config.url(region), token: token, region: region, http: @http,
+                 min_interval: @min_interval, sleeper: @sleeper, log: log)
+    end
+
+    def config
+      @config ||= Config.new
+    end
+
+    def one_key(args)
+      raise Error, "expected exactly one KEY" unless args.size == 1
+
+      args.first
+    end
+
+    # Accepts bare fields, {"product_release": {...}} or `show --json` output.
+    def read_release_file(path)
+      json = JSON.parse(path == "-" ? @stdin.read : File.read(path))
+      json = json["product_release"] || json["data"] || json if json.is_a?(Hash)
+      raise Error, "#{path} must hold a JSON object" unless json.is_a?(Hash)
+
+      json
+    end
+
+    # ponytail: nil fields are dropped, so copy never clears a field on the target.
+    def release_fields(release)
+      fields = release.slice(*Client::WRITABLE).compact
+      fields["links"] = fields["links"].map { |l| l.slice("label", "url") } if fields["links"].is_a?(Array)
+      fields
+    end
+
+    def parse_set(pair)
+      field, value = pair.split("=", 2)
+      raise OptionParser::InvalidArgument, "#{pair} (expected field=value)" if value.nil?
+      unless Client::WRITABLE.include?(field)
+        raise OptionParser::InvalidArgument, "#{field} (writable: #{Client::WRITABLE.join(", ")})"
+      end
+
+      [field, coerce(field, value)]
+    end
+
+    def coerce(field, value)
+      return value.empty? ? nil : Integer(value) if field == "video_duration_seconds"
+      return JSON.parse(value) if field == "links" || (ARRAY_FIELDS.include?(field) && value.start_with?("["))
+
+      value
+    rescue ArgumentError, JSON::ParserError
+      raise OptionParser::InvalidArgument, "#{field}=#{value}"
+    end
+
+    def table(headers, rows)
+      widths = headers.each_index.map { |i| ([headers[i]] + rows.map { |r| r[i].to_s }).map(&:length).max }
+      ([headers] + rows).each do |row|
+        @stdout.puts row.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ").rstrip
+      end
+    end
+
+    def truncate(text, max)
+      text = text.to_s
+      text.length > max ? "#{text[0, max - 1]}…" : text
+    end
+
+    def out(text)
+      @stdout.puts text
+      0
+    end
+
+    def fail_with(message, code)
+      @stderr.puts "error: #{message}"
+      code
+    end
+
+    def help(command = nil, sub = nil)
+      command = "regions" if command == "status"
+      return out(usage) unless command
+      return fail_with("unknown command #{command}", 2) unless COMMANDS.key?(command)
+      return out(parser_for(command).help) unless command == "releases"
+      return out(releases_usage) unless sub
+      return fail_with("unknown command releases #{sub}", 2) unless RELEASE_COMMANDS.key?(sub)
+
+      out(parser_for(sub).help)
+    end
+
+    def releases_usage
+      <<~TEXT
+        Usage: shiftcare-toolkit releases COMMAND [options]
+
+        Calls the internal Product Releases API (/internal/product_releases).
+
+        Commands:
+        #{RELEASE_COMMANDS.map { |name, text| "  #{name.ljust(9)} #{text}" }.join("\n")}
+
+        Help for one command: shiftcare-toolkit releases copy --help
+      TEXT
+    end
+
+    def usage
+      <<~TEXT
+        Usage: shiftcare-toolkit [--region R] [--verbose] COMMAND [options]
+
+        Internal ShiftCare tools. Region tokens (au, us, uk, ca or custom) are shared by every command.
+
+        Commands:
+        #{COMMANDS.map { |name, text| "  #{name.ljust(9)} #{text}" }.join("\n")}
+          help      Show help for a command: shiftcare-toolkit help releases copy
+
+        Global options:
+          --region R   Region to use (default from config, initially au)
+          --verbose    Log each request to stderr (tokens are never logged)
+          --version    Print the version
+
+        Start with: shiftcare-toolkit setup
+      TEXT
+    end
+
+    # ---- option parsers ----
+
+    def parser_for(command)
+      OptionParser.new do |o|
+        o.program_name = "shiftcare-toolkit"
+        o.require_exact = true # so --token is not read as --token-stdin
+        send("options_#{command}", o)
+        o.separator ""
+        o.separator "Common options:"
+        o.on("--region R", "Region (au, us, uk, ca or custom; default #{default_region_label})") { |v| @opts[:region] = v }
+        o.on("--verbose", "Log each request to stderr") { @opts[:verbose] = true }
+        o.on("-h", "--help", "Show this help") { @opts[:help] = true }
+      end
+    end
+
+    def default_region_label
+      config.default_region
+    rescue StandardError
+      "au"
+    end
+
+    def options_setup(o)
+      o.banner = "Usage: shiftcare-toolkit setup [--region R (--token-stdin | --url URL)]"
+      o.separator <<~TEXT
+
+        Saves one token per region to #{Config.default_path} (mode 0600), after
+        checking it against the API. With no --region it walks au, us, uk and ca and asks
+        for each token with hidden input; press Enter to skip a region.
+
+        A token works only in the region that issued it. Create one in each region's
+        admin console: Admin -> Admin API tokens, scope product_releases:write.
+
+        Examples:
+          shiftcare-toolkit setup
+          pbpaste | shiftcare-toolkit setup --region us --token-stdin
+          shiftcare-toolkit setup --region staging --url https://staging.example.com
+          shiftcare-toolkit setup --region staging --token-stdin < token.txt
+
+        Options:
+      TEXT
+      o.on("--token-stdin", "Read the token from stdin (tokens are never taken as arguments)") { @opts[:token_stdin] = true }
+      o.on("--url URL", "Base URL, for a custom region such as staging or local") { |v| @opts[:url] = v }
+    end
+
+    def options_regions(o)
+      o.banner = "Usage: shiftcare-toolkit regions"
+      o.separator <<~TEXT
+
+        Lists every region with its base URL, masked token and where it came from
+        (config or env), and a live check: ok, 401, 403 or unreachable.
+
+        Example:
+          shiftcare-toolkit regions
+      TEXT
+    end
+
+    def options_list(o)
+      o.banner = "Usage: shiftcare-toolkit releases list [--status S] [--visibility V] [--page N | --all] [--json]"
+      o.separator <<~TEXT
+
+        Examples:
+          shiftcare-toolkit releases list
+          shiftcare-toolkit releases list --region us --status dev --visibility hidden
+          shiftcare-toolkit releases list --all --json > au.json
+
+        Options:
+      TEXT
+      o.on("--status S", "Filter by status, e.g. dev, beta, live") { |v| @opts[:status] = v }
+      o.on("--visibility V", "Filter by visibility, e.g. hidden, public") { |v| @opts[:visibility] = v }
+      o.on("--page N", Integer, "Page to fetch (50 per page)") { |v| @opts[:page] = v }
+      o.on("--all", "Follow pagination and fetch every page") { @opts[:all] = true }
+      o.on("--json", "Print JSON instead of a table") { @opts[:json] = true }
+    end
+
+    def options_show(o)
+      o.banner = "Usage: shiftcare-toolkit releases show KEY [--json]"
+      o.separator <<~TEXT
+
+        Examples:
+          shiftcare-toolkit releases show shift_swaps
+          shiftcare-toolkit releases show shift_swaps --region uk --json
+
+        Options:
+      TEXT
+      o.on("--json", "Print JSON") { @opts[:json] = true }
+    end
+
+    def options_create(o)
+      o.banner = "Usage: shiftcare-toolkit releases create --file FILE"
+      o.separator <<~TEXT
+
+        Creates a release from a JSON object holding "key" plus writable fields:
+        #{Client::WRITABLE.join(", ")}.
+        New releases are always status dev and visibility hidden. 409 if the key exists.
+
+        Examples:
+          shiftcare-toolkit releases create --region au --file release.json
+          shiftcare-toolkit releases show shift_swaps --json | shiftcare-toolkit releases create --region us --file -
+
+        Options:
+      TEXT
+      o.on("--file FILE", "JSON file, or - for stdin") { |v| @opts[:file] = v }
+    end
+
+    def options_update(o)
+      o.banner = "Usage: shiftcare-toolkit releases update KEY (--file FILE | --set field=value ...)"
+      o.separator <<~TEXT
+
+        Updates writable fields of a hidden dev draft. 409 once it is published or visible.
+        Array fields (categories, change_items, flag_keys) take one item per --set, or a
+        JSON array. links takes a JSON array of {"label","url"}.
+
+        Examples:
+          shiftcare-toolkit releases update shift_swaps --set title="Shift swaps v2"
+          shiftcare-toolkit releases update shift_swaps --set change_items="Swap a shift" --set change_items="Approve a swap"
+          shiftcare-toolkit releases update shift_swaps --set 'links=[{"label":"Help","url":"https://help.shiftcare.com"}]'
+          shiftcare-toolkit releases update shift_swaps --region us --file patch.json
+
+        Options:
+      TEXT
+      o.on("--file FILE", "JSON file with fields to change, or - for stdin") { |v| @opts[:file] = v }
+      o.on("--set FIELD=VALUE", "Set one field (repeatable)") { |v| (@opts[:set] ||= []) << parse_set(v) }
+    end
+
+    def options_copy(o)
+      o.banner = "Usage: shiftcare-toolkit releases copy --from R --to R1,R2 [--key K ...] [--update-existing] [--dry-run]"
+      o.separator <<~TEXT
+
+        Copies releases (key + writable fields) from one region to others. Missing keys are
+        created as hidden dev drafts. Existing keys are skipped unless --update-existing,
+        which updates them; a target that is no longer a hidden draft (409) is reported and
+        skipped. Ends with a created/updated/skipped/failed summary per region and exits 1
+        if anything failed.
+
+        Examples:
+          shiftcare-toolkit releases copy --from au --to us,uk,ca --dry-run
+          shiftcare-toolkit releases copy --from au --to us,uk,ca --key shift_swaps --key rosters_v2
+          shiftcare-toolkit releases copy --from au --to us --update-existing
+
+        Options:
+      TEXT
+      o.on("--from R", "Source region") { |v| @opts[:from] = v }
+      o.on("--to R1,R2", Array, "Target regions, comma separated") { |v| @opts[:to] = v }
+      o.on("--key K", "Copy only this key (repeatable; default: every release)") { |v| (@opts[:keys] ||= []) << v }
+      o.on("--update-existing", "Update keys that already exist in the target") { @opts[:update_existing] = true }
+      o.on("--dry-run", "Show what would change without writing") { @opts[:dry_run] = true }
+    end
+  end
+end

data/lib/shiftcare_toolkit/client.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "version"
+
+module ShiftcareToolkit
+  # One region's /internal/product_releases API. `http` is any callable taking
+  # (uri, request) and returning something with #code, #body and #[] (header),
+  # so tests can pass a fake instead of Net::HTTP.
+  class Client
+    WRITABLE = %w[
+      title summary rich_body owner icon tone help_url video_url video_title
+      video_duration_seconds categories change_items flag_keys links
+    ].freeze
+    MAX_RETRIES = 5
+    NETWORK_ERRORS = [
+      SocketError, SystemCallError, IOError, Timeout::Error, OpenSSL::SSL::SSLError,
+    ].freeze
+
+    class Error < StandardError
+      attr_reader :status
+
+      def initialize(message, status: nil)
+        super(message)
+        @status = status
+      end
+    end
+
+    # min_interval keeps one client under the 60 req/min per-token limit.
+    def initialize(base_url:, token:, region: nil, http: nil, min_interval: 1.0, sleeper: ->(s) { sleep(s) }, log: nil)
+      @base_url = base_url.chomp("/")
+      @token = token
+      @region = region || base_url
+      @http = http || method(:net_http)
+      @min_interval = min_interval
+      @sleeper = sleeper
+      @log = log
+      @last_request_at = nil
+    end
+
+    def list(page: 1, status: nil, visibility: nil)
+      query = { page: page, status: status, visibility: visibility }.compact
+      request(:get, "/internal/product_releases?#{URI.encode_www_form(query)}")
+    end
+
+    def list_all(status: nil, visibility: nil)
+      releases = []
+      (1..).each do |page|
+        body = list(page: page, status: status, visibility: visibility)
+        releases.concat(body["data"])
+        meta = body["meta"]
+        break if body["data"].empty? || page * meta["per_page"] >= meta["total"]
+      end
+      releases
+    end
+
+    def get(key)
+      request(:get, path_for(key))["data"]
+    end
+
+    def create(attrs)
+      request(:post, "/internal/product_releases", { product_release: attrs })["data"]
+    end
+
+    def update(key, attrs)
+      request(:patch, path_for(key), { product_release: attrs })["data"]
+    end
+
+    private
+
+    def path_for(key)
+      "/internal/product_releases/#{URI.encode_www_form_component(key)}"
+    end
+
+    def request(verb, path, payload = nil)
+      raise Error, "no token for #{@region}: run `shiftcare-toolkit setup --region #{@region}`" if @token.to_s.empty?
+
+      uri = URI("#{@base_url}#{path}")
+      attempt = 0
+      loop do
+        response = perform(verb, uri, payload)
+        code = response.code.to_i
+        if code == 429 && attempt < MAX_RETRIES
+          attempt += 1
+          wait = retry_after(response, attempt)
+          @log&.call("#{@region}: rate limited, retry #{attempt}/#{MAX_RETRIES} in #{wait}s")
+          @sleeper.call(wait)
+          next
+        end
+        return parse(response.body) if code.between?(200, 299)
+
+        raise Error.new(error_message(code, response.body), status: code)
+      end
+    end
+
+    def perform(verb, uri, payload)
+      throttle
+      req = Net::HTTP.const_get(verb.capitalize).new(uri)
+      req["Authorization"] = "Bearer #{@token}"
+      req["User-Agent"] = "shiftcare-toolkit/#{VERSION}"
+      req["Accept"] = "application/json"
+      if payload
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(payload)
+      end
+      started = Time.now
+      response = @http.call(uri, req)
+      @log&.call("#{verb.upcase} #{uri} -> #{response.code} (#{((Time.now - started) * 1000).round}ms)")
+      response
+    rescue *NETWORK_ERRORS => e
+      raise Error, "#{@region} unreachable (#{uri.host}): #{e.class}: #{e.message}"
+    end
+
+    def throttle
+      if @last_request_at && @min_interval.positive?
+        wait = @min_interval - (Time.now - @last_request_at)
+        @sleeper.call(wait) if wait.positive?
+      end
+      @last_request_at = Time.now
+    end
+
+    # The API sends no Retry-After today; fall back to 5, 10, 20, 40, 60 s.
+    def retry_after(response, attempt)
+      header = response["Retry-After"].to_s
+      header.match?(/\A\d+\z/) ? header.to_i : [5 * (2**(attempt - 1)), 60].min
+    end
+
+    def parse(body)
+      body.to_s.empty? ? {} : JSON.parse(body)
+    rescue JSON::ParserError
+      raise Error, "#{@region}: response was not JSON"
+    end
+
+    def error_message(code, body)
+      detail = begin
+        json = JSON.parse(body.to_s)
+        json["error"] || Array(json["errors"]).join("; ")
+      rescue JSON::ParserError
+        nil
+      end
+      case code
+      when 401 then "#{@region}: 401 token rejected (bad, expired or revoked). Tokens work only in the region that issued them."
+      when 403
+        if detail.nil? && body.to_s.include?("1010")
+          "#{@region}: 403 blocked by Cloudflare (error 1010)"
+        else
+          "#{@region}: 403 #{detail || "forbidden"} (the token needs the product_releases:write scope)"
+        end
+      when 429 then "#{@region}: 429 still rate limited after #{MAX_RETRIES} retries"
+      else "#{@region}: #{code} #{detail.to_s.empty? ? "request failed" : detail}"
+      end
+    end
+
+    def net_http(uri, req)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
+        http.request(req)
+      end
+    end
+  end
+end

data/lib/shiftcare_toolkit/config.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module ShiftcareToolkit
+  # Per-region base URLs and tokens, stored in a 0600 YAML file:
+  #
+  #   default_region: au
+  #   regions:
+  #     au: { token: scadm_... }
+  #     staging: { url: https://staging.example.com, token: scadm_... }
+  class Config
+    REGIONS = {
+      "au" => "https://app.shiftcare.com",
+      "us" => "https://us.shiftcare.com",
+      "uk" => "https://uk.shiftcare.com",
+      "ca" => "https://ca.shiftcare.com",
+    }.freeze
+    REGION_FORMAT = /\A[a-z0-9_-]+\z/
+
+    class Error < StandardError; end
+
+    attr_reader :path
+
+    def self.default_path(env = ENV)
+      base = env["XDG_CONFIG_HOME"].to_s.empty? ? File.join(Dir.home, ".config") : env["XDG_CONFIG_HOME"]
+      File.join(base, "shiftcare-toolkit", "config.yml")
+    end
+
+    # Shows the prefix only, the part the admin console also shows.
+    def self.mask(token)
+      return "-" if token.to_s.empty?
+
+      "#{token[0, [12, token.length / 3].min]}…"
+    end
+
+    def initialize(path = self.class.default_path, env: ENV)
+      @path = path
+      @env = env
+      @data = File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
+      @data["regions"] ||= {}
+    end
+
+    def default_region
+      @data["default_region"] || "au"
+    end
+
+    # Built-in regions first, then custom ones from the file.
+    def regions
+      (REGIONS.keys + @data["regions"].keys).uniq
+    end
+
+    def url(region)
+      url = @data.dig("regions", region, "url") || REGIONS[region]
+      raise Error, "unknown region #{region}: run `shiftcare-toolkit setup --region #{region} --url URL`" unless url
+
+      url.chomp("/")
+    end
+
+    def token(region)
+      env_token(region) || @data.dig("regions", region, "token")
+    end
+
+    def token_source(region)
+      return "env" if env_token(region)
+
+      @data.dig("regions", region, "token") ? "config" : nil
+    end
+
+    def set(region, url: nil, token: nil)
+      raise Error, "bad region name #{region.inspect}: use lowercase letters, digits, - or _" unless region.match?(REGION_FORMAT)
+
+      entry = (@data["regions"][region] ||= {})
+      entry["url"] = url.chomp("/") if url
+      entry["token"] = token if token
+    end
+
+    def save
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      File.chmod(0o700, dir)
+      tmp = "#{path}.tmp"
+      File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(YAML.dump(@data)) }
+      File.chmod(0o600, tmp)
+      File.rename(tmp, path)
+    end
+
+    private
+
+    def env_token(region)
+      value = @env["SHIFTCARE_TOOLKIT_TOKEN_#{region.upcase.tr("-", "_")}"]
+      value unless value.to_s.empty?
+    end
+  end
+end

data/lib/shiftcare_toolkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ShiftcareToolkit
+  VERSION = "0.1.0"
+end

data/lib/shiftcare_toolkit.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "shiftcare_toolkit/version"
+require_relative "shiftcare_toolkit/config"
+require_relative "shiftcare_toolkit/client"
+require_relative "shiftcare_toolkit/cli"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: shiftcare-toolkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ShiftCare
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Internal ShiftCare tools. First tool: list, show, create, update and
+  copy product releases across the au, us, uk and ca regions.'
+email:
+executables:
+- shiftcare-toolkit
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- exe/shiftcare-toolkit
+- lib/shiftcare_toolkit.rb
+- lib/shiftcare_toolkit/cli.rb
+- lib/shiftcare_toolkit/client.rb
+- lib/shiftcare_toolkit/config.rb
+- lib/shiftcare_toolkit/version.rb
+homepage: https://github.com/shiftcare/shiftcare-toolkit
+licenses:
+- Nonstandard
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/shiftcare/shiftcare-toolkit
+  changelog_uri: https://github.com/shiftcare/shiftcare-toolkit/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Internal ShiftCare command-line tools
+test_files: []