ya-git-jira 1.5.0 → 2.0.0

package/.opencode/skills/architecture/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: architecture
+description: Project architecture, CLI design patterns, and test conventions
+---
+
+## Dual-Mode Files
+
+Every `bin/` file works both as an importable module (exporting `create()`) and as a
+directly-executable script (via the `isMain()` guard). This enables hierarchical command
+composition while allowing each command to be invoked standalone.
+
+## Hierarchical CLI
+
+Commands form a tree: `gitj` -> `lab` -> `merge` -> `active`. Each level is its own
+file. Parent commands add children via `.addCommand(child.create())`.
+
+## Eager Config Loading
+
+Config values (git config reads) are initiated at module scope as top-level promises:
+```ts
+const hostP = getConfig("jira.host")
+```
+Then awaited when actually needed. This is a performance optimization.
+
+## GitLab API Client
+
+- `lib/gitlab/api.ts` handles pagination by following `Link` headers with `rel="next"`
+- `projectScopedGet()` auto-determines the current GitLab project from the git remote URL
+
+## TypeScript Configuration
+
+- `strict: true`, target/module: `esnext`, `moduleResolution: "bundler"`
+- `allowImportingTsExtensions: true` -- imports use `.ts` extensions
+- `noEmit: true` -- Bun's bundler handles output, not tsc
+- `types: ["bun-types"]` -- Bun global APIs (Bun.spawn, Bun.argv, etc.)
+
+## Test Conventions
+
+- Test runner: Bun's built-in (`bun:test`)
+- Test files: `tests/*.test.ts`
+- Imports: `import { describe, expect, test, beforeEach, afterEach } from 'bun:test'`
+- Tests are async with explicit `Promise<void>` return types
+- Integration tests spawn real subprocesses via the project's `spawn`/`doCommand` utilities
+- Some tests set custom timeouts as a second argument: `test('name', async () => { ... }, 15000)`
+- `all-help.test.ts` dynamically generates tests for every `bin/*.ts` script

package/.opencode/skills/code-style/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: code-style
+description: Code style rules for writing and editing TypeScript in this project
+---
+
+## File Structure
+
+Every `bin/*.ts` file follows this exact pattern:
+1. Shebang: `#!/usr/bin/env bun`
+2. Imports
+3. Top-level `const version = await getPackageVersion()`
+4. `export function create(): Command { ... }` -- factory returning a Commander command
+5. `export default create` -- default export of the factory (not the command instance)
+6. `if (isMain('filename')) { await create().parseAsync(Bun.argv) }` -- dual-mode guard
+
+Parent commands (routing nodes) compose children via `.addCommand()`.
+Leaf commands define `.action(async () => { ... })` with inline logic.
+
+## Imports
+
+- Use `import type { Foo }` for type-only imports
+- Relative paths use `.ts` extensions for files: `import { foo } from "../lib/git.ts"`
+- Relative paths omit extensions for directories with `index.ts`: `import { bar } from "../lib/gitlab"`
+- General ordering (not strictly enforced):
+  1. Third-party / built-in (`commander`, `debug`, `node:path`)
+  2. Local lib modules (`../lib/git`, `../lib/gitlab`)
+  3. Sibling imports (other `bin/` files for subcommand composition)
+
+## Naming Conventions
+
+| Element | Convention | Examples |
+|---------|-----------|----------|
+| Functions | camelCase | `getConfig`, `createBranch`, `getCurrentBranch` |
+| Types/Interfaces | PascalCase | `SpawnResult`, `MergeRequest`, `JiraConfig` |
+| Variables/Constants | camelCase | `defaultOptions`, `dlog` |
+| Files | kebab-case | `merge-request.ts`, `merge-trains.ts` |
+| API response fields | snake_case (matching external APIs) | `path_with_namespace`, `source_branch` |
+
+## Types
+
+- API response types use intersection with `JSONValue`:
+  `export type Project = JSONValue & { id: number; name: string; ... }`
+- `JSONValue` is defined in `lib/json.ts` as a recursive union type
+- API responses are cast with `as Type`: `await response.json() as Issue`
+- Function return types are explicitly annotated: `Promise<string>`, `Promise<Array<Project>>`
+- Both `Array<T>` and `T[]` appear; either is acceptable
+- Use `export type` for API response shapes, `export interface` for configs/options
+
+## Formatting
+
+- **4-space indentation**
+- **Single quotes** for strings (not double quotes)
+- Semicolons are used inconsistently; both with and without are acceptable
+- Opening braces on same line: `function foo(): Type {`
+- Commander method chains use 4-space indentation with dot-chaining on new lines
+
+## Error Handling
+
+- **No try/catch blocks** -- errors propagate naturally
+- Throw on missing config: `if (!host) throw new Error("jira.host not in git config")`
+- CLI-facing errors use `console.error()` + `process.exit(1)`
+- Non-fatal warnings use `console.warn()`
+- The `spawn` utility warns on no-output commands unless `expectQuiet` is set
+
+## Debug Logging
+
+- Uses the `debug` npm package
+- Create logger: `const dlog = debug('gitlab')` or `const dlog = debug('git-lab-project-pipeline-list')`
+- Centralized for gitlab module in `lib/gitlab/dlog.ts`
+- Enable at runtime: `DEBUG=gitlab bun run bin/git-lab-project.ts`
+
+## Comments
+
+- Minimal comments; code is self-documenting
+- Use `//` single-line style when needed
+- No JSDoc conventions

package/.opencode/skills/git-confluence/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: git-confluence
+description: Using git-confluence commands to search, read, and update Confluence pages
+---
+
+## Overview
+
+`git-confluence` interacts with Confluence Cloud via its REST API v2.
+Authentication uses git config values with fallback to `jira.*` equivalents:
+
+```sh
+git config --global confluence.host yourcompany.atlassian.net  # falls back to jira.host
+git config --global confluence.user you@company.com            # falls back to jira.user, then user.email
+git config --global confluence.token your-api-token            # falls back to jira.token
+```
+
+## Commands
+
+```
+git-confluence whoami              Show current authenticated user
+git-confluence space list          List all spaces
+git-confluence page search <q>     Search pages (fuzzy title, --exact, or --full-text)
+git-confluence page show <id>      Show page metadata (add --body-format for content)
+git-confluence page update <id>    Update page content (from stdin or --file)
+```
+
+Use `--help` on any command for options.
+
+## Key Behaviors
+
+- **`--body-format`** accepts `storage` (XHTML) or `atlas_doc_format` (ADF JSON).
+  `--body-only` requires `--body-format` to be set.
+- **`page update`** always writes in `storage` representation, regardless of how
+  the content was read. It auto-fetches the current version and increments it.
+- **Page IDs are numeric strings** (e.g., `"36306946"`).
+- Page content uses Confluence storage format (XHTML with `ac:*`/`ri:*` namespaced
+  elements for macros, links, and images). Reference:
+  https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html
+
+## Workflow: Read, Revise, and Update a Page
+
+```sh
+# 1. Find the page
+git-confluence page search "My Page Title"
+
+# 2. Read content (outputs raw storage-format XHTML)
+git-confluence page show <id> --body-format storage --body-only > page.html
+
+# 3. Edit page.html as needed (must remain valid storage format)
+
+# 4. Push the update
+git-confluence page update <id> --file page.html --message "Updated content"
+```
+
+Content can also be piped via stdin:
+
+```sh
+cat page.html | git-confluence page update <id>
+```
+
+## Arbitrary Confluence API Access
+
+For operations not covered by the dedicated commands, use `git-api confluence`:
+
+```sh
+# GET (default) -- path is relative to /wiki/api/v2
+git-api confluence /spaces
+git-api confluence /pages/12345
+
+# POST (auto-promoted when --data is provided)
+git-api confluence /pages -d '{"spaceId":"123","title":"New Page","body":{"representation":"storage","value":"<p>content</p>"},"status":"current"}'
+
+# Paginated listing
+git-api confluence /spaces --paginate
+
+# Skip /wiki/api/v2 prefix for v1 API access
+git-api confluence /wiki/rest/api/content/12345 --raw
+```
+
+`git-api` handles authentication and base URL automatically. It also supports
+`-v` (status/headers to stderr), and exits with code 1 on HTTP 4xx/5xx.
+Run `git-api -h` for all options.

package/.opencode/skills/git-jira/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: git-jira
+description: Using git-jira commands to work with Jira issues and branches
+---
+
+## Overview
+
+`git-jira` interacts with Jira Cloud via its REST API v3. Authentication uses
+git config values:
+
+```sh
+git config --global jira.host yourcompany.atlassian.net
+git config --global jira.user you@company.com    # falls back to user.email
+git config --global jira.token your-api-token
+```
+
+## Commands
+
+```
+git-jira whoami              Show current Jira user
+git-jira issue list          List your unresolved issues (shortcut: git-jira list)
+git-jira issue show <key>    Show a single issue
+git-jira start <key>         Create a branch from an issue key + summary
+git-bump                     Increment the branch version suffix
+```
+
+All dedicated commands are **read-only**. Use `--help` on any command for options.
+
+## Workflow: Start Working on a Jira Issue
+
+```sh
+git-jira issue list          # find your unresolved issues
+git-jira start PROJ-123      # creates and checks out a descriptive branch
+git-bump                     # re-branch with incremented suffix if needed
+```
+
+The `start` command only creates a local branch -- it does not push or
+transition the Jira issue.
+
+## Arbitrary Jira API Access
+
+The dedicated commands are read-only. For write operations (creating issues,
+transitions, comments, etc.), use `git-api jira`:
+
+```sh
+# GET (default) -- path is relative to /rest/api/3
+git-api jira /myself
+git-api jira /issue/PROJ-123
+
+# POST (auto-promoted when --data is provided)
+git-api jira /issue -d '{"fields":{"project":{"key":"PROJ"},"summary":"New issue","issuetype":{"name":"Task"}}}'
+
+# Explicit method
+git-api jira /issue/PROJ-123 -X PUT -d '{"fields":{"summary":"Updated title"}}'
+git-api jira /issue/PROJ-123/transitions -d '{"transition":{"id":"31"}}'
+
+# Skip /rest/api/3 prefix for full URL control
+git-api jira /rest/api/2/myself --raw
+```
+
+`git-api` handles authentication and base URL automatically. It also supports
+`--paginate`, `-v` (status/headers to stderr), and exits with code 1 on HTTP
+4xx/5xx. Run `git-api -h` for all options.

package/.opencode/skills/git-lab/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: git-lab
+description: Using git-lab commands to work with GitLab projects, merge requests, and pipelines
+---
+
+## Overview
+
+`git-lab` interacts with GitLab via its REST API v4. Authentication uses git
+config values:
+
+```sh
+git config --global gitlab.host gitlab.example.com   # defaults to gitlab.com
+git config --global gitlab.token glpat-xxxxxxxxxxxx   # required
+```
+
+The token is sent as a `Private-Token` header. User identity is resolved from
+`user.email` (falls back to `gitlab.user`).
+
+## Commands
+
+```
+git-lab whoami                     Show current GitLab user
+git-lab group list                 List groups
+git-lab namespace list             List namespaces
+git-lab project list [--match]     List projects (server + client-side filter)
+git-lab project whereami           Identify project from current git remote
+git-lab project mr list            List MRs for a project/branch (defaults to current)
+git-lab merge active               My open merge requests (across all projects)
+git-lab merge todo                 MRs where I'm assigned as reviewer
+git-lab merge train list           Merge trains for the current project
+git-lab project pipeline list      Recent pipelines (scoped to current user)
+git-lab project pipeline latest    Jobs for latest pipeline on current branch
+git-lab project pipeline jobs      Jobs for a specific pipeline
+git-lab project pipeline log       Download a job's log output (plain text)
+git-bump                           Increment branch version suffix
+```
+
+All dedicated commands are **read-only**. Use `--help` on any command for
+options and defaults.
+
+## Key Behaviors
+
+- **Project-scoped commands** (`project whereami`, `project mr list`,
+  `merge train list`, all `pipeline` commands) require being in a git repo
+  with an `origin` remote pointing to GitLab.
+- **`pipeline list`** filters to the current user's pipelines, not all project
+  pipelines.
+- **`pipeline log`** outputs raw text to stdout, suitable for piping or agent
+  consumption when diagnosing CI failures.
+
+## Workflows
+
+### Find the MR for the current branch
+
+```sh
+git-lab project mr list
+```
+
+Defaults to the current directory's project and current branch. Use
+`-p <path>` and `-b <branch>` to override.
+
+### Debug a CI failure
+
+```sh
+git-lab project pipeline latest              # see jobs for current branch
+git-lab project pipeline log --job <id>      # download the log
+git-lab project pipeline log --job <id> --tail 200   # last 200 lines
+```
+
+### Review merge requests
+
+```sh
+git-lab merge todo       # MRs needing my review
+git-lab merge active     # my own open MRs
+```
+
+## Arbitrary GitLab API Access
+
+The dedicated commands are read-only. For write operations (approving MRs,
+posting comments, triggering pipelines, etc.), use `git-api gitlab`:
+
+```sh
+# GET (default) -- path is relative to /api/v4
+git-api gitlab /user
+git-api gitlab /projects/123/merge_requests
+
+# POST (auto-promoted when --data is provided)
+git-api gitlab /projects/123/merge_requests/456/notes -d '{"body":"LGTM"}'
+
+# Explicit method
+git-api gitlab /projects/123/merge_requests/456/approve -X POST
+
+# Paginated listing
+git-api gitlab /projects --paginate
+
+# Skip /api/v4 prefix for full URL control
+git-api gitlab /api/v4/version --raw
+```
+
+`git-api` handles authentication and base URL automatically. It also supports
+`-v` (status/headers to stderr), and exits with code 1 on HTTP 4xx/5xx.
+Run `git-api -h` for all options.

package/AGENTS.md

@@ -0,0 +1,50 @@
+# ya-git-jira
+
+CLI tool providing git subcommands for Jira and GitLab integration
+(e.g., `git-jira start`, `git-lab merge active`, `git-bump`). Built with TypeScript
+on the Bun runtime (NOT Node.js). Uses Commander.js for CLI argument parsing.
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Install dependencies | `bun install` |
+| Build | `bun run build` or `bun run build.ts` |
+| Run all tests | `bun test` |
+| Run a single test file | `bun test tests/git.test.ts` |
+| Run a single test by name | `bun test --test-name-pattern "pattern"` |
+| Type check (no emit) | `bunx tsc --noEmit` |
+
+No linters or formatters are configured. Build output goes to `dist/` (gitignored).
+
+## Commit Messages
+
+Short, lowercase, descriptive phrases without conventional-commit prefixes:
+- `improved config`
+- `split lib/gitlab.ts into lib/gitlab/*.ts`
+- `fix/update git-lab-merge-*`
+- Version bumps: `v1.6.0`
+
+## Key Files
+
+| Path | Purpose |
+|------|---------|
+| `build.ts` | Bun build script (discovers entry points via glob) |
+| `index.ts` | Barrel export of all lib modules |
+| `lib/spawn.ts` | Process spawning wrapper around Bun.spawn |
+| `lib/git.ts` | Git operations (config, branch, remote) |
+| `lib/jira.ts` | Jira API client |
+| `lib/json.ts` | JSONValue type definition |
+| `lib/is_main.ts` | isMain() helper for dual import/run files |
+| `lib/package.ts` | package.json reading and version extraction |
+| `lib/gitlab/` | GitLab API client (api, config, groups, MRs, pipelines, etc.) |
+| `lib/confluence/` | Confluence API client (api, config, types) |
+| `bin/gitj.ts` | Root CLI entry point aggregating all subcommands |
+
+## Skills
+
+Load the `code-style` skill before writing or editing TypeScript code.
+Load the `architecture` skill when you need to understand CLI design patterns, project structure, or test conventions.
+Load the `git-confluence` skill when working with Confluence pages (searching, reading, or updating content).
+Load the `git-jira` skill when working with Jira issues or the `git-jira` commands.
+Load the `git-lab` skill when working with GitLab projects, merge requests, or the `git-lab` commands.

package/README.md

@@ -1,119 +1,169 @@
-# 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
+```
 
-For example, to see the available top level commands, run `gitj --help`:
+## Install
 
 ```
-$ gitj ---help
-Usage: gitj [options] [command]
+npm install -g ya-git-jira   # or bun / yarn / pnpm
+```
 
-Options:
-  -h, --help  display help for command
+## Configuration
 
-Commands:
-  bump
-  jira        A collection of jira utility commands
-```
+All configuration is via `git config`. Use `--global` if the same settings apply
+across repositories.
 
-## git-jira-start -- Create a new topic branch for work on an issue
+### Jira
 
-#### Usage:
-```bash
-$ git jira-start <issue>
 ```
-
-#### Examples:
-```bash
-$ git jira-start BUG-0042
+git config jira.host yourcompany.atlassian.net
+git config jira.token "<api-token>"
 ```
 
-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`.
+Create an API token: <https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/>
 
-The command does not (yet) change the status of the issue.
+### GitLab
 
-## git-bump -- Create a new branch based on the current branch
+```
+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>
 
-Usage:
-```bash
-$ git bump
+### Confluence
+
+```
+git config confluence.host yourcompany.atlassian.net
+git config confluence.token "<api-token>"
 ```
 
-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.
+The token is an Atlassian API token (same kind as Jira).
 
-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`.
+### Email address
 
-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`.
+Commands fall back to `user.email` from git config. Override per-service if needed:
 
-##  Bun required
+```
+git config jira.user <email>
+git config gitlab.user <email>
+git config confluence.user <email>
+```
 
-This package uses [bun](https://bun.sh) instead of [node](https://nodejs.org/en).
-You must install it before you install this package.
+## Command hierarchy
 
 ```
-$ curl -fsSL https://bun.sh/install | bash
+gitj
+    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
+    lab
+        whoami
+        group
+            list
+        merge
+            active
+            todo
+            train
+                list
+        namespace
+            list
+        project
+            list
+            mr
+                list
+            pipeline
+                jobs
+                latest
+                list
+                log
+            whereami
 ```
 
-## Install with any npm-compatible package manager
+Every leaf command supports `--help`. Run `gitj --help-all` to print the full
+tree with descriptions.
+
+## Noteworthy commands
 
-You can install ya-git-jira via `npm`, or `yarn` or `pnpm` or `bun`.
+### git jira start
 
 ```
-$ npm install -g ya-git-jira
+git jira start BUG-42
 ```
 
-## Configuration
+Fetches the issue summary from Jira, converts it to kebab-case, and creates a
+branch like `BUG-42-fix-the-thing`.
 
-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 `-g` option to the commands below.
+### git bump
 
-### Host
+```
+git bump
+```
 
-You must provide the host name of your Jira cloud service (usually `yourcompany.atlassian.net`) via  `git config`:
+Appends or increments a `.vN` suffix on the current branch name:
+`BUG-42-fix-the-thing` -> `.v1` -> `.v2` -> ...
+
+### git api
 
 ```
-$ git config jira.host yourcompany.atlassian.net
+git api jira /rest/api/3/myself
+git api gitlab /api/v4/user
+git api confluence /wiki/api/v2/spaces
 ```
 
-### API Token
-
-This package requries that you create a API Token (a.k.a. Personal Access Token) for your Atlassian
-account, as described [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
+Make arbitrary authenticated REST calls to any configured service. Useful for
+one-off queries and scripting.
 
-You make the token available to `git-jira` via the `git config` command:
+### gitj install-skills
 
 ```
-$ git config jira.pat "<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
 ```
 
-### Email address
+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.
+
+## AI agent skills
+
+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>`.
 
-`git-jira` also needs the email address associated with your Atlassian account.
-If that email address is the same as your `user.email` setting you don't need to
-add any other configuration. If you use different email addresses for `git` and Atlassian
-then you need to add the email address via `git config` like this:
+## Development
 
 ```
-$ git config jira.email <email-address>
+bun install          # install dependencies
+bun run build        # build to dist/
+bun test             # run all tests
+bunx tsc --noEmit    # type check
 ```