ya-git-jira 1.6.0 → 2.0.0

package/README.md

@@ -1,51 +1,89 @@
-# ya-git-jira - Yet Another Git Jira
+# ya-git-jira
 
-This package installs several scripts that are written to be
-usable as `git` extensions, i.e. sub-commands of the `git` command.
-The extensions faciliate workflow when using `git` for source control and `jira`
-for issue tracking. Other similar packages exist -- thus the "yet another"
-in the name.
+Git extensions for Jira, GitLab, and Confluence. Each command is a standalone
+executable that `git` discovers automatically (e.g. `git jira start`, `git lab
+merge active`, `git confluence page search`). A unified `gitj` wrapper is also
+provided.
 
-This package will likely evolve over time to include more workflow cases.
+## Requirements
 
-## gitj -- A test driver to use instead of `git <command>`
+[Bun](https://bun.sh) (not Node.js):
 
-It can be useful to run these commands as if they were being invoked through
-`git` but using a proxy for `git` than can only execute the commands in this
-package.
+```
+curl -fsSL https://bun.sh/install | bash
+```
+
+## Install
+
+```
+npm install -g ya-git-jira   # or bun / yarn / pnpm
+```
+
+## Configuration
+
+All configuration is via `git config`. Use `--global` if the same settings apply
+across repositories.
+
+### Jira
+
+```
+git config jira.host yourcompany.atlassian.net
+git config jira.token "<api-token>"
+```
+
+Create an API token: <https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/>
 
-For example, to see the available top level commands, run `gitj --help`:
+### GitLab
 
 ```
-$ gitj help
-Usage: gitj [options] [command]
+git config gitlab.host gitlab.com        # default if omitted
+git config gitlab.token "<api-token>"
+```
+
+Create a personal access token: <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token>
 
-Options:
-  -V, --version   output the version number
-  -h, --help      display help for command
+### Confluence
 
-Commands:
-  bump [options]  Bump the version number in the current branch
-  jira [options]  Commands for working with Jira
-  lab [options]   Commands for working with GitLab
 ```
+git config confluence.host yourcompany.atlassian.net
+git config confluence.token "<api-token>"
+```
+
+The token is an Atlassian API token (same kind as Jira).
+
+### Email address
+
+Commands fall back to `user.email` from git config. Override per-service if needed:
 
-## Command hierarchy and naming conventions
+```
+git config jira.user <email>
+git config gitlab.user <email>
+git config confluence.user <email>
+```
 
-The `git jira` and `git lab` commands are arranged in a hierarchy with a structure
-and naming conventions that are indended to make it easy to navigate the existing
-commands and to also make it relatively easy to decide where a new command should
-go into the hierarchy. The current hierarchy is:
+## Command hierarchy
 
 ```
 gitj
-    bump
+    api                 authenticated REST request to any service
+    bump                bump the version suffix of the current branch
+    confluence
+        whoami
+        space
+            list
+        page
+            search
+            show
+            update
+    install-skills      install AI agent skills for a coding framework
     jira
+        whoami
+        start           create a topic branch from a Jira issue
         issue
             list
             show
-        start
     lab
+        whoami
         group
             list
         merge
@@ -57,113 +95,75 @@ gitj
             list
         project
             list
+            mr
+                list
             pipeline
+                jobs
+                latest
                 list
+                log
             whereami
-    whoami
 ```
 
-The pattern `<command> list | show` that is used for `issue` will probably become
-a common pattern everywhere that `list` appears above. The subcommand `list` implies
-that multiple items are return, whereas `show` implies seeing the details for a single item.
-
-The `merge` subcommands `active` vs `todo` are both commands that result in a list.
-We might refactor them to instead be `list --active` and `list --todo` which would
-be more consistent.
-
-The `git jira start` command might more logically be `git jira issue start`
-but `start` implies *issue* and it is expected to be one of the most commonly
-executed commands so we elevate it the hierarchy.
+Every leaf command supports `--help`. Run `gitj --help-all` to print the full
+tree with descriptions.
 
-## git-jira-start -- Create a new topic branch for work on an issue
+## Noteworthy commands
 
-#### Usage:
-```bash
-$ git jira-start <issue>
-```
+### git jira start
 
-#### Examples:
-```bash
-$ git jira-start BUG-0042
 ```
-
-The command retrieves the summary line for the issue and converts it to
-a suitable branch name using the kebab-case-convention. If BUG-0042 had
-the summary "fix the thing" then the branch name will be `BUG-0042-fix-the-thing`.
-
-The command does not (yet) change the status of the issue.
-
-## git-bump -- Create a new branch based on the current branch
-
-Usage:
-```bash
-$ git bump
+git jira start BUG-42
 ```
 
-This command is not specific to Jira. It simply reads the current branch name and creates a new branch with the version bumped, i.e. incremented.
-
-Assume the current branch is `BUG-0042-fix-the-thing`.
-Executing the bump command once will create a new branch named `BUG-0042-fix-the-thing.v1`. If you execute the bump command again it will
-create a branch `BUG-0042-fix-the-thing.v2`.
+Fetches the issue summary from Jira, converts it to kebab-case, and creates a
+branch like `BUG-42-fix-the-thing`.
 
-The `git bump` command will work whatever the current branch name is.
-It just checks to see if the current branch already ends with `.v`<*num*>,
-in which case it increments *num* but otherwise leaves the branch name as is.
-If the current branch does not end with `.v`<*num*> then it simply appends the
-suffix `.v1`.
-
-##  Bun required
-
-This package uses [bun](https://bun.sh) instead of [node](https://nodejs.org/en).
-You must install it before you install this package.
+### git bump
 
 ```
-$ curl -fsSL https://bun.sh/install | bash
+git bump
 ```
 
-## Install with any npm-compatible package manager
+Appends or increments a `.vN` suffix on the current branch name:
+`BUG-42-fix-the-thing` -> `.v1` -> `.v2` -> ...
 
-You can install ya-git-jira via `npm`, or `yarn` or `pnpm` or `bun`.
+### git api
 
 ```
-$ npm install -g ya-git-jira
+git api jira /rest/api/3/myself
+git api gitlab /api/v4/user
+git api confluence /wiki/api/v2/spaces
 ```
 
-## Configuration
-
-All configuration is via `git config` settings. If your company has multiple
-repositories that all using Jira issue tracking then you probably want to use
-the global config by adding the `--global` option to the commands below.
-
-### Jira
+Make arbitrary authenticated REST calls to any configured service. Useful for
+one-off queries and scripting.
 
-The `git jira` comands require your Jira `host` and `token`. The `host` is your Jira cloud service (usually `yourcompany.atlassian.net`).
-To create an API token follow the instructions [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
+### gitj install-skills
 
 ```
-$ git config jira.host yourcompany.atlassian.net
-$ git config jira.token "<long token here>"
+gitj install-skills opencode       # symlinks to ~/.config/opencode/skills/
+gitj install-skills copilot        # symlinks to ~/.copilot/skills/
+gitj install-skills claude         # symlinks to .claude/skills/ (project-level)
+gitj install-skills opencode --copy   # copy instead of symlink
+gitj install-skills opencode --force  # overwrite existing directories
 ```
 
-### GitLab
-
-Likewise the `git lab` comands require your GitLab `host` and `token`, though the default `host` `gitlab.com` will be sufficient
-for many users. To create an API token follow the instructions [here](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)
-
-```
-$ git config gitlab.host gitlab.com
-$ git config gitlab.token "<long token here>"
-```
+Installs AI agent skill files (`git-jira`, `git-lab`, `git-confluence`) so that
+coding assistants (OpenCode, GitHub Copilot, Claude Code) know how to use these
+tools.
 
-### Email address
+## AI agent skills
 
-Both `git lab` and `git jira` also need the email address associated associated with those accounts.
-Since `git` itself requires an email addres via the setting `user.email`, it is a reasonable default setting
-that will work for many users. But if necessary, you can specify the different email addresses
-using these two settings:
+The `.opencode/skills/` directory contains concise skill files for AI coding
+agents. These tell agents that the tools exist, how auth works, and key workflow
+patterns. Install them with `gitj install-skills <framework>`.
 
+## Development
 
 ```
-$ git config jira.user <email-address>
-$ git config gitlab.user <email-address>
+bun install          # install dependencies
+bun run build        # build to dist/
+bun test             # run all tests
+bunx tsc --noEmit    # type check
 ```

package/bin/git-api.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { isMain } from '../lib/is_main'
+import { apiRequest, apiPaginate, serviceNames } from '../lib/api.ts'
+
+const version = await getPackageVersion()
+
+const httpMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('api')
+        .description('make an authenticated API request')
+        .argument('<service>', `service name (${serviceNames.join(', ')})`)
+        .argument('<endpoint>', 'API endpoint path (e.g. /user, /myself)')
+        .option('-X, --method <method>', 'HTTP method (default: GET, auto-promotes to POST with --data)')
+        .option('-d, --data <json>', 'request body as JSON string')
+        .option('--raw', 'don\'t prepend the default base path')
+        .option('--paginate', 'follow pagination links and return all results')
+        .option('-v, --verbose', 'show response status and headers on stderr')
+        .action(async (service: string, endpoint: string, options) => {
+            let method = options.method?.toUpperCase() ?? (options.data ? 'POST' : 'GET')
+            if (!httpMethods.includes(method)) {
+                console.error(`Unknown HTTP method: ${method}`)
+                process.exit(1)
+            }
+
+            if (options.paginate && method !== 'GET') {
+                console.error('--paginate only works with GET requests')
+                process.exit(1)
+            }
+
+            const requestOptions = {
+                raw: options.raw,
+                data: options.data,
+            }
+
+            let result
+            if (options.paginate) {
+                result = await apiPaginate(service, endpoint, requestOptions)
+            } else {
+                result = await apiRequest(service, method, endpoint, requestOptions)
+            }
+
+            if (options.verbose) {
+                console.error(`HTTP ${result.status}`)
+                result.headers.forEach((value, key) => {
+                    console.error(`${key}: ${value}`)
+                })
+                console.error('')
+            }
+
+            console.log(JSON.stringify(result.body, null, 2))
+
+            if (result.status >= 400) {
+                process.exit(1)
+            }
+        })
+    return program
+}
+
+export default create
+
+if (isMain('git-api')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-page-search.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { confluenceApi, confluenceSearch } from '../lib/confluence'
+import { getConfluenceConfig } from '../lib/confluence'
+import type { Page, SearchResult } from '../lib/confluence'
+import { isMain } from '../lib/is_main'
+const version = await getPackageVersion()
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('search')
+        .description('Search for Confluence pages by title (fuzzy by default)')
+        .argument('query', 'Search query')
+        .option('-v, --verbose', 'Verbose output')
+        .option('--exact', 'Exact title match (uses v2 API)')
+        .option('--full-text', 'Search page body content in addition to title')
+        .action(async (query: string, options) => {
+            const { host } = await getConfluenceConfig()
+
+            if (options.exact) {
+                const pages = await confluenceApi(`pages?title=${encodeURIComponent(query)}`) as Array<Page>
+                if (options.verbose) {
+                    console.log(pages)
+                } else {
+                    for (const page of pages) {
+                        const url = `https://${host}/wiki/spaces/${page.spaceId}/pages/${page.id}`
+                        console.log(`${page.id}\t${page.title}\t${url}`)
+                    }
+                }
+                return
+            }
+
+            const field = options.fullText ? 'text' : 'title'
+            const cql = `type=page AND ${field} ~ "${query}"`
+            const results = await confluenceSearch(cql) as Array<SearchResult>
+            if (options.verbose) {
+                console.log(results)
+            } else {
+                for (const result of results) {
+                    const id = result.content.id
+                    const title = result.content.title
+                    const url = `https://${host}${result.url}`
+                    console.log(`${id}\t${title}\t${url}`)
+                }
+            }
+        })
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-page-search')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-page-show.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { confluenceApi } from '../lib/confluence'
+import { getConfluenceConfig } from '../lib/confluence'
+import type { Page } from '../lib/confluence'
+import { isMain } from '../lib/is_main'
+const version = await getPackageVersion()
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('show')
+        .description('Show information about a Confluence page')
+        .argument('id', 'Page ID')
+        .option('-v, --verbose', 'Verbose output')
+        .option('-b, --body-format <format>', 'Include page body (storage or atlas_doc_format)')
+        .option('--body-only', 'Output only the body content value (requires --body-format)')
+        .action(async (id: string, options) => {
+            let endpoint = `pages/${id}`
+            if (options.bodyFormat) {
+                endpoint += `?body-format=${options.bodyFormat}`
+            }
+            const page = await confluenceApi(endpoint) as Page
+            if (options.bodyOnly) {
+                if (!options.bodyFormat) {
+                    console.error('--body-only requires --body-format')
+                    process.exit(1)
+                }
+                const body = page.body
+                const content = options.bodyFormat === 'storage'
+                    ? body?.storage?.value
+                    : body?.atlas_doc_format?.value
+                if (content) {
+                    console.log(content)
+                } else {
+                    console.error('No body content returned')
+                    process.exit(1)
+                }
+            } else if (options.verbose) {
+                console.log(page)
+            } else {
+                const { host } = await getConfluenceConfig()
+                const url = `https://${host}/wiki/spaces/${page.spaceId}/pages/${page.id}`
+                const result: Record<string, unknown> = { id: page.id, title: page.title, spaceId: page.spaceId, url }
+                if (page.body?.storage?.value) {
+                    result.bodyLength = page.body.storage.value.length
+                }
+                console.log(result)
+            }
+        })
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-page-show')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-page-update.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { confluenceApi, confluenceApiWrite } from '../lib/confluence'
+import type { Page } from '../lib/confluence'
+import type { JSONValue } from '../lib/json'
+import { isMain } from '../lib/is_main'
+const version = await getPackageVersion()
+
+async function readStdin(): Promise<string> {
+    const chunks: Buffer[] = []
+    for await (const chunk of Bun.stdin.stream()) {
+        chunks.push(Buffer.from(chunk))
+    }
+    return Buffer.concat(chunks).toString('utf-8')
+}
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('update')
+        .description('Update a Confluence page')
+        .argument('id', 'Page ID')
+        .option('-t, --title <title>', 'New page title (defaults to current title)')
+        .option('-f, --file <path>', 'Read body content from file (default: stdin)')
+        .option('-m, --message <message>', 'Version message')
+        .option('-v, --verbose', 'Verbose output')
+        .action(async (id: string, options) => {
+            const current = await confluenceApi(`pages/${id}`) as Page
+
+            let content: string
+            if (options.file) {
+                const file = Bun.file(options.file)
+                content = await file.text()
+            } else {
+                content = await readStdin()
+            }
+
+            if (!content.trim()) {
+                console.error('No content provided. Pipe content via stdin or use --file.')
+                process.exit(1)
+            }
+
+            const title = options.title || current.title
+            const nextVersion = current.version.number + 1
+
+            const body: JSONValue = {
+                id,
+                status: 'current',
+                title,
+                body: {
+                    representation: 'storage',
+                    value: content,
+                },
+                version: {
+                    number: nextVersion,
+                    message: options.message || '',
+                },
+            }
+
+            const result = await confluenceApiWrite(`pages/${id}`, 'PUT', body) as Page
+            if (options.verbose) {
+                console.log(result)
+            } else {
+                console.log(`Updated page ${result.id} "${result.title}" to version ${result.version.number}`)
+            }
+        })
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-page-update')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-page.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { isMain } from '../lib/is_main'
+import search from './git-confluence-page-search'
+import show from './git-confluence-page-show'
+import update from './git-confluence-page-update'
+const version = await getPackageVersion()
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('page')
+        .description('Commands for working with Confluence pages')
+        .addCommand(search())
+        .addCommand(show())
+        .addCommand(update())
+        .action(() => program.help())
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-page')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-space-list.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { confluenceApi } from '../lib/confluence'
+import type { Space } from '../lib/confluence'
+import { isMain } from '../lib/is_main'
+const version = await getPackageVersion()
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('list')
+        .description('List Confluence spaces')
+        .option('-v, --verbose', 'Verbose output')
+        .action(async (options) => {
+            const spaces = await confluenceApi('spaces') as Array<Space>
+            if (options.verbose) {
+                console.log(spaces)
+            } else {
+                for (const space of spaces) {
+                    console.log(`${space.key}\t${space.name}`)
+                }
+            }
+        })
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-space-list')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-space.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { isMain } from '../lib/is_main'
+import list from './git-confluence-space-list'
+const version = await getPackageVersion()
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('space')
+        .description('Commands for working with Confluence spaces')
+        .addCommand(list())
+        .action(() => program.help())
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-space')) {
+    await create().parseAsync(Bun.argv)
+}

package/bin/git-confluence-whoami.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { getPackageVersion } from '../lib/package'
+import { confluenceApiV1 } from '../lib/confluence'
+import type { ConfluenceUser } from '../lib/confluence'
+import { isMain } from '../lib/is_main'
+const version = await getPackageVersion()
+
+export function create(): Command {
+    const program: Command = new Command()
+    program
+        .version(version)
+        .name('whoami')
+        .description('Show the current Confluence user')
+        .option('-v, --verbose', 'Verbose output')
+        .action(async (options) => {
+            const myself = await confluenceApiV1('user/current') as ConfluenceUser
+            if (options.verbose) {
+                console.log(myself)
+            } else {
+                const { displayName, email, accountId } = myself
+                console.log({ displayName, email, accountId })
+            }
+        })
+    return program
+}
+
+export default create
+
+if (isMain('git-confluence-whoami')) {
+    await create().parseAsync(Bun.argv)
+}