kward 0.67.0 → 0.68.0

data/lib/kward/auth/anthropic_oauth.rb

@@ -0,0 +1,291 @@
+require "base64"
+require "digest"
+require "json"
+require "net/http"
+require "securerandom"
+require "socket"
+require "time"
+require "uri"
+require_relative "file"
+require_relative "../config_files"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # OAuth helper for Anthropic Claude Pro/Max subscription credentials.
+  class AnthropicOAuth
+    AUTHORIZE_URL = "https://claude.ai/oauth/authorize"
+    TOKEN_URL = URI("https://platform.claude.com/v1/oauth/token")
+    DEFAULT_PORT = 53_692
+    CALLBACK_PATH = "/callback"
+    DEFAULT_CLIENT_ID = Base64.decode64("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl")
+    SCOPE = "org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload"
+
+    attr_reader :auth_path
+
+    # Creates an object for Anthropic OAuth credentials.
+    def initialize(auth_path: AnthropicOAuth.default_auth_path, client_id: nil, config_path: ConfigFiles.config_path)
+      @auth_path = File.expand_path(auth_path)
+      @client_id = client_id
+      @config_path = File.expand_path(config_path)
+    end
+
+    def self.default_auth_path
+      File.expand_path(ENV["KWARD_ANTHROPIC_AUTH_PATH"] || "~/.kward/anthropic_auth.json")
+    end
+
+    def access_token
+      auth = current_auth
+      auth&.fetch("tokens", {})&.fetch("access_token", nil)
+    end
+
+    def logged_in?
+      !access_token.to_s.empty?
+    end
+
+    def login(prompt:, open_browser: true, timeout_seconds: 120)
+      flow = start_login_flow
+      pkce = flow[:pkce]
+      state = flow[:state]
+      server = flow[:server]
+      redirect_uri = flow[:redirect_uri]
+      url = flow[:authorization_url]
+
+      prompt.say("Anthropic login URL:\n#{url}\n")
+      prompt.say("Waiting for browser login. If it does not complete, paste the callback URL when prompted.")
+      browser_opened = open_browser && open_url(url)
+
+      code = wait_for_callback(server, expected_state: state, timeout_seconds: browser_opened ? timeout_seconds : 5)
+      unless code
+        input = prompt.ask("Paste callback URL or authorization code:")
+        code = authorization_code_from(input.to_s, expected_state: state)
+      end
+      raise "Missing authorization code" if code.to_s.empty?
+
+      complete_login_flow(code: code, redirect_uri: redirect_uri, code_verifier: pkce[:verifier])
+      auth_path
+    ensure
+      server&.close unless server&.closed?
+    end
+
+    def authorization_url(redirect_uri:, code_challenge:, state:)
+      query = URI.encode_www_form(
+        code: "true",
+        client_id: client_id,
+        response_type: "code",
+        redirect_uri: redirect_uri,
+        scope: SCOPE,
+        code_challenge: code_challenge,
+        code_challenge_method: "S256",
+        state: state
+      )
+      "#{AUTHORIZE_URL}?#{query}"
+    end
+
+    def start_login_flow
+      pkce = generate_pkce
+      state = pkce[:verifier]
+      server = start_callback_server
+      redirect_uri = "http://localhost:#{server.addr[1]}#{CALLBACK_PATH}"
+      {
+        pkce: pkce,
+        state: state,
+        server: server,
+        redirect_uri: redirect_uri,
+        authorization_url: authorization_url(redirect_uri: redirect_uri, code_challenge: pkce[:challenge], state: state)
+      }
+    end
+
+    def wait_for_login_callback(server, expected_state:, timeout_seconds:)
+      wait_for_callback(server, expected_state: expected_state, timeout_seconds: timeout_seconds)
+    end
+
+    def complete_login_flow(code:, redirect_uri:, code_verifier:)
+      tokens = exchange_code_for_tokens(code: code, redirect_uri: redirect_uri, code_verifier: code_verifier)
+      save_auth(tokens: tokens)
+      tokens
+    end
+
+    def authorization_code_from(input, expected_state: nil)
+      value = input.strip
+      return "" if value.empty?
+
+      uri = URI.parse(value)
+      params = URI.decode_www_form(uri.query.to_s).to_h
+      if params.key?("code")
+        raise "OAuth state mismatch" if expected_state && params["state"].to_s != expected_state.to_s
+
+        return params["code"]
+      end
+
+      if value.include?("#")
+        code, state = value.split("#", 2)
+        raise "OAuth state mismatch" if expected_state && !state.to_s.empty? && state != expected_state
+
+        return code
+      end
+
+      value
+    rescue URI::InvalidURIError
+      value
+    end
+
+    def save_auth(tokens: {})
+      data = {
+        "auth_mode" => "anthropic_oauth",
+        "tokens" => tokens,
+        "saved_at" => Time.now.utc.iso8601,
+        "expires_at" => expires_at_for(tokens)
+      }.compact
+
+      AuthFile.write_json(@auth_path, data)
+    end
+
+    # Performs refresh for Anthropic OAuth credentials.
+    def refresh!
+      auth = load_auth || raise("Anthropic OAuth login not found")
+      refresh_token = auth.fetch("tokens", {}).fetch("refresh_token", nil)
+      raise "Anthropic OAuth refresh token not found" if refresh_token.to_s.empty?
+
+      response = post_json(TOKEN_URL,
+        grant_type: "refresh_token",
+        client_id: client_id,
+        refresh_token: refresh_token)
+      refreshed = parse_successful_json(response, "Anthropic OAuth token refresh")
+      save_auth(tokens: auth.fetch("tokens", {}).merge(refreshed))
+      load_auth
+    end
+
+    private
+
+    def current_auth
+      auth = load_auth
+      tokens = auth&.fetch("tokens", {}) || {}
+      return nil if tokens.empty?
+
+      if token_expired?(auth) && !tokens["refresh_token"].to_s.empty?
+        auth = refresh!
+      end
+
+      auth
+    end
+
+    def load_auth
+      return nil unless File.exist?(@auth_path)
+
+      JSON.parse(File.read(@auth_path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def client_id
+      return @client_id unless @client_id.to_s.strip.empty?
+
+      value = ENV["ANTHROPIC_OAUTH_CLIENT_ID"].to_s.strip
+      return value unless value.empty?
+
+      value = ConfigFiles.config_value(ConfigFiles.read_config(@config_path), "anthropic_oauth_client_id")
+      return value unless value.to_s.empty?
+
+      DEFAULT_CLIENT_ID
+    end
+
+    def generate_pkce
+      verifier = random_urlsafe(64)
+      challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+      { verifier: verifier, challenge: challenge }
+    end
+
+    def random_urlsafe(bytes)
+      Base64.urlsafe_encode64(SecureRandom.random_bytes(bytes), padding: false)
+    end
+
+    def start_callback_server
+      TCPServer.new("localhost", Integer(ENV.fetch("KWARD_ANTHROPIC_OAUTH_PORT", DEFAULT_PORT)))
+    rescue Errno::EADDRINUSE
+      TCPServer.new("localhost", 0)
+    end
+
+    def wait_for_callback(server, expected_state:, timeout_seconds:)
+      ready = IO.select([server], nil, nil, timeout_seconds)
+      return nil unless ready
+
+      socket = server.accept
+      request_line = socket.gets.to_s
+      path = request_line.split[1].to_s
+      params = URI.decode_www_form(URI.parse(path).query.to_s).to_h
+
+      code = nil
+      status = "200 OK"
+      body = "Login complete. You can close this window."
+      if params["error"]
+        body = "Login failed. Return to the terminal."
+      elsif params["state"].to_s != expected_state.to_s
+        status = "400 Bad Request"
+        body = "Invalid OAuth state. Return to the terminal."
+      else
+        code = params["code"]
+      end
+
+      socket.write("HTTP/1.1 #{status}\r\nContent-Type: text/plain\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}")
+      code
+    rescue URI::InvalidURIError
+      nil
+    ensure
+      socket&.close
+    end
+
+    def exchange_code_for_tokens(code:, redirect_uri:, code_verifier:)
+      response = post_json(TOKEN_URL,
+        grant_type: "authorization_code",
+        client_id: client_id,
+        code: code,
+        redirect_uri: redirect_uri,
+        code_verifier: code_verifier)
+      parse_successful_json(response, "Anthropic OAuth token exchange")
+    end
+
+    def post_json(uri, params)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request.body = JSON.dump(params)
+
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
+    end
+
+    def token_expired?(auth)
+      expires_at = auth&.fetch("expires_at", nil)
+      return false unless expires_at
+
+      Time.parse(expires_at) <= Time.now.utc + 60
+    rescue ArgumentError
+      false
+    end
+
+    def expires_at_for(tokens)
+      expires_in = tokens["expires_in"] || tokens[:expires_in]
+      return tokens["expires_at"] || tokens[:expires_at] unless expires_in
+
+      (Time.now.utc + expires_in.to_i).iso8601
+    end
+
+    def parse_successful_json(response, label)
+      raise "#{label} failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise "#{label} returned invalid JSON"
+    end
+
+    def open_url(url)
+      command = if RUBY_PLATFORM.match?(/darwin/)
+                  "open"
+                elsif RUBY_PLATFORM.match?(/linux/)
+                  "xdg-open"
+                end
+      return false unless command
+
+      system(command, url, out: File::NULL, err: File::NULL)
+    end
+  end
+end

data/lib/kward/auth/file.rb

@@ -1,6 +1,8 @@
 require_relative "../private_file"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Shared private-file storage helpers for auth credentials.
   module AuthFile
     module_function
 

data/lib/kward/auth/github_oauth.rb

@@ -5,7 +5,9 @@ require "uri"
 require_relative "file"
 require_relative "../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # OAuth helper for GitHub Copilot credentials.
   class GithubOAuth
     DEVICE_CODE_URL = URI("https://github.com/login/device/code")
     TOKEN_URL = URI("https://github.com/login/oauth/access_token")
@@ -21,6 +23,7 @@ module Kward
 
     attr_reader :auth_path
 
+    # Creates an object for GitHub Copilot OAuth credentials.
     def initialize(auth_path: GithubOAuth.default_auth_path, config_path: ConfigFiles.config_path)
       @auth_path = File.expand_path(auth_path)
       @config_path = File.expand_path(config_path)

data/lib/kward/auth/openai_oauth.rb

@@ -8,7 +8,9 @@ require "time"
 require "uri"
 require_relative "file"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # OAuth helper for ChatGPT/OpenAI Codex credentials.
   class OpenAIOAuth
     ISSUER = "https://auth.openai.com"
     TOKEN_URL = URI("#{ISSUER}/oauth/token")
@@ -19,6 +21,7 @@ module Kward
 
     attr_reader :auth_path
 
+    # Creates an object for OpenAI OAuth credentials.
     def initialize(auth_path: OpenAIOAuth.default_auth_path, client_id: nil, config_path: OpenAIOAuth.default_config_path, issuer: ISSUER)
       @auth_path = File.expand_path(auth_path)
       @client_id = client_id
@@ -143,6 +146,7 @@ module Kward
       AuthFile.write_json(@auth_path, data)
     end
 
+    # Performs refresh for OpenAI OAuth credentials.
     def refresh!
       auth = load_auth || raise("OpenAI OAuth login not found")
       refresh_token = auth.fetch("tokens", {}).fetch("refresh_token", nil)

data/lib/kward/auth/openrouter_api_key.rb

@@ -1,7 +1,9 @@
 require_relative "../config_files"
 require_relative "openai_oauth"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Config helper for storing and removing OpenRouter API keys.
   class OpenRouterAPIKey
     attr_reader :config_path
 

data/lib/kward/cancellation.rb

@@ -1,7 +1,10 @@
 require "thread"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Cooperative cancellation token shared by model calls, tools, and workers.
   class Cancellation
+    # Cooperative cancellation token shared by model calls, tools, and workers.
     class CancelledError < StandardError; end
 
     def initialize

data/lib/kward/cli/auth_commands.rb

@@ -0,0 +1,82 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.
+  class CLI
+    # Login, logout, and credential-status commands mixed into the CLI frontend.
+    module AuthCommands
+      def handle_auth_command(arguments)
+        if help_option_arguments?(arguments)
+          print_command_help("auth")
+          return
+        end
+
+        case arguments
+        when ["status"]
+          print_auth_status
+        when ["logout"]
+          logout_auth
+        else
+          raise ArgumentError, command_usage("auth")
+        end
+      end
+
+      # Writes the auth status output for the terminal CLI flow.
+      def print_auth_status
+        config = safely_read_config.to_h
+        lines = ["#{colored("Auth Status", :green, :bold)}", ""]
+        lines << auth_status_line("OpenAI OAuth", File.exist?(OpenAIOAuth.default_auth_path), OpenAIOAuth.default_auth_path)
+        lines << auth_status_line("Anthropic OAuth", File.exist?(AnthropicOAuth.default_auth_path), AnthropicOAuth.default_auth_path)
+        lines << auth_status_line("GitHub OAuth", File.exist?(GithubOAuth.default_auth_path), GithubOAuth.default_auth_path)
+        lines << auth_status_line("OpenRouter API key", !config["openrouter_api_key"].to_s.empty? || !ENV["OPENROUTER_API_KEY"].to_s.empty?, ConfigFiles.config_path)
+        @prompt.say lines.join("\n")
+      end
+
+      def auth_status_line(label, configured, location)
+        status = configured ? :ok : :warning
+        message = configured ? "configured" : "not configured"
+        "#{doctor_mark(status)} #{label}: #{message} (#{location})"
+      end
+
+      def logout_auth
+        removed = []
+        [OpenAIOAuth.default_auth_path, AnthropicOAuth.default_auth_path, GithubOAuth.default_auth_path].each do |path|
+          next unless File.exist?(path)
+
+          File.delete(path)
+          removed << path
+        end
+        removed << "OpenRouter API key" if OpenRouterAPIKey.new.logout
+
+        if removed.empty?
+          @prompt.say "No saved credentials found."
+        else
+          @prompt.say "Removed #{removed.length} saved credential#{removed.length == 1 ? "" : "s"}."
+        end
+      end
+
+      def login(provider: nil, oauth: nil)
+        provider = provider.to_s.downcase
+        if provider == "openrouter"
+          auth = oauth || OpenRouterAPIKey.new
+          path = auth.login(prompt: @prompt)
+          @prompt.say("#{colored("Saved", :green, :bold)} OpenRouter API key to #{path}")
+          return
+        end
+
+        oauth ||= case provider
+                  when "github" then GithubOAuth.new
+                  when "anthropic", "claude" then AnthropicOAuth.new
+                  else OpenAIOAuth.new
+                  end
+        path = oauth.login(prompt: @prompt)
+        name = case provider
+               when "github" then "GitHub"
+               when "anthropic", "claude" then "Anthropic"
+               else "OpenAI"
+               end
+        @prompt.say("#{colored("Saved", :green, :bold)} #{name} OAuth login to #{path}")
+      end
+
+    end
+  end
+end

data/lib/kward/cli/commands.rb

@@ -0,0 +1,222 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.
+  class CLI
+    # Top-level command help, option parsing, and command dispatch helpers mixed into the CLI frontend.
+    module Commands
+      private
+
+      def help_command?
+        ["help", "--help", "-h"].include?(@argv.first) && @argv.length <= 2
+      end
+
+      def version_command?
+        ["version", "--version", "-v"].include?(@argv.first) && @argv.length == 1
+      end
+
+      def help_option_arguments?(arguments)
+        arguments.length == 1 && ["help", "--help", "-h"].include?(arguments.first)
+      end
+
+      def one_shot_prompt_argument
+        prompt = @argv.join(" ").strip
+        prompt.empty? ? nil : prompt
+      end
+
+      # Writes the command help output for the terminal CLI flow.
+      def print_command_help(command_name = nil)
+        if command_name.to_s.empty? || ["--help", "-h"].include?(command_name)
+          print_help
+          return
+        end
+
+        help = command_help[command_name]
+        raise ArgumentError, "Unknown command: #{command_name}" unless help
+
+        @prompt.say render_command_help(command_name, help)
+      end
+
+      # Writes the help output for the terminal CLI flow.
+      def print_help
+        command = ->(text) { colored(text, :green, :bold) }
+        option = ->(text) { colored(text, :cyan) }
+        heading = ->(text) { colored(text, :blue, :bold) }
+
+        @prompt.say <<~HELP.rstrip
+          #{colored("Kward", :green, :bold)} - an extendable CLI coding agent
+
+          #{heading.call("Usage")}
+            #{command.call("kward")}                              Start an interactive chat
+            #{command.call("kward")} #{option.call('"Explain this project"')}       Run a one-shot prompt
+            #{command.call("kward login")}                        Sign in or save provider credentials
+            #{command.call("kward auth status")}                  Show saved credential status
+            #{command.call("kward init")}                         Install starter prompts and AGENTS.md
+            #{command.call("kward doctor")}                       Check local Kward setup
+            #{command.call("kward pan")}                          Start Pan mode web UI
+            #{command.call("kward rpc")}                          Start the experimental JSON-RPC backend
+
+          #{heading.call("Commands")}
+            #{command.call("help")}                               Show this help
+            #{command.call("version")}                            Show the installed Kward version
+            #{command.call("login")} [anthropic|openrouter|github] Sign in with OpenAI, Anthropic, OpenRouter, or GitHub
+            #{command.call("auth status|logout")}                 Show or clear saved credentials
+            #{command.call("init")}                               Install starter prompts and AGENTS.md
+            #{command.call("doctor")}                             Check local Kward setup
+            #{command.call("stats tokens")} [range] [options]      Export local token telemetry as CSV
+            #{command.call("pan")}                                Start Pan mode web UI
+            #{command.call("rpc")}                                Run the JSON-RPC backend for UI clients
+
+          #{heading.call("Options")}
+            #{option.call("--working-directory=PATH")}             Run Kward from PATH
+            #{option.call("--help")}, #{option.call("-h")}                         Show this help
+            #{option.call("--version")}, #{option.call("-v")}                      Show the installed version
+
+          #{heading.call("Examples")}
+            #{command.call("kward")}
+            #{command.call("kward")} #{option.call('"Review this diff"')}
+            #{command.call("git diff | kward")} #{option.call('"Review this diff"')}
+            #{command.call("kward login openrouter")}
+            #{command.call("kward stats tokens today --bucket hour")}
+
+          Command names take precedence. Anything else is sent as a one-shot prompt.
+        HELP
+      end
+
+      def command_help
+        {
+          "help" => {
+            usage: "kward help [command]",
+            description: "Show the top-level command overview or help for one command.",
+            examples: ["kward help", "kward help pan"]
+          },
+          "version" => {
+            usage: "kward version",
+            description: "Show the installed Kward version.",
+            examples: ["kward version", "kward --version"]
+          },
+          "login" => {
+            usage: "kward login [anthropic|openrouter|github]",
+            description: "Sign in with OpenAI, Anthropic, OpenRouter, or GitHub.",
+            examples: ["kward login", "kward login anthropic", "kward login openrouter", "kward login github"]
+          },
+          "auth" => {
+            usage: "kward auth status|logout",
+            description: "Show or clear saved provider credentials without printing secrets.",
+            examples: ["kward auth status", "kward auth logout"]
+          },
+          "init" => {
+            usage: "kward init",
+            description: "Install starter prompts and base AGENTS.md into your config directory.",
+            examples: ["kward init"]
+          },
+          "doctor" => {
+            usage: "kward doctor",
+            description: "Check local Kward configuration, workspace, auth hints, and writable directories.",
+            examples: ["kward doctor", "kward --working-directory ~/code/project doctor"]
+          },
+          "stats" => {
+            usage: "kward stats tokens [range] [--bucket second|minute|hour|day|week|month|year] [--output path]",
+            description: "Export local token telemetry as CSV.",
+            examples: ["kward stats tokens today", "kward stats tokens today --bucket hour", "kward stats tokens week --output tokens.csv"]
+          },
+          "pan" => {
+            usage: "kward pan",
+            description: "Start Pan mode, a minimal LAN web UI with a prompt textarea and transcript.",
+            examples: ["kward pan", "kward --working-directory ~/code/project pan"]
+          },
+          "rpc" => {
+            usage: "kward rpc",
+            description: "Start the experimental JSON-RPC backend for UI clients.",
+            examples: ["kward rpc", "kward --working-directory ~/code/project rpc"]
+          }
+        }
+      end
+
+      def render_command_help(name, help)
+        heading = ->(text) { colored(text, :blue, :bold) }
+        command = ->(text) { colored(text, :green, :bold) }
+
+        lines = [
+          "#{command.call(name)} - #{help.fetch(:description)}",
+          "",
+          heading.call("Usage"),
+          "  #{command.call(help.fetch(:usage))}"
+        ]
+        examples = help.fetch(:examples, [])
+        if examples.any?
+          lines << ""
+          lines << heading.call("Examples")
+          examples.each { |example| lines << "  #{command.call(example)}" }
+        end
+        lines.join("\n")
+      end
+
+      def command_usage(name)
+        "Usage: #{command_help.fetch(name).fetch(:usage)}"
+      end
+
+      # Writes the version output for the terminal CLI flow.
+      def print_version
+        @prompt.say "kward #{VERSION}"
+      end
+
+      def install_starter_pack
+        result = StarterPackInstaller.install
+        installed_count = result.installed.length
+        skipped_count = result.skipped.length
+        @prompt.say("Installed #{installed_count} starter pack file#{installed_count == 1 ? "" : "s"}.")
+        @prompt.say("Skipped #{skipped_count} existing starter pack file#{skipped_count == 1 ? "" : "s"}.") if skipped_count.positive?
+      rescue StandardError => e
+        warn "Failed to install starter pack: #{e.message}"
+        exit 1
+      end
+
+      def pan_mode?
+        @argv.first == "pan"
+      end
+
+      def extract_global_options(arguments)
+        remaining = []
+        index = 0
+        while index < arguments.length
+          argument = arguments[index]
+          case argument
+          when "--"
+            @prompt_delimited = true
+            remaining.concat(arguments[(index + 1)..] || [])
+            break
+          when "--working-directory"
+            index += 1
+            raise ArgumentError, "Missing value for --working-directory" if index >= arguments.length
+
+            @working_directory = expanded_working_directory(arguments[index])
+          when /\A--working-directory=(.*)\z/
+            @working_directory = expanded_working_directory(Regexp.last_match(1))
+          else
+            remaining << argument
+          end
+          index += 1
+        end
+        remaining
+      end
+
+      def expanded_working_directory(path)
+        value = path.to_s.strip
+        raise ArgumentError, "Missing value for --working-directory" if value.empty?
+
+        expanded = File.expand_path(value)
+        raise ArgumentError, "Working directory does not exist: #{expanded}" unless Dir.exist?(expanded)
+        raise ArgumentError, "Working directory is not a directory: #{expanded}" unless File.directory?(expanded)
+
+        expanded
+      end
+
+      def with_working_directory
+        return yield unless @working_directory
+
+        Dir.chdir(@working_directory) { yield }
+      end
+
+    end
+  end
+end