@proggarapsody/bitbottle 1.20.0 → 1.22.0

package/README.md

@@ -75,8 +75,8 @@ Credentials are stored in `~/.config/bitbottle/hosts.yml`. Inside a git repo wit
 | Group | Commands |
 |---|---|
 | `auth` | `login` `logout` `status` `token` `refresh` |
-| `pr` | `list` `view` `create` `merge` `approve` `unapprove` `diff` `checkout` `edit` `decline` `ready` `request-review` `comment` |
-| `repo` | `list` `view` `create` `delete` `clone` `set-default` `rename` `fork` _(Cloud)_ |
+| `pr` | `list` `view` `create` `merge` `approve` `unapprove` `diff` `checkout` `edit` `decline` `reopen` `ready` `request-review` `comment` |
+| `repo` | `list` `view` `create` `delete` `clone` `set-default` `rename` `fork` _(Cloud)_ `file get` `tree` |
 | `branch` | `list` `create` `delete` `checkout` |
 | `tag` | `list` `create` `delete` |
 | `webhook` | `list` `view` `create` `delete` |
@@ -85,11 +85,13 @@ Credentials are stored in `~/.config/bitbottle/hosts.yml`. Inside a git repo wit
 | `workspace` | `list` _(Cloud only)_ |
 | `project` | `list WORKSPACE` _(Cloud only)_ |
 | `issue` | `list` `view` `create` `close` _(Cloud only)_ |
+| `search` | `code QUERY` _(Cloud only)_ |
 | `api` | Raw REST passthrough with pagination, `--jq`, variable expansion |
 | `alias` | Custom command shortcuts |
 | `config` | Editor, pager, git protocol per-host |
 | `completion` | `bash` `zsh` `fish` `powershell` |
 | `mcp` | MCP stdio server for AI assistants |
+| `context` | One-call orientation: host, repo, branch, default branch, ahead/behind, user, backend |
 
 All listing commands support `--json fields`, `--jq expr`, `--limit N`, `--hostname HOST`. TTY output is aligned and coloured; piped output is plain tab-separated for scripting.
 
@@ -116,6 +118,15 @@ bitbottle pr merge 42 --squash --delete-branch
 
 # Add reviewers
 bitbottle pr request-review 42 --reviewer alice --reviewer bob
+
+# Decline / reopen (reopen is Bitbucket Server / DC only)
+bitbottle pr decline 42
+bitbottle pr reopen  42
+
+# Read review comments — general + inline (file:line) anchors and replies
+bitbottle pr comment list 42                            # all comments; LOCATION column shows path:line for inline
+bitbottle pr comment list 42 --inline                   # only inline review comments
+bitbottle pr comment list 42 --json id,inline,parentId,resolved,updatedAt
 ```
 
 ### Repos & Branches
@@ -217,6 +228,33 @@ bitbottle repo fork myworkspace/my-service --into otherws --name my-fork
 Data Center, which has no fork primitive in its REST API. Both `rename` and
 `fork` accept `--json fields` and `--jq expr` for structured output.
 
+### Reading source at a ref
+
+Read file content and directory listings at any ref (branch, tag, commit
+hash) without cloning. Both backends; the bytes round-trip cleanly so
+binary files survive `--out`.
+
+```bash
+# Read a file at a ref — straight to stdout
+bitbottle repo file get MYPROJ/my-service README.md --ref main
+
+# Pin a tag and write to disk (binary-safe)
+bitbottle repo file get MYPROJ/my-service logo.png --ref v1.2.0 --out logo.png
+
+# List a directory at a ref. PATH defaults to the repo root.
+bitbottle repo tree MYPROJ/my-service --ref main
+bitbottle repo tree MYPROJ/my-service cmd --ref main
+
+# Structured output for scripts and agents
+bitbottle repo tree MYPROJ/my-service --ref main --json path,type,size
+bitbottle repo tree MYPROJ/my-service --ref main --jq '.[]|select(.type=="dir").path'
+```
+
+`type` is normalised to `file` or `dir` across both backends. Submodules
+surface as `dir` (with the submodule pointer in `hash`) so renderers can
+recurse uniformly without a special case. The MCP equivalents are
+`get_file_content` and `list_tree`.
+
 ### Workspaces & Projects (Cloud only)
 
 ```bash
@@ -232,6 +270,28 @@ bitbottle project list myworkspace --limit 100
 Both commands surface a typed unsupported-capability error against
 Bitbucket Server / Data Center hosts (workspaces are a Cloud concept).
 
+### Search _(Cloud only)_
+
+```bash
+# Search across the workspace inferred from the current checkout's pinned default
+bitbottle search code 'TODO'
+
+# Explicit workspace, custom limit
+bitbottle search code 'foo bar' --workspace myws --limit 50
+
+# Path-restricted query, JSON for scripting
+bitbottle search code 'path:README' --workspace myws --json path,repository
+bitbottle search code 'TODO' --workspace myws --json path --jq '.[].path'
+```
+
+Bitbucket Cloud's query language (`path:`, `lang:`, `repo:`, exact-phrase
+quoting, etc.) is passed through verbatim — bitbottle does not translate
+operators. The matched-segment shape (`pathMatches`, `contentMatches`)
+is preserved on the JSON side so renderers can highlight the matched
+runs. Bitbucket Server / Data Center has no first-class code-search
+REST endpoint; invocations against a Server host return the typed
+`host.unsupported` error.
+
 ### Raw API
 
 ```bash
@@ -242,6 +302,35 @@ bitbottle api -X POST -F 'title=hotfix' -F 'source.branch.name=hotfix/x' \
   '2.0/repositories/{workspace}/{repo_slug}/pullrequests'
 ```
 
+### Context (one-call orientation)
+
+`bitbottle context` collapses three previously independent calls
+(`auth status`, `repo view`, `git status`) into a single structured
+snapshot of where you are. Especially useful for AI agents that drive
+bitbottle through MCP — `get_context` is the standard first call.
+
+```bash
+bitbottle context
+# Host:           git.example.com
+# Backend:        server
+# Project:        PROJ
+# Slug:           repo
+# Branch:         feat/ctx
+# Default branch: main
+# Ahead/Behind:   2 / 0
+# User:           alice (Alice Smith)
+
+bitbottle context --json host,project,slug,branch,default_branch,ahead,behind,user,backend
+bitbottle context --json user --jq '.user.slug'
+```
+
+Outside a git repo `project`, `slug`, `branch`, and `default_branch`
+are empty; `ahead` and `behind` are omitted from the JSON output
+entirely (and rendered as `(unknown — run 'git fetch')` in the human
+table). They are also omitted whenever `git rev-list` cannot compute
+the counts — `0 / 0` would falsely read as "in sync". `host`, `user`,
+and `backend` still resolve via the configured (or `--hostname`) host.
+
 ### Outside a git repo
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proggarapsody/bitbottle",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Bitbucket CLI for Server/Data Center and Cloud — npm wrapper for bitbottle",
   "keywords": [
     "mcp",