fizzy-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f3929ca84a2457054103a3f63addd79d594e2a1b10c35335a0de3ec0255144b
+  data.tar.gz: ed75704d968deb083d4535ce85d6f68827877e65bc735b36c23ac22f0b7f01dc
+SHA512:
+  metadata.gz: 5dd289c5a61f833fb5f90f6efa6a2bbf9d7532f5a6650157debaa918347e94bc9336490dd352a3d9985fa7a875b2730a74a3ee291444b09035220a48365d489a
+  data.tar.gz: 3bf5e77238da1f4f1d49dfb4d74874ab7305be00bf6478ad3e0b2090145d2259922ca928548d58af9fa5325db2295255f2dac3e073eb4590a19c624cba0ecc1c

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2025-02-21
+
+### Added
+- Initial release
+- Board, card, column, step, comment, reaction, tag, user, notification, and pin management
+- Thor-based CLI with subcommands
+- Token auth with multi-account support (`--account`)
+- JSON output mode (`--json`) for all commands
+- Link-header pagination support
+- Table, detail, and JSON output formatters

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 David Paluy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+# Fizzy CLI
+
+A Ruby command-line client for [Fizzy](https://fizzy.do) project management.
+
+[![Gem Version](https://badge.fury.io/rb/fizzy-cli.svg)](https://badge.fury.io/rb/fizzy-cli)
+[![CI](https://github.com/dpaluy/fizzy-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/fizzy-cli/actions/workflows/ci.yml)
+
+## Install
+
+Requires Ruby >= 3.2.
+
+```sh
+gem install fizzy
+```
+
+## Authentication
+
+### Getting a Personal Access Token
+
+1. Log in to [app.fizzy.do](https://app.fizzy.do)
+2. Open your profile settings (click your avatar)
+3. Scroll to the **Developer** section
+4. Click **personal access tokens**
+5. Create a new token and copy it
+
+![Fizzy Developer Settings](fizzy-token.png)
+
+### Logging in
+
+```sh
+fizzy auth login --token YOUR_TOKEN
+```
+
+Tokens are stored at `~/.config/fizzy-cli/tokens.json`. You can also set `FIZZY_TOKEN` as an environment variable with `--account` to skip the file.
+
+```sh
+fizzy auth status     # Show current auth
+fizzy auth accounts   # List available accounts
+fizzy auth switch SLUG  # Change default account
+```
+
+## Usage
+
+All commands support `--json` for JSON output and `--account SLUG` to override the default account.
+
+### Boards
+
+```sh
+fizzy boards list
+fizzy boards get BOARD_ID
+fizzy boards create "My Board"
+fizzy boards update BOARD_ID --name "New Name"
+fizzy boards delete BOARD_ID
+```
+
+### Cards
+
+Cards are addressed by number (not ID).
+
+```sh
+fizzy cards list
+fizzy cards list --board BOARD_ID --status open
+fizzy cards get 42
+fizzy cards create "Card title" --board BOARD_ID
+fizzy cards update 42 --title "New title"
+fizzy cards delete 42
+```
+
+Card actions:
+
+```sh
+fizzy cards close 42
+fizzy cards reopen 42
+fizzy cards not-now 42
+fizzy cards triage 42 --column COLUMN_ID
+fizzy cards untriage 42
+fizzy cards tag 42 "bug"
+fizzy cards assign 42 USER_ID
+fizzy cards watch 42
+fizzy cards unwatch 42
+fizzy cards golden 42
+fizzy cards ungolden 42
+```
+
+### Columns
+
+Columns are scoped to a board.
+
+```sh
+fizzy columns list --board BOARD_ID
+fizzy columns get COLUMN_ID --board BOARD_ID
+fizzy columns create "To Do" --board BOARD_ID
+fizzy columns update COLUMN_ID --board BOARD_ID --name "Done"
+fizzy columns delete COLUMN_ID --board BOARD_ID
+```
+
+### Steps
+
+Steps are scoped to a card (no list endpoint; steps appear in `cards get`).
+
+```sh
+fizzy steps create "Write tests" --card 42
+fizzy steps get STEP_ID --card 42
+fizzy steps update STEP_ID --card 42 --completed
+fizzy steps delete STEP_ID --card 42
+```
+
+### Comments
+
+```sh
+fizzy comments list --card 42
+fizzy comments get COMMENT_ID --card 42
+fizzy comments create "Looks good" --card 42
+fizzy comments update COMMENT_ID --card 42 --body "Updated"
+fizzy comments delete COMMENT_ID --card 42
+```
+
+### Reactions
+
+Works on cards and comments.
+
+```sh
+fizzy reactions list --card 42
+fizzy reactions list --card 42 --comment COMMENT_ID
+fizzy reactions create "thumbsup" --card 42
+fizzy reactions delete REACTION_ID --card 42
+```
+
+### Tags, Users, Notifications, Pins
+
+```sh
+fizzy tags list
+fizzy users list
+fizzy users get USER_ID
+fizzy notifications list
+fizzy notifications read NOTIFICATION_ID
+fizzy notifications mark-all-read
+fizzy pins pin 42
+fizzy pins unpin 42
+```
+
+### Other
+
+```sh
+fizzy identity   # Show accounts and user info
+fizzy version    # Print version
+fizzy help       # List all commands
+```
+
+## Error Handling
+
+```ruby
+begin
+  # any fizzy command
+rescue Fizzy::AuthError => e
+  # 401 - invalid or expired token
+rescue Fizzy::ForbiddenError => e
+  # 403 - insufficient permissions
+rescue Fizzy::NotFoundError => e
+  # 404 - resource not found
+rescue Fizzy::ValidationError => e
+  # 422 - invalid input
+rescue Fizzy::RateLimitError => e
+  # 429 - too many requests, retry with backoff
+rescue Fizzy::ServerError => e
+  # 500+ - server error
+rescue Fizzy::NetworkError => e
+  # Timeout or connection failure
+end
+```
+
+## Configuration
+
+| Source | Purpose |
+|--------|---------|
+| `~/.config/fizzy-cli/tokens.json` | Stored auth tokens and default account |
+| `FIZZY_TOKEN` env var | Token override (requires `--account`) |
+
+## Development
+
+```
+bundle install
+bundle exec rake        # runs tests + rubocop
+bundle exec rake test   # tests only
+bundle exec rubocop     # lint only
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/fizzy-cli.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/fizzy

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/fizzy"
+
+begin
+  Fizzy::CLI.start(ARGV)
+rescue Fizzy::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue Interrupt
+  exit 130
+end

data/lib/fizzy/auth.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Fizzy
+  class Auth
+    CONFIG_DIR = File.expand_path("~/.config/fizzy-cli")
+    TOKEN_FILE = File.join(CONFIG_DIR, "tokens.json")
+
+    def self.resolve(account_slug = nil)
+      if ENV["FIZZY_TOKEN"]
+        raise AuthError, "--account required with FIZZY_TOKEN" unless account_slug
+
+        return { "access_token" => ENV["FIZZY_TOKEN"], "account_slug" => normalize_slug(account_slug) }
+      end
+
+      resolve_from_file(account_slug)
+    end
+
+    def self.normalize_slug(slug)
+      slug&.delete_prefix("/")
+    end
+
+    def self.resolve_from_file(account_slug)
+      unless File.exist?(TOKEN_FILE)
+        raise AuthError,
+              "No tokens file at #{TOKEN_FILE}. Run: fizzy auth login --token TOKEN"
+      end
+
+      data = JSON.parse(File.read(TOKEN_FILE))
+      slug = normalize_slug(account_slug || data["default_account"])
+      account = data["accounts"]&.find { |a| normalize_slug(a["account_slug"]) == slug }
+      raise AuthError, "No account found for #{slug}" unless account
+
+      account
+    end
+    private_class_method :resolve_from_file
+  end
+end

data/lib/fizzy/cli/auth.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Fizzy
+  class CLI < Thor
+    class AuthCommands < Thor
+      include Base
+
+      namespace "auth"
+
+      desc "identity", "Show current identity"
+      def identity
+        resp = client.get("/my/identity")
+        if json?
+          Formatter.json(resp.body)
+        else
+          resp.body["accounts"].each do |a|
+            puts "#{a["name"]} (#{a["slug"]})"
+            puts "  #{a["user"]["name"]} <#{a["user"]["email_address"]}> — #{a["user"]["role"]}"
+          end
+        end
+      end
+
+      desc "login", "Authenticate with a Personal Access Token"
+      option :token, required: true, desc: "Personal Access Token"
+      def login
+        token = options[:token]
+
+        # Verify token by fetching identity
+        c = Client.new(token: token, account_slug: "")
+        resp = c.get("/my/identity")
+        accounts = resp.body["accounts"]
+
+        raise AuthError, "No accounts found for this token" if accounts.empty?
+
+        # Build tokens data
+        token_accounts = accounts.map do |a|
+          {
+            "account_slug" => a["slug"],
+            "account_name" => a["name"],
+            "account_id" => a["id"],
+            "access_token" => token,
+            "user" => {
+              "id" => a["user"]["id"],
+              "name" => a["user"]["name"],
+              "email_address" => a["user"]["email_address"],
+              "role" => a["user"]["role"]
+            },
+            "created_at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+          }
+        end
+
+        data = {
+          "accounts" => token_accounts,
+          "default_account" => accounts.first["slug"]
+        }
+
+        FileUtils.mkdir_p(Auth::CONFIG_DIR)
+        File.write(Auth::TOKEN_FILE, JSON.pretty_generate(data))
+        File.chmod(0o600, Auth::TOKEN_FILE)
+
+        puts "Authenticated as #{accounts.first.dig("user", "name")}"
+        accounts.each do |a|
+          marker = a["slug"] == data["default_account"] ? " (default)" : ""
+          puts "  #{a["name"]} (#{a["slug"]})#{marker}"
+        end
+      end
+
+      desc "status", "Show current auth status"
+      def status
+        acct = Auth.resolve
+        c = Client.new(token: acct["access_token"], account_slug: acct["account_slug"])
+        resp = c.get("/my/identity")
+
+        puts "Token: #{Auth::TOKEN_FILE}"
+        puts "Account: #{acct["account_name"]} (#{acct["account_slug"]})"
+        puts "User: #{acct.dig("user", "name")} <#{acct.dig("user", "email_address")}>"
+
+        accounts_count = resp.body["accounts"].size
+        puts "Accounts: #{accounts_count}" if accounts_count > 1
+      rescue Fizzy::AuthError => e
+        puts "Not authenticated: #{e.message}"
+      end
+
+      desc "accounts", "List available accounts"
+      def accounts
+        data = JSON.parse(File.read(Auth::TOKEN_FILE))
+        data["accounts"].each do |a|
+          marker = a["account_slug"] == data["default_account"] ? " *" : ""
+          puts "#{a["account_name"]} (#{a["account_slug"]})#{marker}"
+          puts "  #{a.dig("user", "name")} <#{a.dig("user", "email_address")}>"
+        end
+      end
+
+      desc "switch ACCOUNT_SLUG", "Set default account"
+      def switch(account_slug)
+        data = JSON.parse(File.read(Auth::TOKEN_FILE))
+        normalized = Auth.normalize_slug(account_slug)
+        account = data["accounts"].find { |a| Auth.normalize_slug(a["account_slug"]) == normalized }
+        raise AuthError, "No account found for #{account_slug}" unless account
+
+        data["default_account"] = normalized
+        File.write(Auth::TOKEN_FILE, JSON.pretty_generate(data))
+
+        puts "Switched to #{account["account_name"]} (#{normalized})"
+      end
+    end
+  end
+end

data/lib/fizzy/cli/base.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Fizzy
+  class CLI < Thor
+    module Base
+      def self.included(base)
+        base.class_eval do
+          def self.exit_on_failure? = true
+        end
+      end
+
+      private
+
+      def global_options
+        parent_options || options
+      end
+
+      def account
+        @account ||= Auth.resolve(global_options[:account])
+      end
+
+      def client
+        @client ||= Client.new(
+          token: account["access_token"],
+          account_slug: account["account_slug"]
+        )
+      end
+
+      def slug
+        "/#{client.account_slug}"
+      end
+
+      def paginator
+        @paginator ||= Paginator.new(client)
+      end
+
+      def json?
+        global_options[:json]
+      end
+
+      def build_body(*keys)
+        keys.each_with_object({}) do |key, body|
+          val = options[key]
+          body[key] = val unless val.nil?
+        end
+      end
+
+      def output_list(data, headers:, &row_mapper)
+        if json?
+          Formatter.json(data)
+        else
+          rows = Array(data).map(&row_mapper)
+          Formatter.table(rows, headers: headers)
+        end
+      end
+
+      def output_detail(data, pairs:)
+        if json?
+          Formatter.json(data)
+        else
+          Formatter.detail(pairs)
+        end
+      end
+    end
+  end
+end

data/lib/fizzy/cli/boards.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Fizzy
+  class CLI < Thor
+    class Boards < Thor
+      include Base
+
+      desc "list", "List all boards"
+      def list
+        data = paginator.all("#{slug}/boards")
+        output_list(data, headers: %w[ID Name Cards Columns]) do |b|
+          [b["id"], b["name"], b["open_cards_count"], b["columns_count"]]
+        end
+      end
+
+      desc "get BOARD_ID", "Show a board"
+      def get(board_id)
+        resp = client.get("#{slug}/boards/#{board_id}")
+        b = resp.body
+        output_detail(b, pairs: [
+                        ["ID", b["id"]],
+                        ["Name", b["name"]],
+                        ["Open cards", b["open_cards_count"]],
+                        ["Columns", b["columns_count"]],
+                        ["Created", b["created_at"]]
+                      ])
+      end
+
+      desc "create NAME", "Create a board"
+      def create(name)
+        resp = client.post("#{slug}/boards", body: { name: name })
+        b = resp.body
+        output_detail(b, pairs: [
+                        ["ID", b["id"]],
+                        ["Name", b["name"]]
+                      ])
+      end
+
+      desc "update BOARD_ID", "Update a board"
+      option :name, required: true, desc: "New board name"
+      def update(board_id)
+        resp = client.put("#{slug}/boards/#{board_id}", body: { name: options[:name] })
+        b = resp.body
+        output_detail(b, pairs: [
+                        ["ID", b["id"]],
+                        ["Name", b["name"]]
+                      ])
+      end
+
+      desc "delete BOARD_ID", "Delete a board"
+      def delete(board_id)
+        client.delete("#{slug}/boards/#{board_id}")
+        puts "Board #{board_id} deleted."
+      end
+    end
+  end
+end