ya-git-jira 1.6.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.