shapeup-cli 0.6.0 → 0.8.0

data/lib/shapeup_cli/commands/login.rb

@@ -4,70 +4,108 @@ module ShapeupCli
   module Commands
     class Login
       def self.run(args)
-        host = nil
-        profile_name = nil
+        new(args).run
+      end
+
+      def initialize(args)
+        @host = Config.host
+        @profile_name = nil
+        @requested_org = nil
+        @token = nil
+
         args.each_with_index do |arg, i|
           case arg
-          when "--host" then host = args[i + 1]
-          when /\A--host=(.+)\z/ then host = $1
-          when "--profile" then profile_name = args[i + 1]
-          when /\A--profile=(.+)\z/ then profile_name = $1
+          when "--host" then @host = args[i + 1]
+          when /\A--host=(.+)\z/ then @host = $1
+          when "--profile" then @profile_name = args[i + 1]
+          when /\A--profile=(.+)\z/ then @profile_name = $1
+          when "--org" then @requested_org = args[i + 1]
+          when /\A--org=(.+)\z/ then @requested_org = $1
+          when "--token" then @token = args[i + 1]
+          when /\A--token=(.+)\z/ then @token = $1
           end
         end
+      end
 
-        host ||= Config.host
-        token_response = ShapeupCli::Auth.login(host: host)
-        token = token_response["access_token"]
+      def run
+        token = @token || ShapeupCli::Auth.login(host: @host)["access_token"]
+        orgs = fetch_organisations(token)
+        org = choose_organisation(orgs)
 
-        # Fetch orgs to let user pick one for this profile
-        client = Client.new(host: host, token: token)
-        result = client.call_tool("list_organisations")
-        data = Output.extract_data(result)
-        orgs = data.is_a?(Hash) ? (data["organisations"] || []) : []
+        profile_name = @profile_name || agent_name(token, org) || (org ? slug(org["name"]) : slug(URI.parse(@host).host))
+        Config.save_profile(profile_name, token: token, host: @host, organisation_id: org&.dig("id"), display_name: org&.dig("name") || profile_name)
 
-        if orgs.empty?
-          puts "No organisations found."
+        if @token && org
+          puts "\nProfile '#{profile_name}' saved. Your default profile is unchanged."
+          puts "  org: #{org["name"]} (#{org["id"]})"
+          puts "  host: #{@host}"
+          puts "\nUse it with: SHAPEUP_PROFILE=#{profile_name} shapeup me"
           return
         end
 
-        # If only one org, use it automatically
-        org = if orgs.length == 1
-          orgs.first
+        Config.switch_profile(profile_name)
+
+        if org
+          puts "\nProfile '#{profile_name}' created and set as default."
+          puts "  org: #{org["name"]} (#{org["id"]})"
+          puts "  host: #{@host}"
+          puts "\nTo add another profile, run 'shapeup login' again."
+          puts "To switch: 'shapeup auth switch <name>'"
         else
-          puts "\nChoose an organisation for this profile:\n"
-          orgs.each_with_index do |o, i|
-            puts "  #{i + 1}) #{o["name"]}"
+          puts "\nSigned in and saved to profile '#{profile_name}', but no organisation is set yet."
+          puts "Choose one with: shapeup config set org <name>"
+          list_organisations(orgs)
+          exit EXIT_USAGE if @requested_org
+        end
+      end
+
+      private
+        def fetch_organisations(token)
+          result = Client.new(host: @host, token: token).call_tool("list_organisations")
+          data = Output.extract_data(result)
+          data.is_a?(Hash) ? (data["organisations"] || []) : []
+        end
+
+        def agent_name(token, org)
+          return unless @token && org
+
+          data = Output.extract_data(Client.new(host: @host, token: token).call_tool("list_inbox", organisation: org["id"].to_s))
+          data.dig("agent", "name") if data.is_a?(Hash)
+        rescue Client::ApiError
+          nil
+        end
+
+        def choose_organisation(orgs)
+          if @requested_org
+            find_organisation(orgs, @requested_org)
+          elsif orgs.length == 1
+            orgs.first
+          elsif orgs.any? && $stdin.tty?
+            prompt_for_organisation(orgs)
+          end
+        end
+
+        def find_organisation(orgs, value)
+          orgs.find { |o| o["id"].to_s == value.to_s || o["name"].casecmp?(value) }.tap do |org|
+            $stderr.puts "Organisation '#{value}' not found." unless org
           end
+        end
+
+        def prompt_for_organisation(orgs)
+          puts "\nChoose an organisation for this profile:\n"
+          list_organisations(orgs)
           print "\nEnter number (1-#{orgs.length}): "
           choice = $stdin.gets&.strip&.to_i
           orgs[choice - 1] if choice&.between?(1, orgs.length)
         end
 
-        unless org
-          puts "No organisation selected."
-          return
+        def list_organisations(orgs)
+          orgs.each_with_index { |o, i| puts "  #{i + 1}) #{o["name"]} (#{o["id"]})" }
         end
 
-        # Generate profile name from org name (slug it)
-        profile_name ||= org["name"].downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
-
-        Config.save_profile(
-          profile_name,
-          token: token,
-          host: host,
-          organisation_id: org["id"],
-          display_name: org["name"]
-        )
-
-        # Also set as default
-        Config.switch_profile(profile_name)
-
-        puts "\nProfile '#{profile_name}' created and set as default."
-        puts "  org: #{org["name"]} (#{org["id"]})"
-        puts "  host: #{host}"
-        puts "\nTo add another profile, run 'shapeup login' again."
-        puts "To switch: 'shapeup auth switch <name>'"
-      end
+        def slug(name)
+          name.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+        end
     end
   end
 end

data/lib/shapeup_cli/commands/setup.rb

@@ -3,7 +3,9 @@
 module ShapeupCli
   module Commands
     class Setup < Base
-      SKILL_SOURCE = File.expand_path("../../../skills/shapeup/SKILL.md", __dir__)
+      SKILLS_DIR = File.expand_path("../../../skills", __dir__)
+      SKILL_SOURCE = File.join(SKILLS_DIR, "shapeup", "SKILL.md")
+      SKILL_NAMES = %w[ shapeup shapeup-connect ].freeze
 
       def self.metadata
         {
@@ -48,37 +50,34 @@ module ShapeupCli
 
       private
         def install_global(agent)
-          dir = File.join(Dir.home, ".#{agent}", "skills", "shapeup")
-          install_skill(dir, "~/.#{agent}/skills/shapeup/")
+          install_skills(File.join(Dir.home, ".#{agent}", "skills"), "~/.#{agent}/skills")
         end
 
         def install_project
-          dir = File.join(".claude", "skills", "shapeup")
-          install_skill(dir, ".claude/skills/shapeup/")
+          install_skills(File.join(".claude", "skills"), ".claude/skills")
         end
 
-        def install_skill(dir, display_path)
-          unless File.exist?(SKILL_SOURCE)
-            abort "SKILL.md not found at #{SKILL_SOURCE}. Is the CLI installed correctly?"
-          end
+        def install_skills(base, display_base)
+          SKILL_NAMES.each do |name|
+            source = File.join(SKILLS_DIR, name, "SKILL.md")
+            abort "SKILL.md not found at #{source}. Is the CLI installed correctly?" unless File.exist?(source)
 
-          FileUtils.mkdir_p(dir)
-          dest = File.join(dir, "SKILL.md")
+            dir = File.join(base, name)
+            FileUtils.mkdir_p(dir)
+            dest = File.join(dir, "SKILL.md")
 
-          if File.exist?(dest)
-            puts "Updating #{display_path}SKILL.md"
-          else
-            puts "Installing #{display_path}SKILL.md"
+            puts "#{File.exist?(dest) ? "Updating" : "Installing"} #{display_base}/#{name}/SKILL.md"
+            FileUtils.cp(source, dest)
           end
 
-          FileUtils.cp(SKILL_SOURCE, dest)
-
           puts "Done! Restart your agent session to pick up the skill."
           puts
           puts "The skill triggers on phrases like:"
           puts "  'my tasks', 'list pitches', 'cycle progress', 'shapeup', etc."
           puts
           puts "Your agent will use the ShapeUp CLI to handle these requests."
+          puts
+          puts "To let your ShapeUp agent pick up requests from issues, run /shapeup-connect."
         end
     end
   end

data/lib/shapeup_cli/commands.rb

@@ -81,6 +81,13 @@ module ShapeupCli
           issues add-to-pitch <id> --pitch <pid>
                                     Fold issue into an existing pitch
 
+        Agents:
+          agents                    List your agents
+          agents add "Name"         Add your agent (Pro, one per member)
+          connect                   Listen for requests as your agent (JSON lines)
+          inbox                     Requests waiting for this agent
+          inbox done <id>           Mark a request handled
+
         Comments:
           comments list --issue <id>           List comments on an issue
           comments list --pitch <id>           List comments on a pitch
@@ -113,15 +120,22 @@ module ShapeupCli
 
         Config:
           config show               Show current config
+          config explain            Trace where each setting's value comes from
           config set org "Name"     Set default organisation (name or ID)
           config set host <url>     Set ShapeUp host
           config init "Name"        Create .shapeup/config.json for this directory
 
+        Doctor:
+          doctor                    Diagnose setup: config, auth, connectivity, skills
+
         Setup:
           setup claude              Install skill into Claude Code
           setup cursor              Install skill into Cursor
           setup project             Install skill into current project
 
+        Profiles (append to any command):
+          --profile <name>          Use a saved profile, e.g. your agent's
+
         Output modes (append to any command):
           --json                    Full JSON envelope with breadcrumbs
           --md                      Markdown tables
@@ -175,8 +189,12 @@ module ShapeupCli
         checklist      Manage checklist items on pitches/issues (list, add, tick, untick, edit, remove)
         tags           List/add/remove tags on pitches and issues
         my-work / me   Show my assigned work
+        inbox          Agents: requests waiting on issues (done <id> to clear)
+        agents         List your agents, or add one
+        connect        Listen for requests as your agent (prints JSON lines)
         search         Search everything
-        config         Show/set config (set, show, init)
+        config         Show/set config (set, show, explain, init)
+        doctor         Diagnose setup (config, auth, connectivity, skills)
         setup          Install agent skills (claude, cursor, project)
         commands       This list
         help           Usage guide
@@ -200,7 +218,11 @@ require_relative "commands/my_work"
 require_relative "commands/search"
 require_relative "commands/auth"
 require_relative "commands/config_cmd"
+require_relative "commands/doctor"
 require_relative "commands/setup"
 require_relative "commands/comments"
 require_relative "commands/checklist"
 require_relative "commands/tags"
+require_relative "commands/inbox"
+require_relative "commands/connect"
+require_relative "commands/agents"

data/lib/shapeup_cli/config.rb

@@ -100,19 +100,46 @@ module ShapeupCli
       data
     end
 
-    # Resolution order: env var > project config > global config > profile > default
+    # Resolution order: env var > profile picked with SHAPEUP_PROFILE > project config > global config > default profile > default
     def self.host
-      ENV["SHAPEUP_HOST"] || load_config["host"] || current_profile&.dig("host") || ShapeupCli::DEFAULT_HOST
+      ENV["SHAPEUP_HOST"] || chosen_profile_value("host") || load_config["host"] || current_profile&.dig("host") || ShapeupCli::DEFAULT_HOST
     end
 
     def self.organisation_id
-      ENV["SHAPEUP_ORG"] || load_config["organisation_id"] || current_profile&.dig("organisation_id")&.then { |v| v.empty? ? nil : v }
+      ENV["SHAPEUP_ORG"] || chosen_profile_value("organisation_id") || load_config["organisation_id"] || current_profile&.dig("organisation_id")&.then { |v| v.empty? ? nil : v }
+    end
+
+    def self.chosen_profile_value(key)
+      return unless ENV["SHAPEUP_PROFILE"]
+
+      value = current_profile&.dig(key)
+      value unless value.to_s.empty?
     end
 
     def self.token
       ENV["SHAPEUP_TOKEN"] || current_profile&.dig("token")
     end
 
+    # --- Introspection (for `config explain` and `doctor`) ---
+
+    def self.saved_default_profile
+      load_profiles_raw["default"]
+    end
+
+    def self.global_config
+      load_config_raw
+    end
+
+    def self.project_config_path
+      find_project_config
+    end
+
+    def self.project_config
+      path = find_project_config
+      return {} unless path
+      JSON.parse(File.read(path)) rescue {}
+    end
+
     # --- Pipe detection ---
 
     def self.piped?

data/lib/shapeup_cli/surface.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ShapeupCli
+  # Serializes the entire CLI surface — commands, subcommands, flags — into
+  # sorted lines, snapshotted in SURFACE.txt and gated by surface_test.rb so
+  # no command or flag appears or disappears without a reviewed diff.
+  module Surface
+    TOP_LEVEL_COMMANDS = %w[ login logout commands help version ].freeze
+
+    def self.lines
+      lines = []
+
+      TOP_LEVEL_COMMANDS.each { |name| lines << "CMD shapeup #{name}" }
+
+      ShapeupCli.top_level_metadata[:shortcuts].each_key do |shortcut|
+        lines << "CMD shapeup #{shortcut.split.first}"
+      end
+
+      ShapeupCli.top_level_metadata[:inherited_flags].each do |flag|
+        lines << "FLAG shapeup --#{flag[:name]} #{flag[:type]}"
+      end
+
+      ShapeupCli::COMMAND_MAP.each do |name, klass|
+        lines << "CMD shapeup #{name}"
+        metadata = klass.metadata
+        (metadata[:subcommands] || []).each do |sub|
+          lines << "SUB shapeup #{name} #{sub[:name]}"
+        end
+        (metadata[:flags] || []).each do |flag|
+          lines << "FLAG shapeup #{name} --#{flag[:name]} #{flag[:type]}"
+        end
+      end
+
+      lines.uniq.sort
+    end
+
+    def self.render
+      lines.join("\n") + "\n"
+    end
+  end
+end

data/lib/shapeup_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShapeupCli
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/shapeup_cli.rb

@@ -19,14 +19,17 @@ require_relative "shapeup_cli/commands"
 module ShapeupCli
   DEFAULT_HOST = "https://shapeup.cc"
 
-  # Exit codes
+  # Exit codes, matching the rubric shared by the Basecamp-family CLIs so
+  # agents that know one CLI can read all of them.
   EXIT_OK          = 0
   EXIT_USAGE       = 1
   EXIT_NOT_FOUND   = 2
-  EXIT_AUTH         = 3
+  EXIT_AUTH        = 3
   EXIT_PERMISSION  = 4
-  EXIT_API_ERROR   = 5
-  EXIT_RATE_LIMIT  = 6
+  EXIT_RATE_LIMIT  = 5
+  EXIT_NETWORK     = 6
+  EXIT_API_ERROR   = 7
+  EXIT_AMBIGUOUS   = 8
   EXIT_INTERRUPTED = 130
 
   COMMAND_MAP = {
@@ -41,14 +44,20 @@ module ShapeupCli
     "search"    => Commands::Search,
     "auth"      => Commands::Auth,
     "config"    => Commands::ConfigCmd,
+    "doctor"    => Commands::Doctor,
     "setup"     => Commands::Setup,
     "comments"  => Commands::Comments,
     "checklist" => Commands::Checklist,
-    "tags"      => Commands::Tags
+    "tags"      => Commands::Tags,
+    "inbox"     => Commands::Inbox,
+    "connect"   => Commands::Connect,
+    "agents"    => Commands::Agents
   }.freeze
 
   def self.run(argv)
     args = argv.dup
+    use_profile_from!(args) unless args.first == "login"
+    @machine_output = args.intersect?(%w[ --json --agent --quiet -q ]) || !$stdout.tty?
 
     # Top-level: shapeup --agent --help
     if args.include?("--agent") && args.include?("--help")
@@ -85,8 +94,12 @@ module ShapeupCli
     when "checklist"      then Commands::Checklist.run(args)
     when "tags"           then Commands::Tags.run(args)
     when "my-work", "me"  then Commands::MyWork.run(args)
+    when "inbox"          then Commands::Inbox.run(args)
+    when "connect"        then Commands::Connect.run(args)
+    when "agents"         then Commands::Agents.run(args)
     when "search"         then Commands::Search.run(args)
     when "config"         then Commands::ConfigCmd.run(args)
+    when "doctor"         then Commands::Doctor.run(args)
     when "setup"          then Commands::Setup.run(args)
     when "commands"       then Commands.list_commands
     when "version", "-v", "--version"
@@ -96,28 +109,52 @@ module ShapeupCli
     else
       $stderr.puts "Unknown command: #{command}"
       $stderr.puts "Run 'shapeup help' for usage"
-      exit 1
+      exit EXIT_USAGE
     end
-  rescue Client::AuthError => e
-    $stderr.puts "Not authenticated. Run 'shapeup login' first."
-    exit EXIT_AUTH
+  rescue Client::AuthError
+    fail_with "Not authenticated.", code: "auth_required", exit_code: EXIT_AUTH,
+      retryable: false, hint: "Run 'shapeup login' or set SHAPEUP_TOKEN"
   rescue Client::NotFoundError => e
-    $stderr.puts "Not found: #{e.message}"
-    exit EXIT_NOT_FOUND
+    fail_with "Not found: #{e.message}", code: "not_found", exit_code: EXIT_NOT_FOUND, retryable: false
   rescue Client::PermissionError => e
-    $stderr.puts "Access denied: #{e.message}"
-    exit EXIT_PERMISSION
-  rescue Client::RateLimitError => e
-    $stderr.puts "Rate limited — please wait and try again."
-    exit EXIT_RATE_LIMIT
+    fail_with "Access denied: #{e.message}", code: "forbidden", exit_code: EXIT_PERMISSION, retryable: false
+  rescue Client::RateLimitError
+    fail_with "Rate limited.", code: "rate_limit", exit_code: EXIT_RATE_LIMIT,
+      retryable: true, hint: "Wait a moment and retry"
+  rescue Client::NetworkError => e
+    fail_with e.message, code: "network", exit_code: EXIT_NETWORK,
+      retryable: true, hint: "Check your connection and 'shapeup config show'"
   rescue Client::ApiError => e
-    $stderr.puts "Error: #{e.message}"
-    exit EXIT_API_ERROR
+    fail_with "Error: #{e.message}", code: "api_error", exit_code: EXIT_API_ERROR, retryable: false
   rescue Interrupt
     $stderr.puts "\nAborted."
     exit EXIT_INTERRUPTED
   end
 
+  # Errors reach machine consumers as a JSON envelope on stdout with a
+  # `retryable` verdict, and humans as plain text on stderr. `retryable: false`
+  # means "no known reason a retry helps", not proof of permanence.
+  def self.fail_with(message, code:, exit_code:, retryable:, hint: nil)
+    if @machine_output
+      envelope = { ok: false, error: message, code: code, retryable: retryable }
+      envelope[:hint] = hint if hint
+      puts JSON.generate(envelope)
+    else
+      $stderr.puts message
+      $stderr.puts hint if hint
+    end
+    exit exit_code
+  end
+
+  def self.use_profile_from!(args)
+    if (index = args.index("--profile"))
+      ENV["SHAPEUP_PROFILE"] = args.delete_at(index + 1) || abort("Usage: --profile <name>")
+      args.delete_at(index)
+    elsif (flag = args.find { |arg| arg.start_with?("--profile=") })
+      ENV["SHAPEUP_PROFILE"] = args.delete(flag).delete_prefix("--profile=")
+    end
+  end
+
   def self.top_level_metadata
     {
       command: "shapeup",
@@ -136,6 +173,7 @@ module ShapeupCli
       },
       inherited_flags: [
         { name: "org", type: "string", usage: "Organisation ID or name" },
+        { name: "profile", type: "string", usage: "Saved profile to use, e.g. your agent's (same as SHAPEUP_PROFILE)" },
         { name: "json", type: "bool", usage: "Full JSON envelope with breadcrumbs" },
         { name: "md", type: "bool", usage: "Markdown output" },
         { name: "agent", type: "bool", usage: "Raw JSON data only (for AI agents)" }

data/skills/shapeup/SKILL.md

@@ -77,7 +77,7 @@ Manage pitches, scopes, tasks, issues, and cycles via the ShapeUp CLI. Columns a
 4. **Follow breadcrumbs** — JSON responses include a `breadcrumbs` array with suggested next commands. Use these to chain workflows.
 5. **"Pitch" = "Package" in code** — users say "pitch", the API uses "package". The CLI uses "pitch" everywhere.
 6. **Use 'me' and 'none'** — `--assignee me` for current user, `--assignee none` for unassigned items.
-7. **Check exit codes** — 0=OK, 2=not found, 3=auth error, 4=permission denied, 5=API error. Branch on exit code without parsing error text.
+7. **Check exit codes** — 0=OK, 2=not found, 3=auth, 4=forbidden, 5=rate limit, 6=network, 7=API error. Branch on the exit code or the JSON envelope's `retryable` field without parsing error text.
 8. **Deletes need confirmation** — `delete`/`remove` commands (pitches, scopes, tasks, issues, comments) prompt `[y/N]` interactively and **refuse when run non-interactively** unless you pass `--yes` (or `-y`). As an agent you have no TTY, so add `--yes` only after you have confirmed the deletion is intended.
 
 ### Output Modes
@@ -99,19 +99,27 @@ Manage pitches, scopes, tasks, issues, and cycles via the ShapeUp CLI. Columns a
 | 2 | Not found |
 | 3 | Auth error |
 | 4 | Permission denied |
-| 5 | API error |
-| 6 | Rate limited |
+| 5 | Rate limited (retryable) |
+| 6 | Network error (retryable) |
+| 7 | API error |
+| 8 | Ambiguous selector |
 | 130 | Interrupted (Ctrl-C) |
 
+With `--json`, `--agent`, or piped output, errors arrive as a JSON envelope on stdout:
+`{"ok": false, "error": "...", "code": "rate_limit", "retryable": true, "hint": "..."}`.
+Branch on `retryable` to decide retry-vs-abandon; `false` means "no known reason a retry helps".
+
 ## Quick Reference
 
 | Task | Command |
 |------|---------|
 | **Auth & Context** | |
-| Login | `shapeup login` |
+| Login | `shapeup login` (opens a browser; from an agent or script pass `--org <name>` so no terminal prompt is needed) |
 | Auth status | `shapeup auth status` |
 | List orgs | `shapeup orgs --json` |
 | Show current org | `shapeup config show` |
+| Trace config precedence | `shapeup config explain` |
+| Diagnose setup problems | `shapeup doctor` |
 | Set default org | `shapeup config set org "Compass Labs"` |
 | Per-directory config | `shapeup config init "Compass Labs"` |
 | Install skill | `shapeup setup claude` |
@@ -203,6 +211,17 @@ Manage pitches, scopes, tasks, issues, and cycles via the ShapeUp CLI. Columns a
 | All my assignments | `shapeup me --json` |
 | My work (alias) | `shapeup my-work --json` |
 | Search everything | `shapeup search "query" --json` |
+| **Agents** | |
+| Your agents | `shapeup agents --json` |
+| Add your agent | `shapeup agents add "Bond"` |
+| Listen for requests as your agent | `shapeup connect` (or `/shapeup-connect` in Claude Code) |
+| Save an agent token as a profile | `shapeup login --token <token>` |
+| Requests waiting for this agent | `shapeup inbox --json` |
+| Mark a request handled | `shapeup inbox done <id>` |
+| Save an agent token as a profile | `shapeup login --token <token>` |
+| Watch the inbox as JSON lines | `SHAPEUP_PROFILE=<agent> shapeup connect` |
+| Reply under a comment | `shapeup comments add --issue <id> --parent <comment_id> "Reply"` |
+| React to a comment | `shapeup comments react <comment_id> 👀` |
 
 ## Common Workflows
 
@@ -366,6 +385,8 @@ Creates `.shapeup/config.json` in the current directory. All commands in this di
 ```bash
 shapeup config set org "Compass Labs"
 shapeup config set host https://shapeup.cc
+shapeup doctor            # full setup diagnosis with fix hints
+shapeup config explain    # why is the CLI using this org/host/token?
 ```
 
 ### Environment Variables