Compare commits
2 Commits
main
...
ff22639dbe
| Author | SHA1 | Date | |
|---|---|---|---|
|
ff22639dbe | ||
|
|
5456ee228b |
7
.gitignore
vendored
7
.gitignore
vendored
@@ -1,7 +0,0 @@
|
|||||||
/ai_plan/
|
|
||||||
/.worktrees/
|
|
||||||
/skills/atlassian/shared/scripts/.env
|
|
||||||
/skills/atlassian/shared/scripts/node_modules/
|
|
||||||
/skills/atlassian/*/scripts/.env
|
|
||||||
/skills/atlassian/*/scripts/node_modules/
|
|
||||||
/skills/web-automation/*/scripts/node_modules/
|
|
||||||
53
README.md
53
README.md
@@ -1,6 +1,6 @@
|
|||||||
# ai-coding-skills
|
# ai-coding-skills
|
||||||
|
|
||||||
Cross-agent skill collection for **Codex**, **Claude Code**, **OpenCode**, and **Cursor**.
|
Cross-agent skill collection for **Codex**, **Claude Code**, and **OpenCode**.
|
||||||
|
|
||||||
This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time.
|
This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time.
|
||||||
|
|
||||||
@@ -15,30 +15,14 @@ This repo is organized similarly to `obra/superpowers` and is designed to scale
|
|||||||
ai-coding-skills/
|
ai-coding-skills/
|
||||||
├── README.md
|
├── README.md
|
||||||
├── docs/
|
├── docs/
|
||||||
│ ├── README.md
|
│ └── install.md
|
||||||
│ ├── ATLASSIAN.md
|
|
||||||
│ ├── CREATE-PLAN.md
|
|
||||||
│ ├── IMPLEMENT-PLAN.md
|
|
||||||
│ └── WEB-AUTOMATION.md
|
|
||||||
├── skills/
|
├── skills/
|
||||||
│ ├── _template/
|
│ ├── _template/
|
||||||
│ │ └── SKILL.md
|
│ │ └── SKILL.md
|
||||||
│ ├── atlassian/
|
|
||||||
│ │ ├── codex/
|
|
||||||
│ │ ├── claude-code/
|
|
||||||
│ │ ├── cursor/
|
|
||||||
│ │ ├── opencode/
|
|
||||||
│ │ └── shared/
|
|
||||||
│ ├── create-plan/
|
│ ├── create-plan/
|
||||||
│ │ ├── codex/
|
│ │ ├── codex/
|
||||||
│ │ ├── claude-code/
|
│ │ ├── claude-code/
|
||||||
│ │ ├── opencode/
|
│ │ └── opencode/
|
||||||
│ │ └── cursor/
|
|
||||||
│ ├── implement-plan/
|
|
||||||
│ │ ├── codex/
|
|
||||||
│ │ ├── claude-code/
|
|
||||||
│ │ ├── opencode/
|
|
||||||
│ │ └── cursor/
|
|
||||||
│ └── web-automation/
|
│ └── web-automation/
|
||||||
│ ├── codex/
|
│ ├── codex/
|
||||||
│ ├── claude-code/
|
│ ├── claude-code/
|
||||||
@@ -54,29 +38,16 @@ ai-coding-skills/
|
|||||||
|
|
||||||
## Skills
|
## Skills
|
||||||
|
|
||||||
| Skill | Agent Variant | Purpose | Status | Docs |
|
| Skill | Agent Variant | Purpose | Status |
|
||||||
|---|---|---|---|---|
|
|---|---|---|---|
|
||||||
| atlassian | codex | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
|
| create-plan | codex | Structured planning with milestones + runbook-first execution workflow | Ready |
|
||||||
| atlassian | claude-code | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
|
| create-plan | claude-code | Structured planning with milestones + runbook-first execution workflow | Ready |
|
||||||
| atlassian | opencode | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
|
| create-plan | opencode | Structured planning with milestones + runbook-first execution workflow | Ready |
|
||||||
| atlassian | cursor | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
|
| web-automation | codex | Playwright + Camoufox browsing/scraping/auth automation | Ready |
|
||||||
| create-plan | codex | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
|
| web-automation | claude-code | Playwright + Camoufox browsing/scraping/auth automation | Ready |
|
||||||
| create-plan | claude-code | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
|
| web-automation | opencode | Playwright + Camoufox browsing/scraping/auth automation | Ready |
|
||||||
| create-plan | opencode | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
|
|
||||||
| create-plan | cursor | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
|
|
||||||
| implement-plan | codex | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
|
|
||||||
| implement-plan | claude-code | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
|
|
||||||
| implement-plan | opencode | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
|
|
||||||
| implement-plan | cursor | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
|
|
||||||
| web-automation | codex | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
|
|
||||||
| web-automation | claude-code | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
|
|
||||||
| web-automation | opencode | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
|
|
||||||
|
|
||||||
- Docs index: `docs/README.md`
|
See install instructions: `docs/install.md`
|
||||||
- Atlassian guide: `docs/ATLASSIAN.md`
|
|
||||||
- Create-plan guide: `docs/CREATE-PLAN.md`
|
|
||||||
- Implement-plan guide: `docs/IMPLEMENT-PLAN.md`
|
|
||||||
- Web-automation guide: `docs/WEB-AUTOMATION.md`
|
|
||||||
|
|
||||||
## Compatibility Policy
|
## Compatibility Policy
|
||||||
|
|
||||||
|
|||||||
@@ -1,156 +0,0 @@
|
|||||||
# ATLASSIAN
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, and OpenCode using one shared CLI surface for common Jira and Confluence workflows.
|
|
||||||
|
|
||||||
## Why This Skill Exists
|
|
||||||
|
|
||||||
The repo targets multiple agent environments with uneven MCP availability. This skill packages a consistent CLI contract so the same task-oriented workflows can be used across all supported agents without depending on MCP-specific integrations.
|
|
||||||
|
|
||||||
The canonical runtime lives in `skills/atlassian/shared/scripts/`. Installable per-agent `scripts/` bundles are generated from that source with:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm --dir skills/atlassian/shared/scripts sync:agents
|
|
||||||
```
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Node.js 20+
|
|
||||||
- `pnpm`
|
|
||||||
- Atlassian Cloud access
|
|
||||||
- `ATLASSIAN_BASE_URL`
|
|
||||||
- `ATLASSIAN_EMAIL`
|
|
||||||
- `ATLASSIAN_API_TOKEN`
|
|
||||||
|
|
||||||
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed agent-specific `scripts/` folder.
|
|
||||||
|
|
||||||
Optional:
|
|
||||||
|
|
||||||
- `ATLASSIAN_JIRA_BASE_URL`
|
|
||||||
- `ATLASSIAN_CONFLUENCE_BASE_URL`
|
|
||||||
- `ATLASSIAN_DEFAULT_PROJECT`
|
|
||||||
- `ATLASSIAN_DEFAULT_SPACE`
|
|
||||||
|
|
||||||
## Supported Commands
|
|
||||||
|
|
||||||
- `health`
|
|
||||||
- `jira-search`
|
|
||||||
- `jira-get`
|
|
||||||
- `jira-create`
|
|
||||||
- `jira-update`
|
|
||||||
- `jira-comment`
|
|
||||||
- `jira-transitions`
|
|
||||||
- `jira-transition`
|
|
||||||
- `conf-search`
|
|
||||||
- `conf-get`
|
|
||||||
- `conf-create`
|
|
||||||
- `conf-update`
|
|
||||||
- `conf-comment`
|
|
||||||
- `conf-children`
|
|
||||||
- `raw`
|
|
||||||
|
|
||||||
## Command Notes
|
|
||||||
|
|
||||||
- `health` validates local configuration, probes Jira and Confluence separately, and reports one product as unavailable without masking the other.
|
|
||||||
- `jira-create` requires `--type`, `--summary`, and either `--project` or `ATLASSIAN_DEFAULT_PROJECT`.
|
|
||||||
- `jira-update` requires `--issue` and at least one of `--summary` or `--description-file`.
|
|
||||||
- `conf-create` requires `--title`, `--body-file`, and either `--space` or `ATLASSIAN_DEFAULT_SPACE`.
|
|
||||||
- `conf-update` requires `--page`, `--title`, and `--body-file`; it fetches the current page version before building the update payload.
|
|
||||||
- `raw --body-file` expects a workspace-scoped JSON file and is limited to validated Atlassian API prefixes.
|
|
||||||
|
|
||||||
## Safety Model
|
|
||||||
|
|
||||||
- Default output is JSON.
|
|
||||||
- Mutating commands support `--dry-run`.
|
|
||||||
- Jira long-text fields are converted to ADF locally.
|
|
||||||
- Confluence page writes are storage-first in v1.
|
|
||||||
- `raw` is restricted to `GET|POST|PUT`.
|
|
||||||
- `--body-file` must stay within the active workspace.
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.codex/skills/atlassian
|
|
||||||
cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
|
|
||||||
cd ~/.codex/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.claude/skills/atlassian
|
|
||||||
cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
|
|
||||||
cd ~/.claude/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/opencode/skills/atlassian
|
|
||||||
cp -R skills/atlassian/opencode/* ~/.config/opencode/skills/atlassian/
|
|
||||||
cd ~/.config/opencode/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cursor
|
|
||||||
|
|
||||||
Repo-local install:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .cursor/skills/atlassian
|
|
||||||
cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
|
|
||||||
cd .cursor/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
Global install:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.cursor/skills/atlassian
|
|
||||||
cp -R skills/atlassian/cursor/* ~/.cursor/skills/atlassian/
|
|
||||||
cd ~/.cursor/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Verify Installation
|
|
||||||
|
|
||||||
Run in the installed `scripts/` folder:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
|
|
||||||
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
|
|
||||||
pnpm atlassian health
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
- Search Jira issues:
|
|
||||||
- `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 25`
|
|
||||||
- Inspect an issue:
|
|
||||||
- `pnpm atlassian jira-get --issue ENG-123`
|
|
||||||
- Dry-run a Jira comment:
|
|
||||||
- `pnpm atlassian jira-comment --issue ENG-123 --body-file comment.md --dry-run`
|
|
||||||
- Dry-run a Jira issue create with default project fallback:
|
|
||||||
- `pnpm atlassian jira-create --type Story --summary "Add Atlassian skill" --description-file story.md --dry-run`
|
|
||||||
- Search Confluence pages:
|
|
||||||
- `pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\"" --max-results 10 --start-at 0`
|
|
||||||
- Inspect a Confluence page:
|
|
||||||
- `pnpm atlassian conf-get --page 12345`
|
|
||||||
- Dry-run a Confluence page update:
|
|
||||||
- `pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run`
|
|
||||||
- Dry-run a Confluence footer comment:
|
|
||||||
- `pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run`
|
|
||||||
- Use bounded raw mode:
|
|
||||||
- `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
|
|
||||||
- `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`
|
|
||||||
|
|
||||||
## Scope Notes
|
|
||||||
|
|
||||||
- Atlassian Cloud is first-class in v1.
|
|
||||||
- Data Center support is future work.
|
|
||||||
- Full `mcp-atlassian` parity is not the goal in v1; the initial scope is the approved core workflow set above.
|
|
||||||
@@ -1,270 +0,0 @@
|
|||||||
# CREATE-PLAN
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Create structured implementation plans with milestone and story tracking, and optionally review them iteratively with a second model/provider before finalizing.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Superpowers skills installed from: https://github.com/obra/superpowers
|
|
||||||
- Required dependencies:
|
|
||||||
- `superpowers:brainstorming`
|
|
||||||
- `superpowers:writing-plans`
|
|
||||||
- For Codex, native skill discovery must be configured:
|
|
||||||
- `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
|
||||||
- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
|
|
||||||
- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
|
|
||||||
- Codex: `~/.codex/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- Claude Code: `~/.claude/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- Cursor: `.cursor/skills/reviewer-runtime/run-review.sh` or `~/.cursor/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- Telegram notification setup is documented in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
|
|
||||||
|
|
||||||
If dependencies are missing, stop and return:
|
|
||||||
|
|
||||||
"Missing dependency: native Superpowers skills are required (`superpowers:brainstorming`, `superpowers:writing-plans`). Install from https://github.com/obra/superpowers, then retry."
|
|
||||||
|
|
||||||
### Reviewer CLI Requirements (Optional)
|
|
||||||
|
|
||||||
To use the iterative plan review feature, one of these CLIs must be installed:
|
|
||||||
|
|
||||||
| Reviewer CLI | Install | Verify |
|
|
||||||
|---|---|---|
|
|
||||||
| `codex` | `npm install -g @openai/codex` | `codex --version` |
|
|
||||||
| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
|
|
||||||
| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) |
|
|
||||||
|
|
||||||
The reviewer CLI is independent of which agent is running the planning — e.g., Claude Code can send plans to Codex for review, and vice versa.
|
|
||||||
|
|
||||||
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.codex/skills/create-plan
|
|
||||||
cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
|
|
||||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.claude/skills/create-plan
|
|
||||||
cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
|
|
||||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/opencode/skills/create-plan
|
|
||||||
cp -R skills/create-plan/opencode/* ~/.config/opencode/skills/create-plan/
|
|
||||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cursor
|
|
||||||
|
|
||||||
Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI discovers skills):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .cursor/skills/create-plan
|
|
||||||
cp -R skills/create-plan/cursor/* .cursor/skills/create-plan/
|
|
||||||
mkdir -p .cursor/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
Or install globally (loaded via `~/.cursor/skills/`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.cursor/skills/create-plan
|
|
||||||
cp -R skills/create-plan/cursor/* ~/.cursor/skills/create-plan/
|
|
||||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Verify Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
test -f ~/.codex/skills/create-plan/SKILL.md || true
|
|
||||||
test -f ~/.claude/skills/create-plan/SKILL.md || true
|
|
||||||
test -f ~/.config/opencode/skills/create-plan/SKILL.md || true
|
|
||||||
test -f .cursor/skills/create-plan/SKILL.md || test -f ~/.cursor/skills/create-plan/SKILL.md || true
|
|
||||||
test -x ~/.codex/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
test -x ~/.claude/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
```
|
|
||||||
|
|
||||||
Verify Superpowers dependencies exist in your agent skills root:
|
|
||||||
|
|
||||||
- Codex: `~/.agents/skills/superpowers/brainstorming/SKILL.md`
|
|
||||||
- Codex: `~/.agents/skills/superpowers/writing-plans/SKILL.md`
|
|
||||||
- Claude Code: `~/.claude/skills/superpowers/brainstorming/SKILL.md`
|
|
||||||
- Claude Code: `~/.claude/skills/superpowers/writing-plans/SKILL.md`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md`
|
|
||||||
- Cursor: `.cursor/skills/superpowers/skills/brainstorming/SKILL.md` or `~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md`
|
|
||||||
- Cursor: `.cursor/skills/superpowers/skills/writing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/writing-plans/SKILL.md`
|
|
||||||
|
|
||||||
## Key Behavior
|
|
||||||
|
|
||||||
- Creates plans under `ai_plan/YYYY-MM-DD-<short-title>/`.
|
|
||||||
- Ensures `/ai_plan/` is in `.gitignore`.
|
|
||||||
- Commits `.gitignore` update locally when added.
|
|
||||||
- Asks which reviewer CLI, model, and max rounds to use (or accepts `skip` for no review).
|
|
||||||
- Iteratively reviews the plan with the chosen reviewer (default max 10 rounds) before generating files.
|
|
||||||
- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
|
|
||||||
- Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
|
|
||||||
- Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
|
|
||||||
- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
|
|
||||||
- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
|
|
||||||
- Produces:
|
|
||||||
- `original-plan.md`
|
|
||||||
- `final-transcript.md`
|
|
||||||
- `milestone-plan.md` — includes Planning Guardrails section
|
|
||||||
- `story-tracker.md` — includes Tracking Guardrails section
|
|
||||||
- `continuation-runbook.md` — includes Skill Workflow Guardrails section
|
|
||||||
|
|
||||||
## Iterative Plan Review
|
|
||||||
|
|
||||||
After the plan is created (design + milestones + stories), the skill sends it to a second model for review:
|
|
||||||
|
|
||||||
1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`), a model, and optional max rounds (default 10), or skips
|
|
||||||
2. **Prepare** — plan payload and a bash reviewer command script are written to temp files
|
|
||||||
3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
|
|
||||||
4. **Feedback** — reviewer evaluates correctness, risks, missing steps, alternatives, security, and returns `## Summary`, `## Findings`, and `## Verdict`
|
|
||||||
5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
|
|
||||||
6. **Revise** — the planning agent addresses findings in priority order and re-submits
|
|
||||||
7. **Repeat** — up to max rounds until the reviewer returns `VERDICT: APPROVED`
|
|
||||||
8. **Finalize** — approved plan is used to generate the plan file package
|
|
||||||
|
|
||||||
### Reviewer Output Contract
|
|
||||||
|
|
||||||
- `P0` = total blocker
|
|
||||||
- `P1` = major risk
|
|
||||||
- `P2` = must-fix before approval
|
|
||||||
- `P3` = cosmetic / nice to have
|
|
||||||
- Each severity section should use `- None.` when empty
|
|
||||||
- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain
|
|
||||||
- `P3` findings are non-blocking, but the caller should still try to fix them when cheap and safe
|
|
||||||
|
|
||||||
### Runtime Artifacts
|
|
||||||
|
|
||||||
The review flow may create these temp artifacts:
|
|
||||||
|
|
||||||
- `/tmp/plan-<id>.md` — plan payload
|
|
||||||
- `/tmp/plan-review-<id>.md` — normalized review text
|
|
||||||
- `/tmp/plan-review-<id>.json` — raw Cursor JSON output
|
|
||||||
- `/tmp/plan-review-<id>.stderr` — reviewer stderr
|
|
||||||
- `/tmp/plan-review-<id>.status` — helper heartbeat/status log
|
|
||||||
- `/tmp/plan-review-<id>.runner.out` — helper-managed stdout from the reviewer command process
|
|
||||||
- `/tmp/plan-review-<id>.sh` — reviewer command script
|
|
||||||
|
|
||||||
Status log lines use this format:
|
|
||||||
|
|
||||||
```text
|
|
||||||
ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-progress|stall-warning|completed|completed-empty-output|failed|needs-operator-decision> elapsed_s=<int> pid=<int> stdout_bytes=<int> stderr_bytes=<int> note="<short message>"
|
|
||||||
```
|
|
||||||
|
|
||||||
`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
|
|
||||||
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
|
|
||||||
|
|
||||||
### Failure Handling
|
|
||||||
|
|
||||||
- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
|
|
||||||
- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
|
|
||||||
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
|
|
||||||
- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
|
|
||||||
|
|
||||||
### Supported Reviewer CLIs
|
|
||||||
|
|
||||||
| CLI | Command | Session Resume | Read-Only Mode |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `codex` | `codex exec -m <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
|
|
||||||
| `claude` | `claude -p --model <model> --strict-mcp-config --setting-sources user` | No (fresh call each round) | `--strict-mcp-config --setting-sources user` |
|
|
||||||
| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--mode=ask` |
|
|
||||||
|
|
||||||
For all three CLIs, the preferred execution path is:
|
|
||||||
|
|
||||||
1. write the reviewer command to a bash script
|
|
||||||
2. run that script through `reviewer-runtime/run-review.sh`
|
|
||||||
3. fall back to direct synchronous execution only if the helper is missing or not executable
|
|
||||||
|
|
||||||
## Notifications
|
|
||||||
|
|
||||||
- Telegram is the only supported notification path.
|
|
||||||
- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
|
|
||||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
|
||||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
|
||||||
|
|
||||||
## Template Guardrails
|
|
||||||
|
|
||||||
All plan templates now include guardrail sections that enforce:
|
|
||||||
|
|
||||||
**Planning Guardrails** (`milestone-plan.md`):
|
|
||||||
- Design validation before implementation planning
|
|
||||||
- Native skill discovery (no deprecated CLI wrappers)
|
|
||||||
- Milestone verification + local commits + explicit approval
|
|
||||||
|
|
||||||
**Tracking Guardrails** (`story-tracker.md`):
|
|
||||||
- Immediate status updates when work starts/completes
|
|
||||||
- Explicit user approval at each milestone boundary
|
|
||||||
- No pushes until all milestones approved
|
|
||||||
- Synchronization between tracker and plan files
|
|
||||||
|
|
||||||
**Skill Workflow Guardrails** (`continuation-runbook.md`):
|
|
||||||
- Native skill invocation before action
|
|
||||||
- Explicit skill announcements
|
|
||||||
- Checklist tracking for driven skills
|
|
||||||
- No deprecated CLI wrappers
|
|
||||||
|
|
||||||
## Variant Hardening Notes
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
- Must invoke explicit required sub-skills:
|
|
||||||
- `superpowers:brainstorming`
|
|
||||||
- `superpowers:writing-plans`
|
|
||||||
- Must enforce plan-mode file-write guard:
|
|
||||||
- if in plan mode, instruct user to exit plan mode before generating files
|
|
||||||
- Must copy `original-plan.md` from `~/.claude/plans/` when available.
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
|
|
||||||
- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
|
||||||
- Must invoke required sub-skills with explicit announcements:
|
|
||||||
- `superpowers:brainstorming` — for design exploration and approach validation
|
|
||||||
- `superpowers:writing-plans` — for milestone and story breakdown
|
|
||||||
- Must track checklist-driven skills with `update_plan` todos.
|
|
||||||
- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
|
|
||||||
- Must verify Superpowers skill discovery under:
|
|
||||||
- `~/.config/opencode/skills/superpowers`
|
|
||||||
- Must explicitly load:
|
|
||||||
- `superpowers/brainstorming`
|
|
||||||
- `superpowers/writing-plans`
|
|
||||||
|
|
||||||
### Cursor
|
|
||||||
|
|
||||||
- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global).
|
|
||||||
- Must announce skill usage explicitly before invocation.
|
|
||||||
- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively.
|
|
||||||
- Must not use `--force` or `--mode=agent` for review (reviewer should never write files).
|
|
||||||
|
|
||||||
## Execution Workflow Rules
|
|
||||||
|
|
||||||
- Read runbook first.
|
|
||||||
- Complete one milestone at a time.
|
|
||||||
- Lint/typecheck/test (changed files first).
|
|
||||||
- Commit (do not push), ask for feedback, apply feedback, commit again.
|
|
||||||
- Move to next milestone only after approval.
|
|
||||||
- Ask permission before final push.
|
|
||||||
@@ -1,275 +0,0 @@
|
|||||||
# IMPLEMENT-PLAN
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. Milestones are implemented one-by-one with lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all are approved.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Plan folder under `ai_plan/` (created by `create-plan`) with:
|
|
||||||
- `continuation-runbook.md`
|
|
||||||
- `milestone-plan.md`
|
|
||||||
- `story-tracker.md`
|
|
||||||
- Git repo with worktree support
|
|
||||||
- Superpowers execution skills installed from: https://github.com/obra/superpowers
|
|
||||||
- Required dependencies:
|
|
||||||
- `superpowers:executing-plans`
|
|
||||||
- `superpowers:using-git-worktrees`
|
|
||||||
- `superpowers:verification-before-completion`
|
|
||||||
- `superpowers:finishing-a-development-branch`
|
|
||||||
- For Codex, native skill discovery must be configured:
|
|
||||||
- `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
|
||||||
- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
|
|
||||||
- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
|
|
||||||
- Codex: `~/.codex/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- Claude Code: `~/.claude/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- Cursor: `.cursor/skills/reviewer-runtime/run-review.sh` or `~/.cursor/skills/reviewer-runtime/run-review.sh`
|
|
||||||
- Telegram notification setup is documented in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
|
|
||||||
|
|
||||||
If dependencies are missing, stop and return:
|
|
||||||
|
|
||||||
"Missing dependency: [specific missing item]. Ensure all prerequisites are met, then retry."
|
|
||||||
|
|
||||||
### Reviewer CLI Requirements (Optional)
|
|
||||||
|
|
||||||
To use the iterative milestone review feature, one of these CLIs must be installed:
|
|
||||||
|
|
||||||
| Reviewer CLI | Install | Verify |
|
|
||||||
|---|---|---|
|
|
||||||
| `codex` | `npm install -g @openai/codex` | `codex --version` |
|
|
||||||
| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
|
|
||||||
| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) |
|
|
||||||
|
|
||||||
The reviewer CLI is independent of which agent is running the implementation — e.g., Claude Code can send milestones to Codex for review, and vice versa.
|
|
||||||
|
|
||||||
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.codex/skills/implement-plan
|
|
||||||
cp -R skills/implement-plan/codex/* ~/.codex/skills/implement-plan/
|
|
||||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.claude/skills/implement-plan
|
|
||||||
cp -R skills/implement-plan/claude-code/* ~/.claude/skills/implement-plan/
|
|
||||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/opencode/skills/implement-plan
|
|
||||||
cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/
|
|
||||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cursor
|
|
||||||
|
|
||||||
Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI discovers skills):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .cursor/skills/implement-plan
|
|
||||||
cp -R skills/implement-plan/cursor/* .cursor/skills/implement-plan/
|
|
||||||
mkdir -p .cursor/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
Or install globally (loaded via `~/.cursor/skills/`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.cursor/skills/implement-plan
|
|
||||||
cp -R skills/implement-plan/cursor/* ~/.cursor/skills/implement-plan/
|
|
||||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Verify Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
test -f ~/.codex/skills/implement-plan/SKILL.md || true
|
|
||||||
test -f ~/.claude/skills/implement-plan/SKILL.md || true
|
|
||||||
test -f ~/.config/opencode/skills/implement-plan/SKILL.md || true
|
|
||||||
test -f .cursor/skills/implement-plan/SKILL.md || test -f ~/.cursor/skills/implement-plan/SKILL.md || true
|
|
||||||
test -x ~/.codex/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
test -x ~/.claude/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh || true
|
|
||||||
```
|
|
||||||
|
|
||||||
Verify Superpowers execution dependencies exist in your agent skills root:
|
|
||||||
|
|
||||||
- Codex: `~/.agents/skills/superpowers/executing-plans/SKILL.md`
|
|
||||||
- Codex: `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md`
|
|
||||||
- Codex: `~/.agents/skills/superpowers/verification-before-completion/SKILL.md`
|
|
||||||
- Codex: `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md`
|
|
||||||
- Claude Code: `~/.claude/skills/superpowers/executing-plans/SKILL.md`
|
|
||||||
- Claude Code: `~/.claude/skills/superpowers/using-git-worktrees/SKILL.md`
|
|
||||||
- Claude Code: `~/.claude/skills/superpowers/verification-before-completion/SKILL.md`
|
|
||||||
- Claude Code: `~/.claude/skills/superpowers/finishing-a-development-branch/SKILL.md`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/superpowers/executing-plans/SKILL.md`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/superpowers/using-git-worktrees/SKILL.md`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md`
|
|
||||||
- Cursor: `.cursor/skills/superpowers/skills/executing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md`
|
|
||||||
- Cursor: `.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md` or `~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`
|
|
||||||
- Cursor: `.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md` or `~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`
|
|
||||||
- Cursor: `.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md` or `~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`
|
|
||||||
|
|
||||||
## Key Behavior
|
|
||||||
|
|
||||||
- Reads existing plan from `ai_plan/YYYY-MM-DD-<short-title>/`.
|
|
||||||
- Sets up an isolated git worktree with branch `implement/<plan-folder-name>`.
|
|
||||||
- Executes milestones one-by-one, tracking stories in `story-tracker.md`.
|
|
||||||
- Runs lint/typecheck/tests as a gate before each milestone review.
|
|
||||||
- Sends each milestone to a reviewer CLI for approval (max rounds configurable, default 10).
|
|
||||||
- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
|
|
||||||
- Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
|
|
||||||
- Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
|
|
||||||
- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
|
|
||||||
- Commits each milestone locally only after reviewer approval (does not push).
|
|
||||||
- After all milestones approved, merges worktree branch to parent and deletes worktree.
|
|
||||||
- Supports resume: detects existing worktree and `in-dev`/`completed` stories.
|
|
||||||
- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
|
|
||||||
|
|
||||||
## Milestone Review Loop
|
|
||||||
|
|
||||||
After each milestone is implemented and verified, the skill sends it to a second model for review:
|
|
||||||
|
|
||||||
1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`) and model, or skips
|
|
||||||
2. **Prepare** — milestone payload and a bash reviewer command script are written to temp files
|
|
||||||
3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
|
|
||||||
4. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage, security, and returns `## Summary`, `## Findings`, and `## Verdict`
|
|
||||||
5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
|
|
||||||
6. **Revise** — the implementing agent addresses findings in priority order, re-verifies, and re-submits
|
|
||||||
7. **Repeat** — up to max rounds (default 10) until the reviewer returns `VERDICT: APPROVED`
|
|
||||||
7. **Approve** — milestone is marked approved in `story-tracker.md`
|
|
||||||
|
|
||||||
### Reviewer Output Contract
|
|
||||||
|
|
||||||
- `P0` = total blocker
|
|
||||||
- `P1` = major risk
|
|
||||||
- `P2` = must-fix before approval
|
|
||||||
- `P3` = cosmetic / nice to have
|
|
||||||
- Each severity section should use `- None.` when empty
|
|
||||||
- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain
|
|
||||||
- `P3` findings are non-blocking, but the caller should still try to fix them when cheap and safe
|
|
||||||
|
|
||||||
### Runtime Artifacts
|
|
||||||
|
|
||||||
The milestone review flow may create these temp artifacts:
|
|
||||||
|
|
||||||
- `/tmp/milestone-<id>.md` — milestone review payload
|
|
||||||
- `/tmp/milestone-review-<id>.md` — normalized review text
|
|
||||||
- `/tmp/milestone-review-<id>.json` — raw Cursor JSON output
|
|
||||||
- `/tmp/milestone-review-<id>.stderr` — reviewer stderr
|
|
||||||
- `/tmp/milestone-review-<id>.status` — helper heartbeat/status log
|
|
||||||
- `/tmp/milestone-review-<id>.runner.out` — helper-managed stdout from the reviewer command process
|
|
||||||
- `/tmp/milestone-review-<id>.sh` — reviewer command script
|
|
||||||
|
|
||||||
Status log lines use this format:
|
|
||||||
|
|
||||||
```text
|
|
||||||
ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-progress|stall-warning|completed|completed-empty-output|failed|needs-operator-decision> elapsed_s=<int> pid=<int> stdout_bytes=<int> stderr_bytes=<int> note="<short message>"
|
|
||||||
```
|
|
||||||
|
|
||||||
`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
|
|
||||||
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
|
|
||||||
|
|
||||||
### Failure Handling
|
|
||||||
|
|
||||||
- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
|
|
||||||
- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
|
|
||||||
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
|
|
||||||
- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
|
|
||||||
|
|
||||||
### Supported Reviewer CLIs
|
|
||||||
|
|
||||||
| CLI | Command | Session Resume | Read-Only Mode |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `codex` | `codex exec -m <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
|
|
||||||
| `claude` | `claude -p --model <model> --strict-mcp-config --setting-sources user` | No (fresh call each round) | `--strict-mcp-config --setting-sources user` |
|
|
||||||
| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--mode=ask` |
|
|
||||||
|
|
||||||
For all three CLIs, the preferred execution path is:
|
|
||||||
|
|
||||||
1. write the reviewer command to a bash script
|
|
||||||
2. run that script through `reviewer-runtime/run-review.sh`
|
|
||||||
3. fall back to direct synchronous execution only if the helper is missing or not executable
|
|
||||||
|
|
||||||
## Notifications
|
|
||||||
|
|
||||||
- Telegram is the only supported notification path.
|
|
||||||
- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
|
|
||||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
|
||||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
|
||||||
|
|
||||||
The helper also supports manual override flags for diagnostics:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
run-review.sh \
|
|
||||||
--command-file <path> \
|
|
||||||
--stdout-file <path> \
|
|
||||||
--stderr-file <path> \
|
|
||||||
--status-file <path> \
|
|
||||||
--poll-seconds 10 \
|
|
||||||
--soft-timeout-seconds 600 \
|
|
||||||
--stall-warning-seconds 300 \
|
|
||||||
--hard-timeout-seconds 1800
|
|
||||||
```
|
|
||||||
|
|
||||||
## Variant Hardening Notes
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
- Must invoke explicit required sub-skills:
|
|
||||||
- `superpowers:executing-plans`
|
|
||||||
- `superpowers:using-git-worktrees`
|
|
||||||
- `superpowers:verification-before-completion`
|
|
||||||
- `superpowers:finishing-a-development-branch`
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
|
|
||||||
- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
|
||||||
- Must invoke required sub-skills with explicit announcements.
|
|
||||||
- Must track checklist-driven skills with `update_plan` todos.
|
|
||||||
- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
|
|
||||||
- Must verify Superpowers skill discovery under:
|
|
||||||
- `~/.config/opencode/skills/superpowers`
|
|
||||||
- Must explicitly load all four execution sub-skills.
|
|
||||||
|
|
||||||
### Cursor
|
|
||||||
|
|
||||||
- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global).
|
|
||||||
- Must announce skill usage explicitly before invocation.
|
|
||||||
- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively.
|
|
||||||
- Must not use `--force` or `--mode=agent` for review (reviewer should never write files).
|
|
||||||
|
|
||||||
## Execution Workflow Rules
|
|
||||||
|
|
||||||
- Read `continuation-runbook.md` first (source of truth).
|
|
||||||
- Set up worktree before any implementation work.
|
|
||||||
- Complete one milestone at a time.
|
|
||||||
- Update `story-tracker.md` before/after each story.
|
|
||||||
- Lint/typecheck/test after each milestone (all must pass).
|
|
||||||
- Send to reviewer for approval before committing.
|
|
||||||
- Address review feedback, re-verify, re-submit (do not commit between rounds).
|
|
||||||
- Commit locally (do not push) only after reviewer approves the milestone.
|
|
||||||
- Move to next milestone only after approval and commit.
|
|
||||||
- After all milestones: run full test suite, merge worktree branch to parent, delete worktree.
|
|
||||||
- Max review rounds default to 10 if user does not specify a value.
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
# Skills Documentation
|
|
||||||
|
|
||||||
This directory contains user-facing docs for each skill.
|
|
||||||
|
|
||||||
## Index
|
|
||||||
|
|
||||||
- [ATLASSIAN.md](./ATLASSIAN.md) — Includes requirements, generated bundle sync, install, auth, safety rules, and usage examples for the Atlassian skill.
|
|
||||||
- [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
|
|
||||||
- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan.
|
|
||||||
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
|
|
||||||
- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.
|
|
||||||
|
|
||||||
## Repo Setup
|
|
||||||
|
|
||||||
Clone the repo first:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://git.fiorinis.com/Home/ai-coding-skills.git
|
|
||||||
cd ai-coding-skills
|
|
||||||
```
|
|
||||||
@@ -1,97 +0,0 @@
|
|||||||
# TELEGRAM-NOTIFICATIONS
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Shared setup for Telegram notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`, both for completion and for pauses that need user attention.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Telegram bot token in `TELEGRAM_BOT_TOKEN`
|
|
||||||
- Telegram chat id in `TELEGRAM_CHAT_ID`
|
|
||||||
- Notification helper installed beside the shared reviewer runtime:
|
|
||||||
- Codex: `~/.codex/skills/reviewer-runtime/notify-telegram.sh`
|
|
||||||
- Claude Code: `~/.claude/skills/reviewer-runtime/notify-telegram.sh`
|
|
||||||
- OpenCode: `~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh`
|
|
||||||
- Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh` or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
The helper ships from `skills/reviewer-runtime/` together with `run-review.sh`.
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cursor
|
|
||||||
|
|
||||||
Repo-local install:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .cursor/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
Global install:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
|
||||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Verify Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
test -x ~/.codex/skills/reviewer-runtime/notify-telegram.sh || true
|
|
||||||
test -x ~/.claude/skills/reviewer-runtime/notify-telegram.sh || true
|
|
||||||
test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh || true
|
|
||||||
test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configure Telegram
|
|
||||||
|
|
||||||
Export the required variables before running a skill that sends Telegram notifications:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export TELEGRAM_BOT_TOKEN="<bot-token>"
|
|
||||||
export TELEGRAM_CHAT_ID="<chat-id>"
|
|
||||||
```
|
|
||||||
|
|
||||||
Optional:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export TELEGRAM_API_BASE_URL="https://api.telegram.org"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Test the Helper
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
TELEGRAM_BOT_TOKEN="<bot-token>" \
|
|
||||||
TELEGRAM_CHAT_ID="<chat-id>" \
|
|
||||||
skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Rules
|
|
||||||
|
|
||||||
- Telegram is the only supported notification path for these skills.
|
|
||||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
|
||||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
|
||||||
- Skills should report when Telegram is not configured instead of silently pretending a notification was sent.
|
|
||||||
@@ -1,133 +0,0 @@
|
|||||||
# WEB-AUTOMATION
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Automate rendered browsing, scraping, authentication, and multi-step browser flows with Playwright-compatible CloakBrowser.
|
|
||||||
|
|
||||||
## What Ships In Every Variant
|
|
||||||
|
|
||||||
- `browse.ts` for direct navigation and screenshots
|
|
||||||
- `auth.ts` for form and Microsoft SSO login flows
|
|
||||||
- `scrape.ts` for markdown extraction
|
|
||||||
- `flow.ts` for natural-language or JSON browser steps
|
|
||||||
- `extract.js` for one-shot rendered JSON extraction
|
|
||||||
- `check-install.js` for install and wiring validation
|
|
||||||
- `scan-local-app.ts` for configurable local-app smoke scans
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Node.js 20+
|
|
||||||
- pnpm
|
|
||||||
- `cloakbrowser`
|
|
||||||
- `playwright-core`
|
|
||||||
- Network access to download the CloakBrowser binary on first use
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
### Codex
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.codex/skills/web-automation
|
|
||||||
cp -R skills/web-automation/codex/* ~/.codex/skills/web-automation/
|
|
||||||
cd ~/.codex/skills/web-automation/scripts
|
|
||||||
pnpm install
|
|
||||||
npx cloakbrowser install
|
|
||||||
pnpm approve-builds
|
|
||||||
pnpm rebuild better-sqlite3 esbuild
|
|
||||||
```
|
|
||||||
|
|
||||||
### Claude Code
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.claude/skills/web-automation
|
|
||||||
cp -R skills/web-automation/claude-code/* ~/.claude/skills/web-automation/
|
|
||||||
cd ~/.claude/skills/web-automation/scripts
|
|
||||||
pnpm install
|
|
||||||
npx cloakbrowser install
|
|
||||||
pnpm approve-builds
|
|
||||||
pnpm rebuild better-sqlite3 esbuild
|
|
||||||
```
|
|
||||||
|
|
||||||
### OpenCode
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/opencode/skills/web-automation
|
|
||||||
cp -R skills/web-automation/opencode/* ~/.config/opencode/skills/web-automation/
|
|
||||||
cd ~/.config/opencode/skills/web-automation/scripts
|
|
||||||
pnpm install
|
|
||||||
npx cloakbrowser install
|
|
||||||
pnpm approve-builds
|
|
||||||
pnpm rebuild better-sqlite3 esbuild
|
|
||||||
```
|
|
||||||
|
|
||||||
## Update To The Latest CloakBrowser
|
|
||||||
|
|
||||||
Run inside the installed `scripts/` directory for the variant you are using:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm up cloakbrowser playwright-core
|
|
||||||
npx cloakbrowser install
|
|
||||||
pnpm approve-builds
|
|
||||||
pnpm rebuild better-sqlite3 esbuild
|
|
||||||
```
|
|
||||||
|
|
||||||
This repo intentionally treats `cloakbrowser` as a refreshable dependency: update to the latest available compatible release, then regenerate the lockfile from that resolved set.
|
|
||||||
|
|
||||||
## Verify Installation & Wiring
|
|
||||||
|
|
||||||
Run in the installed `scripts/` folder:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
node check-install.js
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected checks:
|
|
||||||
|
|
||||||
- `cloakbrowser` and `playwright-core` resolve correctly
|
|
||||||
- `browse.ts` is wired to CloakBrowser
|
|
||||||
|
|
||||||
If the check fails, stop and return:
|
|
||||||
|
|
||||||
"Missing dependency/config: web-automation requires `cloakbrowser` and `playwright-core` with CloakBrowser-based scripts. Run setup in this skill, then retry."
|
|
||||||
|
|
||||||
If runtime later fails with native-binding issues, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm approve-builds
|
|
||||||
pnpm rebuild better-sqlite3 esbuild
|
|
||||||
```
|
|
||||||
|
|
||||||
## Environment Variables
|
|
||||||
|
|
||||||
- `CLOAKBROWSER_PROFILE_PATH`
|
|
||||||
- `CLOAKBROWSER_HEADLESS`
|
|
||||||
- `CLOAKBROWSER_USERNAME`
|
|
||||||
- `CLOAKBROWSER_PASSWORD`
|
|
||||||
|
|
||||||
There are no `CAMOUFOX_*` compatibility aliases in this migration.
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
- Browse: `npx tsx browse.ts --url "https://example.com"`
|
|
||||||
- Scrape markdown: `npx tsx scrape.ts --url "https://example.com" --mode main --output page.md`
|
|
||||||
- Authenticate: `npx tsx auth.ts --url "https://example.com/login"`
|
|
||||||
- Natural-language flow: `npx tsx flow.ts --instruction 'go to https://example.com then click on "Login"'`
|
|
||||||
- JSON extract: `node extract.js "https://example.com"`
|
|
||||||
- Local smoke scan: `SCAN_BASE_URL=http://localhost:3000 SCAN_ROUTES=/,/dashboard npx tsx scan-local-app.ts`
|
|
||||||
|
|
||||||
## Local App Smoke Scan
|
|
||||||
|
|
||||||
`scan-local-app.ts` is generic. Configure it with:
|
|
||||||
|
|
||||||
- `SCAN_BASE_URL`
|
|
||||||
- `SCAN_LOGIN_PATH`
|
|
||||||
- `SCAN_USERNAME`
|
|
||||||
- `SCAN_PASSWORD`
|
|
||||||
- `SCAN_USERNAME_SELECTOR`
|
|
||||||
- `SCAN_PASSWORD_SELECTOR`
|
|
||||||
- `SCAN_SUBMIT_SELECTOR`
|
|
||||||
- `SCAN_ROUTES`
|
|
||||||
- `SCAN_REPORT_PATH`
|
|
||||||
- `SCAN_HEADLESS`
|
|
||||||
|
|
||||||
If `SCAN_USERNAME` or `SCAN_PASSWORD` are omitted, the script falls back to `CLOAKBROWSER_USERNAME` and `CLOAKBROWSER_PASSWORD`.
|
|
||||||
86
docs/install.md
Normal file
86
docs/install.md
Normal file
@@ -0,0 +1,86 @@
|
|||||||
|
# Installation
|
||||||
|
|
||||||
|
Install from this repo similarly to superpowers: clone once, then copy/symlink agent-specific skills.
|
||||||
|
|
||||||
|
## 1) Clone
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.fiorinis.com/Home/ai-coding-skills.git
|
||||||
|
cd ai-coding-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2) Install `create-plan`
|
||||||
|
|
||||||
|
### Codex
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.codex/skills/create-plan
|
||||||
|
cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude Code
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.claude/skills/create-plan
|
||||||
|
cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
|
||||||
|
```
|
||||||
|
|
||||||
|
### OpenCode
|
||||||
|
|
||||||
|
Use your OpenCode skills/plugin path and copy the opencode variant.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Example path (adjust for your environment)
|
||||||
|
mkdir -p ~/.opencode/skills/create-plan
|
||||||
|
cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3) Install `web-automation`
|
||||||
|
|
||||||
|
### Codex
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.codex/skills/web-automation
|
||||||
|
cp -R skills/web-automation/codex/* ~/.codex/skills/web-automation/
|
||||||
|
cd ~/.codex/skills/web-automation/scripts
|
||||||
|
pnpm install
|
||||||
|
npx camoufox-js fetch
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude Code
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.claude/skills/web-automation
|
||||||
|
cp -R skills/web-automation/claude-code/* ~/.claude/skills/web-automation/
|
||||||
|
cd ~/.claude/skills/web-automation/scripts
|
||||||
|
pnpm install
|
||||||
|
npx camoufox-js fetch
|
||||||
|
```
|
||||||
|
|
||||||
|
### OpenCode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p ~/.opencode/skills/web-automation
|
||||||
|
cp -R skills/web-automation/opencode/* ~/.opencode/skills/web-automation/
|
||||||
|
cd ~/.opencode/skills/web-automation/scripts
|
||||||
|
pnpm install
|
||||||
|
npx camoufox-js fetch
|
||||||
|
```
|
||||||
|
|
||||||
|
Requirements for `web-automation`:
|
||||||
|
- Node.js 20+
|
||||||
|
- pnpm
|
||||||
|
- Browser download/network access for Camoufox
|
||||||
|
|
||||||
|
## 4) Verify
|
||||||
|
|
||||||
|
- Ensure `SKILL.md` exists in the destination folder.
|
||||||
|
- Ensure `templates/` files (create-plan) or `scripts/` files (web-automation) are present.
|
||||||
|
- Start a new agent session and ask:
|
||||||
|
- "create a plan for ..." (create-plan)
|
||||||
|
- "scrape this page ..." (web-automation)
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- `docs/plans` / `docs/plan` can be gitignored by design.
|
||||||
|
- Plan artifacts are intentionally local.
|
||||||
@@ -1,78 +0,0 @@
|
|||||||
---
|
|
||||||
name: atlassian
|
|
||||||
description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Atlassian (Claude Code)
|
|
||||||
|
|
||||||
Portable Atlassian workflows for Claude Code using a shared TypeScript CLI.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Node.js 20+
|
|
||||||
- `pnpm`
|
|
||||||
- Atlassian Cloud account access
|
|
||||||
- `ATLASSIAN_BASE_URL`
|
|
||||||
- `ATLASSIAN_EMAIL`
|
|
||||||
- `ATLASSIAN_API_TOKEN`
|
|
||||||
|
|
||||||
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in `~/.claude/skills/atlassian/scripts`.
|
|
||||||
|
|
||||||
## First-Time Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.claude/skills/atlassian
|
|
||||||
cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
|
|
||||||
cd ~/.claude/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd ~/.claude/skills/atlassian/scripts
|
|
||||||
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
|
|
||||||
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
|
|
||||||
pnpm atlassian health
|
|
||||||
```
|
|
||||||
|
|
||||||
If any check fails, stop and return:
|
|
||||||
|
|
||||||
`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
|
|
||||||
|
|
||||||
## Supported Commands
|
|
||||||
|
|
||||||
- `pnpm atlassian health`
|
|
||||||
- `pnpm atlassian jira-search --jql "..."`
|
|
||||||
- `pnpm atlassian jira-get --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-transitions --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-transition ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-search --query "..."`
|
|
||||||
- `pnpm atlassian conf-get --page 12345`
|
|
||||||
- `pnpm atlassian conf-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-children --page 12345`
|
|
||||||
- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
- `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 10`
|
|
||||||
- `pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run`
|
|
||||||
- `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
|
|
||||||
|
|
||||||
## Safety Rules
|
|
||||||
|
|
||||||
- Default output is JSON; only switch to text output when the user needs a human-readable summary.
|
|
||||||
- Use `--dry-run` before any write unless the user clearly asked for the mutation.
|
|
||||||
- Treat `raw` as an escape hatch, not the default API surface.
|
|
||||||
- `--body-file` must stay inside the current workspace.
|
|
||||||
- Confluence write bodies should be storage-format inputs in v1.
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Atlassian Cloud is the primary supported platform in v1.
|
|
||||||
- The portable CLI exists so the same skill works consistently across multiple agent environments.
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
{
|
|
||||||
"name": "atlassian-skill-scripts",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"description": "Shared runtime for the Atlassian skill",
|
|
||||||
"type": "module",
|
|
||||||
"scripts": {
|
|
||||||
"atlassian": "tsx src/cli.ts",
|
|
||||||
"typecheck": "tsc --noEmit"
|
|
||||||
},
|
|
||||||
"dependencies": {
|
|
||||||
"commander": "^13.1.0",
|
|
||||||
"dotenv": "^16.4.7"
|
|
||||||
},
|
|
||||||
"devDependencies": {
|
|
||||||
"@types/node": "^24.3.0",
|
|
||||||
"tsx": "^4.20.5",
|
|
||||||
"typescript": "^5.9.2"
|
|
||||||
},
|
|
||||||
"packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
|
|
||||||
}
|
|
||||||
361
skills/atlassian/claude-code/scripts/pnpm-lock.yaml
generated
361
skills/atlassian/claude-code/scripts/pnpm-lock.yaml
generated
@@ -1,361 +0,0 @@
|
|||||||
lockfileVersion: '9.0'
|
|
||||||
|
|
||||||
settings:
|
|
||||||
autoInstallPeers: true
|
|
||||||
excludeLinksFromLockfile: false
|
|
||||||
|
|
||||||
importers:
|
|
||||||
|
|
||||||
.:
|
|
||||||
dependencies:
|
|
||||||
commander:
|
|
||||||
specifier: ^13.1.0
|
|
||||||
version: 13.1.0
|
|
||||||
dotenv:
|
|
||||||
specifier: ^16.4.7
|
|
||||||
version: 16.6.1
|
|
||||||
devDependencies:
|
|
||||||
'@types/node':
|
|
||||||
specifier: ^24.3.0
|
|
||||||
version: 24.12.0
|
|
||||||
tsx:
|
|
||||||
specifier: ^4.20.5
|
|
||||||
version: 4.21.0
|
|
||||||
typescript:
|
|
||||||
specifier: ^5.9.2
|
|
||||||
version: 5.9.3
|
|
||||||
|
|
||||||
packages:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [aix]
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [loong64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [mips64el]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [riscv64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [s390x]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openharmony]
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [sunos]
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
|
|
||||||
|
|
||||||
commander@13.1.0:
|
|
||||||
resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
|
|
||||||
dotenv@16.6.1:
|
|
||||||
resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
|
|
||||||
engines: {node: '>=12'}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
|
|
||||||
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0:
|
|
||||||
resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
|
|
||||||
engines: {node: '>=18.0.0'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
typescript@5.9.3:
|
|
||||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
|
||||||
engines: {node: '>=14.17'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
undici-types@7.16.0:
|
|
||||||
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
|
|
||||||
|
|
||||||
snapshots:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
dependencies:
|
|
||||||
undici-types: 7.16.0
|
|
||||||
|
|
||||||
commander@13.1.0: {}
|
|
||||||
|
|
||||||
dotenv@16.6.1: {}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
optionalDependencies:
|
|
||||||
'@esbuild/aix-ppc64': 0.27.3
|
|
||||||
'@esbuild/android-arm': 0.27.3
|
|
||||||
'@esbuild/android-arm64': 0.27.3
|
|
||||||
'@esbuild/android-x64': 0.27.3
|
|
||||||
'@esbuild/darwin-arm64': 0.27.3
|
|
||||||
'@esbuild/darwin-x64': 0.27.3
|
|
||||||
'@esbuild/freebsd-arm64': 0.27.3
|
|
||||||
'@esbuild/freebsd-x64': 0.27.3
|
|
||||||
'@esbuild/linux-arm': 0.27.3
|
|
||||||
'@esbuild/linux-arm64': 0.27.3
|
|
||||||
'@esbuild/linux-ia32': 0.27.3
|
|
||||||
'@esbuild/linux-loong64': 0.27.3
|
|
||||||
'@esbuild/linux-mips64el': 0.27.3
|
|
||||||
'@esbuild/linux-ppc64': 0.27.3
|
|
||||||
'@esbuild/linux-riscv64': 0.27.3
|
|
||||||
'@esbuild/linux-s390x': 0.27.3
|
|
||||||
'@esbuild/linux-x64': 0.27.3
|
|
||||||
'@esbuild/netbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/netbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/openbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openharmony-arm64': 0.27.3
|
|
||||||
'@esbuild/sunos-x64': 0.27.3
|
|
||||||
'@esbuild/win32-arm64': 0.27.3
|
|
||||||
'@esbuild/win32-ia32': 0.27.3
|
|
||||||
'@esbuild/win32-x64': 0.27.3
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
dependencies:
|
|
||||||
resolve-pkg-maps: 1.0.0
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0: {}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
dependencies:
|
|
||||||
esbuild: 0.27.3
|
|
||||||
get-tsconfig: 4.13.6
|
|
||||||
optionalDependencies:
|
|
||||||
fsevents: 2.3.3
|
|
||||||
|
|
||||||
typescript@5.9.3: {}
|
|
||||||
|
|
||||||
undici-types@7.16.0: {}
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
const TEXT_NODE = "text";
|
|
||||||
|
|
||||||
function textNode(text: string) {
|
|
||||||
return {
|
|
||||||
type: TEXT_NODE,
|
|
||||||
text,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function paragraphNode(lines: string[]) {
|
|
||||||
const content: Array<{ type: string; text?: string }> = [];
|
|
||||||
|
|
||||||
lines.forEach((line, index) => {
|
|
||||||
if (index > 0) {
|
|
||||||
content.push({ type: "hardBreak" });
|
|
||||||
}
|
|
||||||
|
|
||||||
if (line.length > 0) {
|
|
||||||
content.push(textNode(line));
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "paragraph",
|
|
||||||
...(content.length > 0 ? { content } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function markdownToAdf(input: string) {
|
|
||||||
const lines = input.replace(/\r\n/g, "\n").split("\n");
|
|
||||||
const content: Array<Record<string, unknown>> = [];
|
|
||||||
let index = 0;
|
|
||||||
|
|
||||||
while (index < lines.length) {
|
|
||||||
const current = lines[index]?.trimEnd() ?? "";
|
|
||||||
|
|
||||||
if (current.trim().length === 0) {
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const heading = current.match(/^(#{1,6})\s+(.*)$/);
|
|
||||||
|
|
||||||
if (heading) {
|
|
||||||
content.push({
|
|
||||||
type: "heading",
|
|
||||||
attrs: { level: heading[1].length },
|
|
||||||
content: [textNode(heading[2])],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (/^[-*]\s+/.test(current)) {
|
|
||||||
const items: Array<Record<string, unknown>> = [];
|
|
||||||
|
|
||||||
while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
|
|
||||||
items.push({
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push({
|
|
||||||
type: "bulletList",
|
|
||||||
content: items,
|
|
||||||
});
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const paragraphLines: string[] = [];
|
|
||||||
|
|
||||||
while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
|
|
||||||
paragraphLines.push(lines[index] ?? "");
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push(paragraphNode(paragraphLines));
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "doc",
|
|
||||||
version: 1,
|
|
||||||
content,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,332 +0,0 @@
|
|||||||
import process from "node:process";
|
|
||||||
import { pathToFileURL } from "node:url";
|
|
||||||
|
|
||||||
import { Command } from "commander";
|
|
||||||
|
|
||||||
import { createConfluenceClient } from "./confluence.js";
|
|
||||||
import { loadConfig } from "./config.js";
|
|
||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { runHealthCheck } from "./health.js";
|
|
||||||
import { createJiraClient } from "./jira.js";
|
|
||||||
import { writeOutput } from "./output.js";
|
|
||||||
import { runRawCommand } from "./raw.js";
|
|
||||||
import type { FetchLike, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
type CliContext = {
|
|
||||||
cwd?: string;
|
|
||||||
env?: NodeJS.ProcessEnv;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
stdout?: Writer;
|
|
||||||
stderr?: Writer;
|
|
||||||
};
|
|
||||||
|
|
||||||
function resolveFormat(format: string | undefined): OutputFormat {
|
|
||||||
return format === "text" ? "text" : "json";
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRuntime(context: CliContext) {
|
|
||||||
const cwd = context.cwd ?? process.cwd();
|
|
||||||
const env = context.env ?? process.env;
|
|
||||||
const stdout = context.stdout ?? process.stdout;
|
|
||||||
const stderr = context.stderr ?? process.stderr;
|
|
||||||
let configCache: ReturnType<typeof loadConfig> | undefined;
|
|
||||||
let jiraCache: ReturnType<typeof createJiraClient> | undefined;
|
|
||||||
let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
|
|
||||||
|
|
||||||
function getConfig() {
|
|
||||||
configCache ??= loadConfig(env, { cwd });
|
|
||||||
return configCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getJiraClient() {
|
|
||||||
jiraCache ??= createJiraClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return jiraCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getConfluenceClient() {
|
|
||||||
confluenceCache ??= createConfluenceClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return confluenceCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readBodyFile(filePath: string | undefined) {
|
|
||||||
if (!filePath) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
return readWorkspaceFile(filePath, cwd);
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
cwd,
|
|
||||||
stdout,
|
|
||||||
stderr,
|
|
||||||
readBodyFile,
|
|
||||||
getConfig,
|
|
||||||
getJiraClient,
|
|
||||||
getConfluenceClient,
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function buildProgram(context: CliContext = {}) {
|
|
||||||
const runtime = createRuntime(context);
|
|
||||||
const program = new Command()
|
|
||||||
.name("atlassian")
|
|
||||||
.description("Portable Atlassian CLI for multi-agent skills")
|
|
||||||
.version("0.1.0");
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("health")
|
|
||||||
.description("Validate configuration and Atlassian connectivity")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
|
|
||||||
writeOutput(
|
|
||||||
runtime.stdout,
|
|
||||||
payload,
|
|
||||||
resolveFormat(options.format),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-search")
|
|
||||||
.requiredOption("--query <query>", "CQL search query")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().searchPages({
|
|
||||||
query: options.query,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-get")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().getPage(options.page);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-create")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--space <space>", "Confluence space ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().createPage({
|
|
||||||
space: options.space,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-update")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().updatePage({
|
|
||||||
pageId: options.page,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-comment")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().commentPage({
|
|
||||||
pageId: options.page,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-children")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Cursor/start token", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().listChildren(
|
|
||||||
options.page,
|
|
||||||
Number(options.maxResults),
|
|
||||||
Number(options.startAt),
|
|
||||||
);
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("raw")
|
|
||||||
.requiredOption("--product <product>", "jira or confluence")
|
|
||||||
.requiredOption("--method <method>", "GET, POST, or PUT")
|
|
||||||
.requiredOption("--path <path>", "Validated API path")
|
|
||||||
.option("--body-file <path>", "Workspace-relative JSON file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
|
|
||||||
product: options.product,
|
|
||||||
method: String(options.method).toUpperCase(),
|
|
||||||
path: options.path,
|
|
||||||
bodyFile: options.bodyFile,
|
|
||||||
cwd: runtime.cwd,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-search")
|
|
||||||
.requiredOption("--jql <jql>", "JQL expression to execute")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().searchIssues({
|
|
||||||
jql: options.jql,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-get")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getIssue(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-create")
|
|
||||||
.requiredOption("--type <type>", "Issue type name")
|
|
||||||
.requiredOption("--summary <summary>", "Issue summary")
|
|
||||||
.option("--project <project>", "Project key")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().createIssue({
|
|
||||||
project: options.project,
|
|
||||||
type: options.type,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-update")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--summary <summary>", "Updated summary")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().updateIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-comment")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().commentIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transitions")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getTransitions(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transition")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--transition <transition>", "Transition ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().transitionIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
transition: options.transition,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
return program;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runCli(argv = process.argv, context: CliContext = {}) {
|
|
||||||
const program = buildProgram(context);
|
|
||||||
await program.parseAsync(argv);
|
|
||||||
}
|
|
||||||
|
|
||||||
const isDirectExecution =
|
|
||||||
Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
|
|
||||||
|
|
||||||
if (isDirectExecution) {
|
|
||||||
runCli().catch((error: unknown) => {
|
|
||||||
const message = error instanceof Error ? error.message : String(error);
|
|
||||||
process.stderr.write(`${message}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
import path from "node:path";
|
|
||||||
|
|
||||||
import { config as loadDotEnv } from "dotenv";
|
|
||||||
|
|
||||||
import type { AtlassianConfig } from "./types.js";
|
|
||||||
|
|
||||||
function normalizeBaseUrl(value: string) {
|
|
||||||
return value.replace(/\/+$/, "");
|
|
||||||
}
|
|
||||||
|
|
||||||
function readRequired(env: NodeJS.ProcessEnv, key: string) {
|
|
||||||
const value = env[key]?.trim();
|
|
||||||
|
|
||||||
if (!value) {
|
|
||||||
throw new Error(`Missing required environment variable: ${key}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return value;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function loadConfig(
|
|
||||||
env: NodeJS.ProcessEnv = process.env,
|
|
||||||
options?: {
|
|
||||||
cwd?: string;
|
|
||||||
},
|
|
||||||
): AtlassianConfig {
|
|
||||||
loadDotEnv({
|
|
||||||
path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
|
|
||||||
processEnv: env as Record<string, string>,
|
|
||||||
override: false,
|
|
||||||
});
|
|
||||||
|
|
||||||
const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
baseUrl,
|
|
||||||
jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
|
|
||||||
confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
|
|
||||||
email: readRequired(env, "ATLASSIAN_EMAIL"),
|
|
||||||
apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
|
|
||||||
defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
|
|
||||||
defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createBasicAuthHeader(config: {
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
[key: string]: unknown;
|
|
||||||
}) {
|
|
||||||
return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
|
|
||||||
}
|
|
||||||
@@ -1,292 +0,0 @@
|
|||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ConfluenceClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
query: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
space?: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
pageId: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
pageId: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type PageSummary = {
|
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
type: string;
|
|
||||||
status?: string;
|
|
||||||
spaceId?: string;
|
|
||||||
url?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
|
|
||||||
const links = (page._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
id: String(page.id ?? ""),
|
|
||||||
title: String(page.title ?? ""),
|
|
||||||
type: String(page.type ?? "page"),
|
|
||||||
...(page.status ? { status: String(page.status) } : {}),
|
|
||||||
...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
|
|
||||||
...(excerpt ? { excerpt } : {}),
|
|
||||||
...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createConfluenceClient(options: ConfluenceClientOptions) {
|
|
||||||
const config = options.config;
|
|
||||||
|
|
||||||
async function getPageForUpdate(pageId: string) {
|
|
||||||
return (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("cql", input.query);
|
|
||||||
url.searchParams.set("limit", String(input.maxResults));
|
|
||||||
url.searchParams.set("start", String(input.startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((entry) => {
|
|
||||||
const result = entry as Record<string, unknown>;
|
|
||||||
return normalizePage(
|
|
||||||
config.baseUrl,
|
|
||||||
(result.content ?? {}) as Record<string, unknown>,
|
|
||||||
result.excerpt ? String(result.excerpt) : undefined,
|
|
||||||
);
|
|
||||||
}),
|
|
||||||
startAt: Number(raw.start ?? input.startAt),
|
|
||||||
maxResults: Number(raw.limit ?? input.maxResults),
|
|
||||||
total: Number(raw.totalSize ?? raw.size ?? results.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getPage(pageId: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
page: {
|
|
||||||
...normalizePage(config.baseUrl, raw),
|
|
||||||
version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
|
|
||||||
body: body?.value ? String(body.value) : "",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("limit", String(maxResults));
|
|
||||||
url.searchParams.set("cursor", String(startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
const links = (raw._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
|
|
||||||
nextCursor: links.next ? String(links.next) : null,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const spaceId = input.space || config.defaultSpace;
|
|
||||||
|
|
||||||
if (!spaceId) {
|
|
||||||
throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
|
|
||||||
body: {
|
|
||||||
spaceId,
|
|
||||||
title: input.title,
|
|
||||||
status: "current",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const currentPage = await getPageForUpdate(input.pageId);
|
|
||||||
const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
|
|
||||||
const spaceId = String(currentPage.spaceId ?? "");
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "PUT" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
|
|
||||||
body: {
|
|
||||||
id: input.pageId,
|
|
||||||
status: String(currentPage.status ?? "current"),
|
|
||||||
title: input.title,
|
|
||||||
spaceId,
|
|
||||||
version: {
|
|
||||||
number: Number(version) + 1,
|
|
||||||
},
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
handleResponseError(response) {
|
|
||||||
if (response.status === 409) {
|
|
||||||
return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return undefined;
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
|
|
||||||
body: {
|
|
||||||
pageId: input.pageId,
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
import { readFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
export async function readWorkspaceFile(filePath: string, cwd: string) {
|
|
||||||
const resolved = path.resolve(cwd, filePath);
|
|
||||||
const relative = path.relative(cwd, resolved);
|
|
||||||
|
|
||||||
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
|
||||||
throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return readFile(resolved, "utf8");
|
|
||||||
}
|
|
||||||
@@ -1,69 +0,0 @@
|
|||||||
import { createJsonHeaders, createStatusError } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ProductHealth = {
|
|
||||||
ok: boolean;
|
|
||||||
status?: number;
|
|
||||||
message?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runHealthCheck(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
const client = fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!client) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
|
|
||||||
try {
|
|
||||||
const response = await client(url, {
|
|
||||||
method: "GET",
|
|
||||||
headers: createJsonHeaders(config, false),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const error = createStatusError(`${product} health check failed`, response);
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
status: response.status,
|
|
||||||
message: error.message,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
status: response.status,
|
|
||||||
};
|
|
||||||
} catch (error: unknown) {
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
message: error instanceof Error ? error.message : String(error),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
|
|
||||||
const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: jira.ok && confluence.ok,
|
|
||||||
data: {
|
|
||||||
baseUrl: config.baseUrl,
|
|
||||||
jiraBaseUrl: config.jiraBaseUrl,
|
|
||||||
confluenceBaseUrl: config.confluenceBaseUrl,
|
|
||||||
defaultProject: config.defaultProject,
|
|
||||||
defaultSpace: config.defaultSpace,
|
|
||||||
products: {
|
|
||||||
jira,
|
|
||||||
confluence,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
import { createBasicAuthHeader } from "./config.js";
|
|
||||||
import type { AtlassianConfig, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
export type HttpMethod = "GET" | "POST" | "PUT";
|
|
||||||
|
|
||||||
export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
|
|
||||||
const headers: Array<[string, string]> = [
|
|
||||||
["Accept", "application/json"],
|
|
||||||
["Authorization", createBasicAuthHeader(config)],
|
|
||||||
];
|
|
||||||
|
|
||||||
if (includeJsonBody) {
|
|
||||||
headers.push(["Content-Type", "application/json"]);
|
|
||||||
}
|
|
||||||
|
|
||||||
return headers;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function parseResponse(response: Response) {
|
|
||||||
if (response.status === 204) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contentType = response.headers.get("content-type") ?? "";
|
|
||||||
|
|
||||||
if (contentType.includes("application/json")) {
|
|
||||||
try {
|
|
||||||
return await response.json();
|
|
||||||
} catch {
|
|
||||||
throw new Error("Malformed JSON response from Atlassian API");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return response.text();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createStatusError(errorPrefix: string, response: Response) {
|
|
||||||
const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
|
|
||||||
|
|
||||||
switch (response.status) {
|
|
||||||
case 401:
|
|
||||||
return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
|
|
||||||
case 403:
|
|
||||||
return new Error(`${base} - verify product permissions for this account`);
|
|
||||||
case 404:
|
|
||||||
return new Error(`${base} - verify the resource identifier or API path`);
|
|
||||||
case 429:
|
|
||||||
return new Error(`${base} - retry later or reduce request rate`);
|
|
||||||
default:
|
|
||||||
return new Error(base);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function sendJsonRequest(options: {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
url: string;
|
|
||||||
method: HttpMethod;
|
|
||||||
body?: unknown;
|
|
||||||
errorPrefix: string;
|
|
||||||
handleResponseError?: (response: Response) => Error | undefined;
|
|
||||||
}) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await fetchImpl(options.url, {
|
|
||||||
method: options.method,
|
|
||||||
headers: createJsonHeaders(options.config, options.body !== undefined),
|
|
||||||
...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const customError = options.handleResponseError?.(response);
|
|
||||||
|
|
||||||
if (customError) {
|
|
||||||
throw customError;
|
|
||||||
}
|
|
||||||
|
|
||||||
throw createStatusError(options.errorPrefix, response);
|
|
||||||
}
|
|
||||||
|
|
||||||
return parseResponse(response);
|
|
||||||
}
|
|
||||||
@@ -1,264 +0,0 @@
|
|||||||
import { markdownToAdf } from "./adf.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
|
|
||||||
|
|
||||||
const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
|
|
||||||
|
|
||||||
type JiraClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
jql: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
project?: string;
|
|
||||||
type: string;
|
|
||||||
summary: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
issue: string;
|
|
||||||
summary?: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
issue: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type TransitionInput = {
|
|
||||||
issue: string;
|
|
||||||
transition: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
|
|
||||||
const fields = (issue.fields ?? {}) as Record<string, unknown>;
|
|
||||||
const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
|
|
||||||
const status = (fields.status ?? {}) as Record<string, unknown>;
|
|
||||||
const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
key: String(issue.key ?? ""),
|
|
||||||
summary: String(fields.summary ?? ""),
|
|
||||||
issueType: String(issueType.name ?? ""),
|
|
||||||
status: String(status.name ?? ""),
|
|
||||||
assignee: assignee.displayName ? String(assignee.displayName) : undefined,
|
|
||||||
created: String(fields.created ?? ""),
|
|
||||||
updated: String(fields.updated ?? ""),
|
|
||||||
url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const url = new URL(path, `${config.jiraBaseUrl}/`);
|
|
||||||
|
|
||||||
return {
|
|
||||||
method,
|
|
||||||
url: url.toString(),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createJiraClient(options: JiraClientOptions) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const request = createRequest(options.config, method, path, body);
|
|
||||||
return sendJsonRequest({
|
|
||||||
config: options.config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send("POST", "/rest/api/3/search", {
|
|
||||||
jql: input.jql,
|
|
||||||
maxResults: input.maxResults,
|
|
||||||
startAt: input.startAt,
|
|
||||||
fields: [...ISSUE_FIELDS],
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const issues = Array.isArray(raw.issues) ? raw.issues : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
|
|
||||||
startAt: Number(raw.startAt ?? input.startAt),
|
|
||||||
maxResults: Number(raw.maxResults ?? input.maxResults),
|
|
||||||
total: Number(raw.total ?? issues.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getIssue(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
|
|
||||||
url.searchParams.set("fields", ISSUE_FIELDS.join(","));
|
|
||||||
|
|
||||||
const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: normalizeIssue(options.config, raw),
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send(
|
|
||||||
"GET",
|
|
||||||
`/rest/api/3/issue/${issue}/transitions`,
|
|
||||||
)) as { transitions?: Array<Record<string, unknown>> };
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
transitions: (raw.transitions ?? []).map((transition) => ({
|
|
||||||
id: String(transition.id ?? ""),
|
|
||||||
name: String(transition.name ?? ""),
|
|
||||||
toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
|
|
||||||
hasScreen: Boolean(transition.hasScreen),
|
|
||||||
})),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const project = input.project || options.config.defaultProject;
|
|
||||||
|
|
||||||
if (!project) {
|
|
||||||
throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
|
|
||||||
fields: {
|
|
||||||
project: { key: project },
|
|
||||||
issuetype: { name: input.type },
|
|
||||||
summary: input.summary,
|
|
||||||
...(input.description ? { description: markdownToAdf(input.description) } : {}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", "/rest/api/3/issue", request.body);
|
|
||||||
return { ok: true, data: raw };
|
|
||||||
},
|
|
||||||
|
|
||||||
async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const fields: Record<string, unknown> = {};
|
|
||||||
|
|
||||||
if (input.summary) {
|
|
||||||
fields.summary = input.summary;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (input.description) {
|
|
||||||
fields.description = markdownToAdf(input.description);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Object.keys(fields).length === 0) {
|
|
||||||
throw new Error("jira-update requires --summary and/or --description-file");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
|
|
||||||
fields,
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
updated: true,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
|
|
||||||
body: markdownToAdf(input.body),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(
|
|
||||||
options.config,
|
|
||||||
"POST",
|
|
||||||
`/rest/api/3/issue/${input.issue}/transitions`,
|
|
||||||
{
|
|
||||||
transition: {
|
|
||||||
id: input.transition,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
);
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
transitioned: true,
|
|
||||||
transition: input.transition,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
import type { CommandOutput, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
function renderText(payload: CommandOutput<unknown>) {
|
|
||||||
const data = payload.data as Record<string, unknown>;
|
|
||||||
|
|
||||||
if (Array.isArray(data?.issues)) {
|
|
||||||
return data.issues
|
|
||||||
.map((issue) => {
|
|
||||||
const item = issue as Record<string, string>;
|
|
||||||
return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (data?.issue && typeof data.issue === "object") {
|
|
||||||
const issue = data.issue as Record<string, string>;
|
|
||||||
return [
|
|
||||||
issue.key,
|
|
||||||
`${issue.issueType} | ${issue.status}`,
|
|
||||||
issue.summary,
|
|
||||||
issue.url,
|
|
||||||
].join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Array.isArray(data?.transitions)) {
|
|
||||||
return data.transitions
|
|
||||||
.map((transition) => {
|
|
||||||
const item = transition as Record<string, string>;
|
|
||||||
return `${item.id} ${item.name} -> ${item.toStatus}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
return JSON.stringify(payload, null, 2);
|
|
||||||
}
|
|
||||||
|
|
||||||
export function writeOutput(
|
|
||||||
writer: Writer,
|
|
||||||
payload: CommandOutput<unknown>,
|
|
||||||
format: OutputFormat = "json",
|
|
||||||
) {
|
|
||||||
const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
|
|
||||||
writer.write(`${body}\n`);
|
|
||||||
}
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
|
|
||||||
const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
|
|
||||||
|
|
||||||
type RawInput = {
|
|
||||||
product: "jira" | "confluence";
|
|
||||||
method: string;
|
|
||||||
path: string;
|
|
||||||
bodyFile?: string;
|
|
||||||
cwd: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function getAllowedPrefixes(product: RawInput["product"]) {
|
|
||||||
return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
|
|
||||||
const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
|
|
||||||
if (!["GET", "POST", "PUT"].includes(method)) {
|
|
||||||
throw new Error("raw only allows GET, POST, and PUT");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function validatePath(product: RawInput["product"], path: string) {
|
|
||||||
const allowedPrefixes = getAllowedPrefixes(product);
|
|
||||||
|
|
||||||
if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
|
|
||||||
throw new Error(`raw path is not allowed for ${product}: ${path}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readRawBody(bodyFile: string | undefined, cwd: string) {
|
|
||||||
if (!bodyFile) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contents = await readWorkspaceFile(bodyFile, cwd);
|
|
||||||
return JSON.parse(contents) as unknown;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runRawCommand(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
input: RawInput,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
validateMethod(input.method);
|
|
||||||
validatePath(input.product, input.path);
|
|
||||||
|
|
||||||
const body = await readRawBody(input.bodyFile, input.cwd);
|
|
||||||
const request = {
|
|
||||||
method: input.method,
|
|
||||||
url: buildUrl(config, input.product, input.path),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const data = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: input.method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Raw request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
export type AtlassianConfig = {
|
|
||||||
baseUrl: string;
|
|
||||||
jiraBaseUrl: string;
|
|
||||||
confluenceBaseUrl: string;
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
defaultProject?: string;
|
|
||||||
defaultSpace?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type CommandOutput<T> = {
|
|
||||||
ok: boolean;
|
|
||||||
data: T;
|
|
||||||
dryRun?: boolean;
|
|
||||||
raw?: unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type JiraIssueSummary = {
|
|
||||||
key: string;
|
|
||||||
summary: string;
|
|
||||||
issueType: string;
|
|
||||||
status: string;
|
|
||||||
assignee?: string;
|
|
||||||
created: string;
|
|
||||||
updated: string;
|
|
||||||
url: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type Writer = {
|
|
||||||
write(chunk: string | Uint8Array): unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type FetchLike = typeof fetch;
|
|
||||||
|
|
||||||
export type OutputFormat = "json" | "text";
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"target": "ES2022",
|
|
||||||
"module": "NodeNext",
|
|
||||||
"moduleResolution": "NodeNext",
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"forceConsistentCasingInFileNames": true,
|
|
||||||
"strict": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"resolveJsonModule": true,
|
|
||||||
"types": ["node"],
|
|
||||||
"outDir": "dist"
|
|
||||||
},
|
|
||||||
"include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
|
|
||||||
}
|
|
||||||
@@ -1,81 +0,0 @@
|
|||||||
---
|
|
||||||
name: atlassian
|
|
||||||
description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Atlassian (Codex)
|
|
||||||
|
|
||||||
Portable Atlassian workflows for Codex using a shared TypeScript CLI.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Node.js 20+
|
|
||||||
- `pnpm`
|
|
||||||
- Atlassian Cloud account access
|
|
||||||
- `ATLASSIAN_BASE_URL`
|
|
||||||
- `ATLASSIAN_EMAIL`
|
|
||||||
- `ATLASSIAN_API_TOKEN`
|
|
||||||
|
|
||||||
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in `~/.codex/skills/atlassian/scripts`.
|
|
||||||
|
|
||||||
## First-Time Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.codex/skills/atlassian
|
|
||||||
cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
|
|
||||||
cd ~/.codex/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
|
||||||
|
|
||||||
Run before using the skill:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd ~/.codex/skills/atlassian/scripts
|
|
||||||
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
|
|
||||||
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
|
|
||||||
pnpm atlassian health
|
|
||||||
```
|
|
||||||
|
|
||||||
If any check fails, stop and return:
|
|
||||||
|
|
||||||
`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
|
|
||||||
|
|
||||||
## Supported Commands
|
|
||||||
|
|
||||||
- `pnpm atlassian health`
|
|
||||||
- `pnpm atlassian jira-search --jql "..."`
|
|
||||||
- `pnpm atlassian jira-get --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-transitions --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-transition ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-search --query "..."`
|
|
||||||
- `pnpm atlassian conf-get --page 12345`
|
|
||||||
- `pnpm atlassian conf-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-children --page 12345`
|
|
||||||
- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
- `pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 10`
|
|
||||||
- `pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run`
|
|
||||||
- `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`
|
|
||||||
|
|
||||||
## Safety Rules
|
|
||||||
|
|
||||||
- Default output is JSON; prefer that for agent workflows.
|
|
||||||
- Use `--dry-run` before any mutating command unless the user clearly wants the write to happen immediately.
|
|
||||||
- Jira long-text fields are converted to ADF locally.
|
|
||||||
- Confluence page bodies are storage-first in v1.
|
|
||||||
- `--body-file` must point to workspace-scoped files only; do not use arbitrary system paths.
|
|
||||||
- `raw` is for explicit edge cases only and does not allow `DELETE`.
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Atlassian Cloud is the only first-class target in v1.
|
|
||||||
- This skill exists so Codex, Claude Code, Cursor Agent, and OpenCode can share the same command surface even when MCP access differs.
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
{
|
|
||||||
"name": "atlassian-skill-scripts",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"description": "Shared runtime for the Atlassian skill",
|
|
||||||
"type": "module",
|
|
||||||
"scripts": {
|
|
||||||
"atlassian": "tsx src/cli.ts",
|
|
||||||
"typecheck": "tsc --noEmit"
|
|
||||||
},
|
|
||||||
"dependencies": {
|
|
||||||
"commander": "^13.1.0",
|
|
||||||
"dotenv": "^16.4.7"
|
|
||||||
},
|
|
||||||
"devDependencies": {
|
|
||||||
"@types/node": "^24.3.0",
|
|
||||||
"tsx": "^4.20.5",
|
|
||||||
"typescript": "^5.9.2"
|
|
||||||
},
|
|
||||||
"packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
|
|
||||||
}
|
|
||||||
361
skills/atlassian/codex/scripts/pnpm-lock.yaml
generated
361
skills/atlassian/codex/scripts/pnpm-lock.yaml
generated
@@ -1,361 +0,0 @@
|
|||||||
lockfileVersion: '9.0'
|
|
||||||
|
|
||||||
settings:
|
|
||||||
autoInstallPeers: true
|
|
||||||
excludeLinksFromLockfile: false
|
|
||||||
|
|
||||||
importers:
|
|
||||||
|
|
||||||
.:
|
|
||||||
dependencies:
|
|
||||||
commander:
|
|
||||||
specifier: ^13.1.0
|
|
||||||
version: 13.1.0
|
|
||||||
dotenv:
|
|
||||||
specifier: ^16.4.7
|
|
||||||
version: 16.6.1
|
|
||||||
devDependencies:
|
|
||||||
'@types/node':
|
|
||||||
specifier: ^24.3.0
|
|
||||||
version: 24.12.0
|
|
||||||
tsx:
|
|
||||||
specifier: ^4.20.5
|
|
||||||
version: 4.21.0
|
|
||||||
typescript:
|
|
||||||
specifier: ^5.9.2
|
|
||||||
version: 5.9.3
|
|
||||||
|
|
||||||
packages:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [aix]
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [loong64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [mips64el]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [riscv64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [s390x]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openharmony]
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [sunos]
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
|
|
||||||
|
|
||||||
commander@13.1.0:
|
|
||||||
resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
|
|
||||||
dotenv@16.6.1:
|
|
||||||
resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
|
|
||||||
engines: {node: '>=12'}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
|
|
||||||
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0:
|
|
||||||
resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
|
|
||||||
engines: {node: '>=18.0.0'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
typescript@5.9.3:
|
|
||||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
|
||||||
engines: {node: '>=14.17'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
undici-types@7.16.0:
|
|
||||||
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
|
|
||||||
|
|
||||||
snapshots:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
dependencies:
|
|
||||||
undici-types: 7.16.0
|
|
||||||
|
|
||||||
commander@13.1.0: {}
|
|
||||||
|
|
||||||
dotenv@16.6.1: {}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
optionalDependencies:
|
|
||||||
'@esbuild/aix-ppc64': 0.27.3
|
|
||||||
'@esbuild/android-arm': 0.27.3
|
|
||||||
'@esbuild/android-arm64': 0.27.3
|
|
||||||
'@esbuild/android-x64': 0.27.3
|
|
||||||
'@esbuild/darwin-arm64': 0.27.3
|
|
||||||
'@esbuild/darwin-x64': 0.27.3
|
|
||||||
'@esbuild/freebsd-arm64': 0.27.3
|
|
||||||
'@esbuild/freebsd-x64': 0.27.3
|
|
||||||
'@esbuild/linux-arm': 0.27.3
|
|
||||||
'@esbuild/linux-arm64': 0.27.3
|
|
||||||
'@esbuild/linux-ia32': 0.27.3
|
|
||||||
'@esbuild/linux-loong64': 0.27.3
|
|
||||||
'@esbuild/linux-mips64el': 0.27.3
|
|
||||||
'@esbuild/linux-ppc64': 0.27.3
|
|
||||||
'@esbuild/linux-riscv64': 0.27.3
|
|
||||||
'@esbuild/linux-s390x': 0.27.3
|
|
||||||
'@esbuild/linux-x64': 0.27.3
|
|
||||||
'@esbuild/netbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/netbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/openbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openharmony-arm64': 0.27.3
|
|
||||||
'@esbuild/sunos-x64': 0.27.3
|
|
||||||
'@esbuild/win32-arm64': 0.27.3
|
|
||||||
'@esbuild/win32-ia32': 0.27.3
|
|
||||||
'@esbuild/win32-x64': 0.27.3
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
dependencies:
|
|
||||||
resolve-pkg-maps: 1.0.0
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0: {}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
dependencies:
|
|
||||||
esbuild: 0.27.3
|
|
||||||
get-tsconfig: 4.13.6
|
|
||||||
optionalDependencies:
|
|
||||||
fsevents: 2.3.3
|
|
||||||
|
|
||||||
typescript@5.9.3: {}
|
|
||||||
|
|
||||||
undici-types@7.16.0: {}
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
const TEXT_NODE = "text";
|
|
||||||
|
|
||||||
function textNode(text: string) {
|
|
||||||
return {
|
|
||||||
type: TEXT_NODE,
|
|
||||||
text,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function paragraphNode(lines: string[]) {
|
|
||||||
const content: Array<{ type: string; text?: string }> = [];
|
|
||||||
|
|
||||||
lines.forEach((line, index) => {
|
|
||||||
if (index > 0) {
|
|
||||||
content.push({ type: "hardBreak" });
|
|
||||||
}
|
|
||||||
|
|
||||||
if (line.length > 0) {
|
|
||||||
content.push(textNode(line));
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "paragraph",
|
|
||||||
...(content.length > 0 ? { content } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function markdownToAdf(input: string) {
|
|
||||||
const lines = input.replace(/\r\n/g, "\n").split("\n");
|
|
||||||
const content: Array<Record<string, unknown>> = [];
|
|
||||||
let index = 0;
|
|
||||||
|
|
||||||
while (index < lines.length) {
|
|
||||||
const current = lines[index]?.trimEnd() ?? "";
|
|
||||||
|
|
||||||
if (current.trim().length === 0) {
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const heading = current.match(/^(#{1,6})\s+(.*)$/);
|
|
||||||
|
|
||||||
if (heading) {
|
|
||||||
content.push({
|
|
||||||
type: "heading",
|
|
||||||
attrs: { level: heading[1].length },
|
|
||||||
content: [textNode(heading[2])],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (/^[-*]\s+/.test(current)) {
|
|
||||||
const items: Array<Record<string, unknown>> = [];
|
|
||||||
|
|
||||||
while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
|
|
||||||
items.push({
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push({
|
|
||||||
type: "bulletList",
|
|
||||||
content: items,
|
|
||||||
});
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const paragraphLines: string[] = [];
|
|
||||||
|
|
||||||
while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
|
|
||||||
paragraphLines.push(lines[index] ?? "");
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push(paragraphNode(paragraphLines));
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "doc",
|
|
||||||
version: 1,
|
|
||||||
content,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,332 +0,0 @@
|
|||||||
import process from "node:process";
|
|
||||||
import { pathToFileURL } from "node:url";
|
|
||||||
|
|
||||||
import { Command } from "commander";
|
|
||||||
|
|
||||||
import { createConfluenceClient } from "./confluence.js";
|
|
||||||
import { loadConfig } from "./config.js";
|
|
||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { runHealthCheck } from "./health.js";
|
|
||||||
import { createJiraClient } from "./jira.js";
|
|
||||||
import { writeOutput } from "./output.js";
|
|
||||||
import { runRawCommand } from "./raw.js";
|
|
||||||
import type { FetchLike, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
type CliContext = {
|
|
||||||
cwd?: string;
|
|
||||||
env?: NodeJS.ProcessEnv;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
stdout?: Writer;
|
|
||||||
stderr?: Writer;
|
|
||||||
};
|
|
||||||
|
|
||||||
function resolveFormat(format: string | undefined): OutputFormat {
|
|
||||||
return format === "text" ? "text" : "json";
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRuntime(context: CliContext) {
|
|
||||||
const cwd = context.cwd ?? process.cwd();
|
|
||||||
const env = context.env ?? process.env;
|
|
||||||
const stdout = context.stdout ?? process.stdout;
|
|
||||||
const stderr = context.stderr ?? process.stderr;
|
|
||||||
let configCache: ReturnType<typeof loadConfig> | undefined;
|
|
||||||
let jiraCache: ReturnType<typeof createJiraClient> | undefined;
|
|
||||||
let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
|
|
||||||
|
|
||||||
function getConfig() {
|
|
||||||
configCache ??= loadConfig(env, { cwd });
|
|
||||||
return configCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getJiraClient() {
|
|
||||||
jiraCache ??= createJiraClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return jiraCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getConfluenceClient() {
|
|
||||||
confluenceCache ??= createConfluenceClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return confluenceCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readBodyFile(filePath: string | undefined) {
|
|
||||||
if (!filePath) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
return readWorkspaceFile(filePath, cwd);
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
cwd,
|
|
||||||
stdout,
|
|
||||||
stderr,
|
|
||||||
readBodyFile,
|
|
||||||
getConfig,
|
|
||||||
getJiraClient,
|
|
||||||
getConfluenceClient,
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function buildProgram(context: CliContext = {}) {
|
|
||||||
const runtime = createRuntime(context);
|
|
||||||
const program = new Command()
|
|
||||||
.name("atlassian")
|
|
||||||
.description("Portable Atlassian CLI for multi-agent skills")
|
|
||||||
.version("0.1.0");
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("health")
|
|
||||||
.description("Validate configuration and Atlassian connectivity")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
|
|
||||||
writeOutput(
|
|
||||||
runtime.stdout,
|
|
||||||
payload,
|
|
||||||
resolveFormat(options.format),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-search")
|
|
||||||
.requiredOption("--query <query>", "CQL search query")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().searchPages({
|
|
||||||
query: options.query,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-get")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().getPage(options.page);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-create")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--space <space>", "Confluence space ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().createPage({
|
|
||||||
space: options.space,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-update")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().updatePage({
|
|
||||||
pageId: options.page,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-comment")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().commentPage({
|
|
||||||
pageId: options.page,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-children")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Cursor/start token", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().listChildren(
|
|
||||||
options.page,
|
|
||||||
Number(options.maxResults),
|
|
||||||
Number(options.startAt),
|
|
||||||
);
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("raw")
|
|
||||||
.requiredOption("--product <product>", "jira or confluence")
|
|
||||||
.requiredOption("--method <method>", "GET, POST, or PUT")
|
|
||||||
.requiredOption("--path <path>", "Validated API path")
|
|
||||||
.option("--body-file <path>", "Workspace-relative JSON file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
|
|
||||||
product: options.product,
|
|
||||||
method: String(options.method).toUpperCase(),
|
|
||||||
path: options.path,
|
|
||||||
bodyFile: options.bodyFile,
|
|
||||||
cwd: runtime.cwd,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-search")
|
|
||||||
.requiredOption("--jql <jql>", "JQL expression to execute")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().searchIssues({
|
|
||||||
jql: options.jql,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-get")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getIssue(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-create")
|
|
||||||
.requiredOption("--type <type>", "Issue type name")
|
|
||||||
.requiredOption("--summary <summary>", "Issue summary")
|
|
||||||
.option("--project <project>", "Project key")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().createIssue({
|
|
||||||
project: options.project,
|
|
||||||
type: options.type,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-update")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--summary <summary>", "Updated summary")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().updateIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-comment")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().commentIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transitions")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getTransitions(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transition")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--transition <transition>", "Transition ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().transitionIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
transition: options.transition,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
return program;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runCli(argv = process.argv, context: CliContext = {}) {
|
|
||||||
const program = buildProgram(context);
|
|
||||||
await program.parseAsync(argv);
|
|
||||||
}
|
|
||||||
|
|
||||||
const isDirectExecution =
|
|
||||||
Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
|
|
||||||
|
|
||||||
if (isDirectExecution) {
|
|
||||||
runCli().catch((error: unknown) => {
|
|
||||||
const message = error instanceof Error ? error.message : String(error);
|
|
||||||
process.stderr.write(`${message}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
import path from "node:path";
|
|
||||||
|
|
||||||
import { config as loadDotEnv } from "dotenv";
|
|
||||||
|
|
||||||
import type { AtlassianConfig } from "./types.js";
|
|
||||||
|
|
||||||
function normalizeBaseUrl(value: string) {
|
|
||||||
return value.replace(/\/+$/, "");
|
|
||||||
}
|
|
||||||
|
|
||||||
function readRequired(env: NodeJS.ProcessEnv, key: string) {
|
|
||||||
const value = env[key]?.trim();
|
|
||||||
|
|
||||||
if (!value) {
|
|
||||||
throw new Error(`Missing required environment variable: ${key}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return value;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function loadConfig(
|
|
||||||
env: NodeJS.ProcessEnv = process.env,
|
|
||||||
options?: {
|
|
||||||
cwd?: string;
|
|
||||||
},
|
|
||||||
): AtlassianConfig {
|
|
||||||
loadDotEnv({
|
|
||||||
path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
|
|
||||||
processEnv: env as Record<string, string>,
|
|
||||||
override: false,
|
|
||||||
});
|
|
||||||
|
|
||||||
const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
baseUrl,
|
|
||||||
jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
|
|
||||||
confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
|
|
||||||
email: readRequired(env, "ATLASSIAN_EMAIL"),
|
|
||||||
apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
|
|
||||||
defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
|
|
||||||
defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createBasicAuthHeader(config: {
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
[key: string]: unknown;
|
|
||||||
}) {
|
|
||||||
return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
|
|
||||||
}
|
|
||||||
@@ -1,292 +0,0 @@
|
|||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ConfluenceClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
query: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
space?: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
pageId: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
pageId: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type PageSummary = {
|
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
type: string;
|
|
||||||
status?: string;
|
|
||||||
spaceId?: string;
|
|
||||||
url?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
|
|
||||||
const links = (page._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
id: String(page.id ?? ""),
|
|
||||||
title: String(page.title ?? ""),
|
|
||||||
type: String(page.type ?? "page"),
|
|
||||||
...(page.status ? { status: String(page.status) } : {}),
|
|
||||||
...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
|
|
||||||
...(excerpt ? { excerpt } : {}),
|
|
||||||
...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createConfluenceClient(options: ConfluenceClientOptions) {
|
|
||||||
const config = options.config;
|
|
||||||
|
|
||||||
async function getPageForUpdate(pageId: string) {
|
|
||||||
return (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("cql", input.query);
|
|
||||||
url.searchParams.set("limit", String(input.maxResults));
|
|
||||||
url.searchParams.set("start", String(input.startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((entry) => {
|
|
||||||
const result = entry as Record<string, unknown>;
|
|
||||||
return normalizePage(
|
|
||||||
config.baseUrl,
|
|
||||||
(result.content ?? {}) as Record<string, unknown>,
|
|
||||||
result.excerpt ? String(result.excerpt) : undefined,
|
|
||||||
);
|
|
||||||
}),
|
|
||||||
startAt: Number(raw.start ?? input.startAt),
|
|
||||||
maxResults: Number(raw.limit ?? input.maxResults),
|
|
||||||
total: Number(raw.totalSize ?? raw.size ?? results.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getPage(pageId: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
page: {
|
|
||||||
...normalizePage(config.baseUrl, raw),
|
|
||||||
version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
|
|
||||||
body: body?.value ? String(body.value) : "",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("limit", String(maxResults));
|
|
||||||
url.searchParams.set("cursor", String(startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
const links = (raw._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
|
|
||||||
nextCursor: links.next ? String(links.next) : null,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const spaceId = input.space || config.defaultSpace;
|
|
||||||
|
|
||||||
if (!spaceId) {
|
|
||||||
throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
|
|
||||||
body: {
|
|
||||||
spaceId,
|
|
||||||
title: input.title,
|
|
||||||
status: "current",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const currentPage = await getPageForUpdate(input.pageId);
|
|
||||||
const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
|
|
||||||
const spaceId = String(currentPage.spaceId ?? "");
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "PUT" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
|
|
||||||
body: {
|
|
||||||
id: input.pageId,
|
|
||||||
status: String(currentPage.status ?? "current"),
|
|
||||||
title: input.title,
|
|
||||||
spaceId,
|
|
||||||
version: {
|
|
||||||
number: Number(version) + 1,
|
|
||||||
},
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
handleResponseError(response) {
|
|
||||||
if (response.status === 409) {
|
|
||||||
return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return undefined;
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
|
|
||||||
body: {
|
|
||||||
pageId: input.pageId,
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
import { readFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
export async function readWorkspaceFile(filePath: string, cwd: string) {
|
|
||||||
const resolved = path.resolve(cwd, filePath);
|
|
||||||
const relative = path.relative(cwd, resolved);
|
|
||||||
|
|
||||||
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
|
||||||
throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return readFile(resolved, "utf8");
|
|
||||||
}
|
|
||||||
@@ -1,69 +0,0 @@
|
|||||||
import { createJsonHeaders, createStatusError } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ProductHealth = {
|
|
||||||
ok: boolean;
|
|
||||||
status?: number;
|
|
||||||
message?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runHealthCheck(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
const client = fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!client) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
|
|
||||||
try {
|
|
||||||
const response = await client(url, {
|
|
||||||
method: "GET",
|
|
||||||
headers: createJsonHeaders(config, false),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const error = createStatusError(`${product} health check failed`, response);
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
status: response.status,
|
|
||||||
message: error.message,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
status: response.status,
|
|
||||||
};
|
|
||||||
} catch (error: unknown) {
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
message: error instanceof Error ? error.message : String(error),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
|
|
||||||
const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: jira.ok && confluence.ok,
|
|
||||||
data: {
|
|
||||||
baseUrl: config.baseUrl,
|
|
||||||
jiraBaseUrl: config.jiraBaseUrl,
|
|
||||||
confluenceBaseUrl: config.confluenceBaseUrl,
|
|
||||||
defaultProject: config.defaultProject,
|
|
||||||
defaultSpace: config.defaultSpace,
|
|
||||||
products: {
|
|
||||||
jira,
|
|
||||||
confluence,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
import { createBasicAuthHeader } from "./config.js";
|
|
||||||
import type { AtlassianConfig, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
export type HttpMethod = "GET" | "POST" | "PUT";
|
|
||||||
|
|
||||||
export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
|
|
||||||
const headers: Array<[string, string]> = [
|
|
||||||
["Accept", "application/json"],
|
|
||||||
["Authorization", createBasicAuthHeader(config)],
|
|
||||||
];
|
|
||||||
|
|
||||||
if (includeJsonBody) {
|
|
||||||
headers.push(["Content-Type", "application/json"]);
|
|
||||||
}
|
|
||||||
|
|
||||||
return headers;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function parseResponse(response: Response) {
|
|
||||||
if (response.status === 204) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contentType = response.headers.get("content-type") ?? "";
|
|
||||||
|
|
||||||
if (contentType.includes("application/json")) {
|
|
||||||
try {
|
|
||||||
return await response.json();
|
|
||||||
} catch {
|
|
||||||
throw new Error("Malformed JSON response from Atlassian API");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return response.text();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createStatusError(errorPrefix: string, response: Response) {
|
|
||||||
const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
|
|
||||||
|
|
||||||
switch (response.status) {
|
|
||||||
case 401:
|
|
||||||
return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
|
|
||||||
case 403:
|
|
||||||
return new Error(`${base} - verify product permissions for this account`);
|
|
||||||
case 404:
|
|
||||||
return new Error(`${base} - verify the resource identifier or API path`);
|
|
||||||
case 429:
|
|
||||||
return new Error(`${base} - retry later or reduce request rate`);
|
|
||||||
default:
|
|
||||||
return new Error(base);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function sendJsonRequest(options: {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
url: string;
|
|
||||||
method: HttpMethod;
|
|
||||||
body?: unknown;
|
|
||||||
errorPrefix: string;
|
|
||||||
handleResponseError?: (response: Response) => Error | undefined;
|
|
||||||
}) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await fetchImpl(options.url, {
|
|
||||||
method: options.method,
|
|
||||||
headers: createJsonHeaders(options.config, options.body !== undefined),
|
|
||||||
...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const customError = options.handleResponseError?.(response);
|
|
||||||
|
|
||||||
if (customError) {
|
|
||||||
throw customError;
|
|
||||||
}
|
|
||||||
|
|
||||||
throw createStatusError(options.errorPrefix, response);
|
|
||||||
}
|
|
||||||
|
|
||||||
return parseResponse(response);
|
|
||||||
}
|
|
||||||
@@ -1,264 +0,0 @@
|
|||||||
import { markdownToAdf } from "./adf.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
|
|
||||||
|
|
||||||
const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
|
|
||||||
|
|
||||||
type JiraClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
jql: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
project?: string;
|
|
||||||
type: string;
|
|
||||||
summary: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
issue: string;
|
|
||||||
summary?: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
issue: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type TransitionInput = {
|
|
||||||
issue: string;
|
|
||||||
transition: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
|
|
||||||
const fields = (issue.fields ?? {}) as Record<string, unknown>;
|
|
||||||
const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
|
|
||||||
const status = (fields.status ?? {}) as Record<string, unknown>;
|
|
||||||
const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
key: String(issue.key ?? ""),
|
|
||||||
summary: String(fields.summary ?? ""),
|
|
||||||
issueType: String(issueType.name ?? ""),
|
|
||||||
status: String(status.name ?? ""),
|
|
||||||
assignee: assignee.displayName ? String(assignee.displayName) : undefined,
|
|
||||||
created: String(fields.created ?? ""),
|
|
||||||
updated: String(fields.updated ?? ""),
|
|
||||||
url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const url = new URL(path, `${config.jiraBaseUrl}/`);
|
|
||||||
|
|
||||||
return {
|
|
||||||
method,
|
|
||||||
url: url.toString(),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createJiraClient(options: JiraClientOptions) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const request = createRequest(options.config, method, path, body);
|
|
||||||
return sendJsonRequest({
|
|
||||||
config: options.config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send("POST", "/rest/api/3/search", {
|
|
||||||
jql: input.jql,
|
|
||||||
maxResults: input.maxResults,
|
|
||||||
startAt: input.startAt,
|
|
||||||
fields: [...ISSUE_FIELDS],
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const issues = Array.isArray(raw.issues) ? raw.issues : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
|
|
||||||
startAt: Number(raw.startAt ?? input.startAt),
|
|
||||||
maxResults: Number(raw.maxResults ?? input.maxResults),
|
|
||||||
total: Number(raw.total ?? issues.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getIssue(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
|
|
||||||
url.searchParams.set("fields", ISSUE_FIELDS.join(","));
|
|
||||||
|
|
||||||
const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: normalizeIssue(options.config, raw),
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send(
|
|
||||||
"GET",
|
|
||||||
`/rest/api/3/issue/${issue}/transitions`,
|
|
||||||
)) as { transitions?: Array<Record<string, unknown>> };
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
transitions: (raw.transitions ?? []).map((transition) => ({
|
|
||||||
id: String(transition.id ?? ""),
|
|
||||||
name: String(transition.name ?? ""),
|
|
||||||
toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
|
|
||||||
hasScreen: Boolean(transition.hasScreen),
|
|
||||||
})),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const project = input.project || options.config.defaultProject;
|
|
||||||
|
|
||||||
if (!project) {
|
|
||||||
throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
|
|
||||||
fields: {
|
|
||||||
project: { key: project },
|
|
||||||
issuetype: { name: input.type },
|
|
||||||
summary: input.summary,
|
|
||||||
...(input.description ? { description: markdownToAdf(input.description) } : {}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", "/rest/api/3/issue", request.body);
|
|
||||||
return { ok: true, data: raw };
|
|
||||||
},
|
|
||||||
|
|
||||||
async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const fields: Record<string, unknown> = {};
|
|
||||||
|
|
||||||
if (input.summary) {
|
|
||||||
fields.summary = input.summary;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (input.description) {
|
|
||||||
fields.description = markdownToAdf(input.description);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Object.keys(fields).length === 0) {
|
|
||||||
throw new Error("jira-update requires --summary and/or --description-file");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
|
|
||||||
fields,
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
updated: true,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
|
|
||||||
body: markdownToAdf(input.body),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(
|
|
||||||
options.config,
|
|
||||||
"POST",
|
|
||||||
`/rest/api/3/issue/${input.issue}/transitions`,
|
|
||||||
{
|
|
||||||
transition: {
|
|
||||||
id: input.transition,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
);
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
transitioned: true,
|
|
||||||
transition: input.transition,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
import type { CommandOutput, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
function renderText(payload: CommandOutput<unknown>) {
|
|
||||||
const data = payload.data as Record<string, unknown>;
|
|
||||||
|
|
||||||
if (Array.isArray(data?.issues)) {
|
|
||||||
return data.issues
|
|
||||||
.map((issue) => {
|
|
||||||
const item = issue as Record<string, string>;
|
|
||||||
return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (data?.issue && typeof data.issue === "object") {
|
|
||||||
const issue = data.issue as Record<string, string>;
|
|
||||||
return [
|
|
||||||
issue.key,
|
|
||||||
`${issue.issueType} | ${issue.status}`,
|
|
||||||
issue.summary,
|
|
||||||
issue.url,
|
|
||||||
].join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Array.isArray(data?.transitions)) {
|
|
||||||
return data.transitions
|
|
||||||
.map((transition) => {
|
|
||||||
const item = transition as Record<string, string>;
|
|
||||||
return `${item.id} ${item.name} -> ${item.toStatus}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
return JSON.stringify(payload, null, 2);
|
|
||||||
}
|
|
||||||
|
|
||||||
export function writeOutput(
|
|
||||||
writer: Writer,
|
|
||||||
payload: CommandOutput<unknown>,
|
|
||||||
format: OutputFormat = "json",
|
|
||||||
) {
|
|
||||||
const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
|
|
||||||
writer.write(`${body}\n`);
|
|
||||||
}
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
|
|
||||||
const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
|
|
||||||
|
|
||||||
type RawInput = {
|
|
||||||
product: "jira" | "confluence";
|
|
||||||
method: string;
|
|
||||||
path: string;
|
|
||||||
bodyFile?: string;
|
|
||||||
cwd: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function getAllowedPrefixes(product: RawInput["product"]) {
|
|
||||||
return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
|
|
||||||
const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
|
|
||||||
if (!["GET", "POST", "PUT"].includes(method)) {
|
|
||||||
throw new Error("raw only allows GET, POST, and PUT");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function validatePath(product: RawInput["product"], path: string) {
|
|
||||||
const allowedPrefixes = getAllowedPrefixes(product);
|
|
||||||
|
|
||||||
if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
|
|
||||||
throw new Error(`raw path is not allowed for ${product}: ${path}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readRawBody(bodyFile: string | undefined, cwd: string) {
|
|
||||||
if (!bodyFile) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contents = await readWorkspaceFile(bodyFile, cwd);
|
|
||||||
return JSON.parse(contents) as unknown;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runRawCommand(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
input: RawInput,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
validateMethod(input.method);
|
|
||||||
validatePath(input.product, input.path);
|
|
||||||
|
|
||||||
const body = await readRawBody(input.bodyFile, input.cwd);
|
|
||||||
const request = {
|
|
||||||
method: input.method,
|
|
||||||
url: buildUrl(config, input.product, input.path),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const data = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: input.method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Raw request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
export type AtlassianConfig = {
|
|
||||||
baseUrl: string;
|
|
||||||
jiraBaseUrl: string;
|
|
||||||
confluenceBaseUrl: string;
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
defaultProject?: string;
|
|
||||||
defaultSpace?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type CommandOutput<T> = {
|
|
||||||
ok: boolean;
|
|
||||||
data: T;
|
|
||||||
dryRun?: boolean;
|
|
||||||
raw?: unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type JiraIssueSummary = {
|
|
||||||
key: string;
|
|
||||||
summary: string;
|
|
||||||
issueType: string;
|
|
||||||
status: string;
|
|
||||||
assignee?: string;
|
|
||||||
created: string;
|
|
||||||
updated: string;
|
|
||||||
url: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type Writer = {
|
|
||||||
write(chunk: string | Uint8Array): unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type FetchLike = typeof fetch;
|
|
||||||
|
|
||||||
export type OutputFormat = "json" | "text";
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"target": "ES2022",
|
|
||||||
"module": "NodeNext",
|
|
||||||
"moduleResolution": "NodeNext",
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"forceConsistentCasingInFileNames": true,
|
|
||||||
"strict": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"resolveJsonModule": true,
|
|
||||||
"types": ["node"],
|
|
||||||
"outDir": "dist"
|
|
||||||
},
|
|
||||||
"include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
|
|
||||||
}
|
|
||||||
@@ -1,93 +0,0 @@
|
|||||||
---
|
|
||||||
name: atlassian
|
|
||||||
description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Atlassian (Cursor Agent CLI)
|
|
||||||
|
|
||||||
Portable Atlassian workflows for Cursor Agent CLI using a shared TypeScript CLI.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Cursor Agent CLI skill discovery via `.cursor/skills/` or `~/.cursor/skills/`
|
|
||||||
- Node.js 20+
|
|
||||||
- `pnpm`
|
|
||||||
- Atlassian Cloud account access
|
|
||||||
- `ATLASSIAN_BASE_URL`
|
|
||||||
- `ATLASSIAN_EMAIL`
|
|
||||||
- `ATLASSIAN_API_TOKEN`
|
|
||||||
|
|
||||||
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed `scripts/` folder.
|
|
||||||
|
|
||||||
## First-Time Setup
|
|
||||||
|
|
||||||
Repo-local install:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .cursor/skills/atlassian
|
|
||||||
cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
|
|
||||||
cd .cursor/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
Global install:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.cursor/skills/atlassian
|
|
||||||
cp -R skills/atlassian/cursor/* ~/.cursor/skills/atlassian/
|
|
||||||
cd ~/.cursor/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
|
||||||
|
|
||||||
Repo-local form:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent --version
|
|
||||||
cd .cursor/skills/atlassian/scripts
|
|
||||||
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
|
|
||||||
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
|
|
||||||
pnpm atlassian health
|
|
||||||
```
|
|
||||||
|
|
||||||
If any check fails, stop and return:
|
|
||||||
|
|
||||||
`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
|
|
||||||
|
|
||||||
## Supported Commands
|
|
||||||
|
|
||||||
- `pnpm atlassian health`
|
|
||||||
- `pnpm atlassian jira-search --jql "..."`
|
|
||||||
- `pnpm atlassian jira-get --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-transitions --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-transition ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-search --query "..."`
|
|
||||||
- `pnpm atlassian conf-get --page 12345`
|
|
||||||
- `pnpm atlassian conf-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-children --page 12345`
|
|
||||||
- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
- `pnpm atlassian jira-get --issue ENG-123`
|
|
||||||
- `pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\"" --max-results 10 --start-at 0`
|
|
||||||
- `pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run`
|
|
||||||
|
|
||||||
## Safety Rules
|
|
||||||
|
|
||||||
- Prefer JSON output for agent use.
|
|
||||||
- Use `--dry-run` before writes unless the user explicitly wants the change applied.
|
|
||||||
- Keep `--body-file` inputs within the current workspace.
|
|
||||||
- Use `raw` only for user-requested unsupported endpoints.
|
|
||||||
- `raw` does not allow `DELETE`.
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Cursor discovers this skill from `.cursor/skills/` or `~/.cursor/skills/`.
|
|
||||||
- Atlassian Cloud is the supported platform in v1.
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
{
|
|
||||||
"name": "atlassian-skill-scripts",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"description": "Shared runtime for the Atlassian skill",
|
|
||||||
"type": "module",
|
|
||||||
"scripts": {
|
|
||||||
"atlassian": "tsx src/cli.ts",
|
|
||||||
"typecheck": "tsc --noEmit"
|
|
||||||
},
|
|
||||||
"dependencies": {
|
|
||||||
"commander": "^13.1.0",
|
|
||||||
"dotenv": "^16.4.7"
|
|
||||||
},
|
|
||||||
"devDependencies": {
|
|
||||||
"@types/node": "^24.3.0",
|
|
||||||
"tsx": "^4.20.5",
|
|
||||||
"typescript": "^5.9.2"
|
|
||||||
},
|
|
||||||
"packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
|
|
||||||
}
|
|
||||||
361
skills/atlassian/cursor/scripts/pnpm-lock.yaml
generated
361
skills/atlassian/cursor/scripts/pnpm-lock.yaml
generated
@@ -1,361 +0,0 @@
|
|||||||
lockfileVersion: '9.0'
|
|
||||||
|
|
||||||
settings:
|
|
||||||
autoInstallPeers: true
|
|
||||||
excludeLinksFromLockfile: false
|
|
||||||
|
|
||||||
importers:
|
|
||||||
|
|
||||||
.:
|
|
||||||
dependencies:
|
|
||||||
commander:
|
|
||||||
specifier: ^13.1.0
|
|
||||||
version: 13.1.0
|
|
||||||
dotenv:
|
|
||||||
specifier: ^16.4.7
|
|
||||||
version: 16.6.1
|
|
||||||
devDependencies:
|
|
||||||
'@types/node':
|
|
||||||
specifier: ^24.3.0
|
|
||||||
version: 24.12.0
|
|
||||||
tsx:
|
|
||||||
specifier: ^4.20.5
|
|
||||||
version: 4.21.0
|
|
||||||
typescript:
|
|
||||||
specifier: ^5.9.2
|
|
||||||
version: 5.9.3
|
|
||||||
|
|
||||||
packages:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [aix]
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [loong64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [mips64el]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [riscv64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [s390x]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openharmony]
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [sunos]
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
|
|
||||||
|
|
||||||
commander@13.1.0:
|
|
||||||
resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
|
|
||||||
dotenv@16.6.1:
|
|
||||||
resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
|
|
||||||
engines: {node: '>=12'}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
|
|
||||||
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0:
|
|
||||||
resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
|
|
||||||
engines: {node: '>=18.0.0'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
typescript@5.9.3:
|
|
||||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
|
||||||
engines: {node: '>=14.17'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
undici-types@7.16.0:
|
|
||||||
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
|
|
||||||
|
|
||||||
snapshots:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
dependencies:
|
|
||||||
undici-types: 7.16.0
|
|
||||||
|
|
||||||
commander@13.1.0: {}
|
|
||||||
|
|
||||||
dotenv@16.6.1: {}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
optionalDependencies:
|
|
||||||
'@esbuild/aix-ppc64': 0.27.3
|
|
||||||
'@esbuild/android-arm': 0.27.3
|
|
||||||
'@esbuild/android-arm64': 0.27.3
|
|
||||||
'@esbuild/android-x64': 0.27.3
|
|
||||||
'@esbuild/darwin-arm64': 0.27.3
|
|
||||||
'@esbuild/darwin-x64': 0.27.3
|
|
||||||
'@esbuild/freebsd-arm64': 0.27.3
|
|
||||||
'@esbuild/freebsd-x64': 0.27.3
|
|
||||||
'@esbuild/linux-arm': 0.27.3
|
|
||||||
'@esbuild/linux-arm64': 0.27.3
|
|
||||||
'@esbuild/linux-ia32': 0.27.3
|
|
||||||
'@esbuild/linux-loong64': 0.27.3
|
|
||||||
'@esbuild/linux-mips64el': 0.27.3
|
|
||||||
'@esbuild/linux-ppc64': 0.27.3
|
|
||||||
'@esbuild/linux-riscv64': 0.27.3
|
|
||||||
'@esbuild/linux-s390x': 0.27.3
|
|
||||||
'@esbuild/linux-x64': 0.27.3
|
|
||||||
'@esbuild/netbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/netbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/openbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openharmony-arm64': 0.27.3
|
|
||||||
'@esbuild/sunos-x64': 0.27.3
|
|
||||||
'@esbuild/win32-arm64': 0.27.3
|
|
||||||
'@esbuild/win32-ia32': 0.27.3
|
|
||||||
'@esbuild/win32-x64': 0.27.3
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
dependencies:
|
|
||||||
resolve-pkg-maps: 1.0.0
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0: {}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
dependencies:
|
|
||||||
esbuild: 0.27.3
|
|
||||||
get-tsconfig: 4.13.6
|
|
||||||
optionalDependencies:
|
|
||||||
fsevents: 2.3.3
|
|
||||||
|
|
||||||
typescript@5.9.3: {}
|
|
||||||
|
|
||||||
undici-types@7.16.0: {}
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
const TEXT_NODE = "text";
|
|
||||||
|
|
||||||
function textNode(text: string) {
|
|
||||||
return {
|
|
||||||
type: TEXT_NODE,
|
|
||||||
text,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function paragraphNode(lines: string[]) {
|
|
||||||
const content: Array<{ type: string; text?: string }> = [];
|
|
||||||
|
|
||||||
lines.forEach((line, index) => {
|
|
||||||
if (index > 0) {
|
|
||||||
content.push({ type: "hardBreak" });
|
|
||||||
}
|
|
||||||
|
|
||||||
if (line.length > 0) {
|
|
||||||
content.push(textNode(line));
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "paragraph",
|
|
||||||
...(content.length > 0 ? { content } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function markdownToAdf(input: string) {
|
|
||||||
const lines = input.replace(/\r\n/g, "\n").split("\n");
|
|
||||||
const content: Array<Record<string, unknown>> = [];
|
|
||||||
let index = 0;
|
|
||||||
|
|
||||||
while (index < lines.length) {
|
|
||||||
const current = lines[index]?.trimEnd() ?? "";
|
|
||||||
|
|
||||||
if (current.trim().length === 0) {
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const heading = current.match(/^(#{1,6})\s+(.*)$/);
|
|
||||||
|
|
||||||
if (heading) {
|
|
||||||
content.push({
|
|
||||||
type: "heading",
|
|
||||||
attrs: { level: heading[1].length },
|
|
||||||
content: [textNode(heading[2])],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (/^[-*]\s+/.test(current)) {
|
|
||||||
const items: Array<Record<string, unknown>> = [];
|
|
||||||
|
|
||||||
while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
|
|
||||||
items.push({
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push({
|
|
||||||
type: "bulletList",
|
|
||||||
content: items,
|
|
||||||
});
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const paragraphLines: string[] = [];
|
|
||||||
|
|
||||||
while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
|
|
||||||
paragraphLines.push(lines[index] ?? "");
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push(paragraphNode(paragraphLines));
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "doc",
|
|
||||||
version: 1,
|
|
||||||
content,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,332 +0,0 @@
|
|||||||
import process from "node:process";
|
|
||||||
import { pathToFileURL } from "node:url";
|
|
||||||
|
|
||||||
import { Command } from "commander";
|
|
||||||
|
|
||||||
import { createConfluenceClient } from "./confluence.js";
|
|
||||||
import { loadConfig } from "./config.js";
|
|
||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { runHealthCheck } from "./health.js";
|
|
||||||
import { createJiraClient } from "./jira.js";
|
|
||||||
import { writeOutput } from "./output.js";
|
|
||||||
import { runRawCommand } from "./raw.js";
|
|
||||||
import type { FetchLike, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
type CliContext = {
|
|
||||||
cwd?: string;
|
|
||||||
env?: NodeJS.ProcessEnv;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
stdout?: Writer;
|
|
||||||
stderr?: Writer;
|
|
||||||
};
|
|
||||||
|
|
||||||
function resolveFormat(format: string | undefined): OutputFormat {
|
|
||||||
return format === "text" ? "text" : "json";
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRuntime(context: CliContext) {
|
|
||||||
const cwd = context.cwd ?? process.cwd();
|
|
||||||
const env = context.env ?? process.env;
|
|
||||||
const stdout = context.stdout ?? process.stdout;
|
|
||||||
const stderr = context.stderr ?? process.stderr;
|
|
||||||
let configCache: ReturnType<typeof loadConfig> | undefined;
|
|
||||||
let jiraCache: ReturnType<typeof createJiraClient> | undefined;
|
|
||||||
let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
|
|
||||||
|
|
||||||
function getConfig() {
|
|
||||||
configCache ??= loadConfig(env, { cwd });
|
|
||||||
return configCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getJiraClient() {
|
|
||||||
jiraCache ??= createJiraClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return jiraCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getConfluenceClient() {
|
|
||||||
confluenceCache ??= createConfluenceClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return confluenceCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readBodyFile(filePath: string | undefined) {
|
|
||||||
if (!filePath) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
return readWorkspaceFile(filePath, cwd);
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
cwd,
|
|
||||||
stdout,
|
|
||||||
stderr,
|
|
||||||
readBodyFile,
|
|
||||||
getConfig,
|
|
||||||
getJiraClient,
|
|
||||||
getConfluenceClient,
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function buildProgram(context: CliContext = {}) {
|
|
||||||
const runtime = createRuntime(context);
|
|
||||||
const program = new Command()
|
|
||||||
.name("atlassian")
|
|
||||||
.description("Portable Atlassian CLI for multi-agent skills")
|
|
||||||
.version("0.1.0");
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("health")
|
|
||||||
.description("Validate configuration and Atlassian connectivity")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
|
|
||||||
writeOutput(
|
|
||||||
runtime.stdout,
|
|
||||||
payload,
|
|
||||||
resolveFormat(options.format),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-search")
|
|
||||||
.requiredOption("--query <query>", "CQL search query")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().searchPages({
|
|
||||||
query: options.query,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-get")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().getPage(options.page);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-create")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--space <space>", "Confluence space ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().createPage({
|
|
||||||
space: options.space,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-update")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().updatePage({
|
|
||||||
pageId: options.page,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-comment")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().commentPage({
|
|
||||||
pageId: options.page,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-children")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Cursor/start token", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().listChildren(
|
|
||||||
options.page,
|
|
||||||
Number(options.maxResults),
|
|
||||||
Number(options.startAt),
|
|
||||||
);
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("raw")
|
|
||||||
.requiredOption("--product <product>", "jira or confluence")
|
|
||||||
.requiredOption("--method <method>", "GET, POST, or PUT")
|
|
||||||
.requiredOption("--path <path>", "Validated API path")
|
|
||||||
.option("--body-file <path>", "Workspace-relative JSON file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
|
|
||||||
product: options.product,
|
|
||||||
method: String(options.method).toUpperCase(),
|
|
||||||
path: options.path,
|
|
||||||
bodyFile: options.bodyFile,
|
|
||||||
cwd: runtime.cwd,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-search")
|
|
||||||
.requiredOption("--jql <jql>", "JQL expression to execute")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().searchIssues({
|
|
||||||
jql: options.jql,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-get")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getIssue(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-create")
|
|
||||||
.requiredOption("--type <type>", "Issue type name")
|
|
||||||
.requiredOption("--summary <summary>", "Issue summary")
|
|
||||||
.option("--project <project>", "Project key")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().createIssue({
|
|
||||||
project: options.project,
|
|
||||||
type: options.type,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-update")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--summary <summary>", "Updated summary")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().updateIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-comment")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().commentIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transitions")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getTransitions(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transition")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--transition <transition>", "Transition ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().transitionIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
transition: options.transition,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
return program;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runCli(argv = process.argv, context: CliContext = {}) {
|
|
||||||
const program = buildProgram(context);
|
|
||||||
await program.parseAsync(argv);
|
|
||||||
}
|
|
||||||
|
|
||||||
const isDirectExecution =
|
|
||||||
Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
|
|
||||||
|
|
||||||
if (isDirectExecution) {
|
|
||||||
runCli().catch((error: unknown) => {
|
|
||||||
const message = error instanceof Error ? error.message : String(error);
|
|
||||||
process.stderr.write(`${message}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
import path from "node:path";
|
|
||||||
|
|
||||||
import { config as loadDotEnv } from "dotenv";
|
|
||||||
|
|
||||||
import type { AtlassianConfig } from "./types.js";
|
|
||||||
|
|
||||||
function normalizeBaseUrl(value: string) {
|
|
||||||
return value.replace(/\/+$/, "");
|
|
||||||
}
|
|
||||||
|
|
||||||
function readRequired(env: NodeJS.ProcessEnv, key: string) {
|
|
||||||
const value = env[key]?.trim();
|
|
||||||
|
|
||||||
if (!value) {
|
|
||||||
throw new Error(`Missing required environment variable: ${key}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return value;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function loadConfig(
|
|
||||||
env: NodeJS.ProcessEnv = process.env,
|
|
||||||
options?: {
|
|
||||||
cwd?: string;
|
|
||||||
},
|
|
||||||
): AtlassianConfig {
|
|
||||||
loadDotEnv({
|
|
||||||
path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
|
|
||||||
processEnv: env as Record<string, string>,
|
|
||||||
override: false,
|
|
||||||
});
|
|
||||||
|
|
||||||
const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
baseUrl,
|
|
||||||
jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
|
|
||||||
confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
|
|
||||||
email: readRequired(env, "ATLASSIAN_EMAIL"),
|
|
||||||
apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
|
|
||||||
defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
|
|
||||||
defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createBasicAuthHeader(config: {
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
[key: string]: unknown;
|
|
||||||
}) {
|
|
||||||
return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
|
|
||||||
}
|
|
||||||
@@ -1,292 +0,0 @@
|
|||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ConfluenceClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
query: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
space?: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
pageId: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
pageId: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type PageSummary = {
|
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
type: string;
|
|
||||||
status?: string;
|
|
||||||
spaceId?: string;
|
|
||||||
url?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
|
|
||||||
const links = (page._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
id: String(page.id ?? ""),
|
|
||||||
title: String(page.title ?? ""),
|
|
||||||
type: String(page.type ?? "page"),
|
|
||||||
...(page.status ? { status: String(page.status) } : {}),
|
|
||||||
...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
|
|
||||||
...(excerpt ? { excerpt } : {}),
|
|
||||||
...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createConfluenceClient(options: ConfluenceClientOptions) {
|
|
||||||
const config = options.config;
|
|
||||||
|
|
||||||
async function getPageForUpdate(pageId: string) {
|
|
||||||
return (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("cql", input.query);
|
|
||||||
url.searchParams.set("limit", String(input.maxResults));
|
|
||||||
url.searchParams.set("start", String(input.startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((entry) => {
|
|
||||||
const result = entry as Record<string, unknown>;
|
|
||||||
return normalizePage(
|
|
||||||
config.baseUrl,
|
|
||||||
(result.content ?? {}) as Record<string, unknown>,
|
|
||||||
result.excerpt ? String(result.excerpt) : undefined,
|
|
||||||
);
|
|
||||||
}),
|
|
||||||
startAt: Number(raw.start ?? input.startAt),
|
|
||||||
maxResults: Number(raw.limit ?? input.maxResults),
|
|
||||||
total: Number(raw.totalSize ?? raw.size ?? results.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getPage(pageId: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
page: {
|
|
||||||
...normalizePage(config.baseUrl, raw),
|
|
||||||
version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
|
|
||||||
body: body?.value ? String(body.value) : "",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("limit", String(maxResults));
|
|
||||||
url.searchParams.set("cursor", String(startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
const links = (raw._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
|
|
||||||
nextCursor: links.next ? String(links.next) : null,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const spaceId = input.space || config.defaultSpace;
|
|
||||||
|
|
||||||
if (!spaceId) {
|
|
||||||
throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
|
|
||||||
body: {
|
|
||||||
spaceId,
|
|
||||||
title: input.title,
|
|
||||||
status: "current",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const currentPage = await getPageForUpdate(input.pageId);
|
|
||||||
const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
|
|
||||||
const spaceId = String(currentPage.spaceId ?? "");
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "PUT" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
|
|
||||||
body: {
|
|
||||||
id: input.pageId,
|
|
||||||
status: String(currentPage.status ?? "current"),
|
|
||||||
title: input.title,
|
|
||||||
spaceId,
|
|
||||||
version: {
|
|
||||||
number: Number(version) + 1,
|
|
||||||
},
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
handleResponseError(response) {
|
|
||||||
if (response.status === 409) {
|
|
||||||
return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return undefined;
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
|
|
||||||
body: {
|
|
||||||
pageId: input.pageId,
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
import { readFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
export async function readWorkspaceFile(filePath: string, cwd: string) {
|
|
||||||
const resolved = path.resolve(cwd, filePath);
|
|
||||||
const relative = path.relative(cwd, resolved);
|
|
||||||
|
|
||||||
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
|
||||||
throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return readFile(resolved, "utf8");
|
|
||||||
}
|
|
||||||
@@ -1,69 +0,0 @@
|
|||||||
import { createJsonHeaders, createStatusError } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ProductHealth = {
|
|
||||||
ok: boolean;
|
|
||||||
status?: number;
|
|
||||||
message?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runHealthCheck(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
const client = fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!client) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
|
|
||||||
try {
|
|
||||||
const response = await client(url, {
|
|
||||||
method: "GET",
|
|
||||||
headers: createJsonHeaders(config, false),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const error = createStatusError(`${product} health check failed`, response);
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
status: response.status,
|
|
||||||
message: error.message,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
status: response.status,
|
|
||||||
};
|
|
||||||
} catch (error: unknown) {
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
message: error instanceof Error ? error.message : String(error),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
|
|
||||||
const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: jira.ok && confluence.ok,
|
|
||||||
data: {
|
|
||||||
baseUrl: config.baseUrl,
|
|
||||||
jiraBaseUrl: config.jiraBaseUrl,
|
|
||||||
confluenceBaseUrl: config.confluenceBaseUrl,
|
|
||||||
defaultProject: config.defaultProject,
|
|
||||||
defaultSpace: config.defaultSpace,
|
|
||||||
products: {
|
|
||||||
jira,
|
|
||||||
confluence,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
import { createBasicAuthHeader } from "./config.js";
|
|
||||||
import type { AtlassianConfig, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
export type HttpMethod = "GET" | "POST" | "PUT";
|
|
||||||
|
|
||||||
export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
|
|
||||||
const headers: Array<[string, string]> = [
|
|
||||||
["Accept", "application/json"],
|
|
||||||
["Authorization", createBasicAuthHeader(config)],
|
|
||||||
];
|
|
||||||
|
|
||||||
if (includeJsonBody) {
|
|
||||||
headers.push(["Content-Type", "application/json"]);
|
|
||||||
}
|
|
||||||
|
|
||||||
return headers;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function parseResponse(response: Response) {
|
|
||||||
if (response.status === 204) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contentType = response.headers.get("content-type") ?? "";
|
|
||||||
|
|
||||||
if (contentType.includes("application/json")) {
|
|
||||||
try {
|
|
||||||
return await response.json();
|
|
||||||
} catch {
|
|
||||||
throw new Error("Malformed JSON response from Atlassian API");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return response.text();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createStatusError(errorPrefix: string, response: Response) {
|
|
||||||
const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
|
|
||||||
|
|
||||||
switch (response.status) {
|
|
||||||
case 401:
|
|
||||||
return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
|
|
||||||
case 403:
|
|
||||||
return new Error(`${base} - verify product permissions for this account`);
|
|
||||||
case 404:
|
|
||||||
return new Error(`${base} - verify the resource identifier or API path`);
|
|
||||||
case 429:
|
|
||||||
return new Error(`${base} - retry later or reduce request rate`);
|
|
||||||
default:
|
|
||||||
return new Error(base);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function sendJsonRequest(options: {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
url: string;
|
|
||||||
method: HttpMethod;
|
|
||||||
body?: unknown;
|
|
||||||
errorPrefix: string;
|
|
||||||
handleResponseError?: (response: Response) => Error | undefined;
|
|
||||||
}) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await fetchImpl(options.url, {
|
|
||||||
method: options.method,
|
|
||||||
headers: createJsonHeaders(options.config, options.body !== undefined),
|
|
||||||
...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const customError = options.handleResponseError?.(response);
|
|
||||||
|
|
||||||
if (customError) {
|
|
||||||
throw customError;
|
|
||||||
}
|
|
||||||
|
|
||||||
throw createStatusError(options.errorPrefix, response);
|
|
||||||
}
|
|
||||||
|
|
||||||
return parseResponse(response);
|
|
||||||
}
|
|
||||||
@@ -1,264 +0,0 @@
|
|||||||
import { markdownToAdf } from "./adf.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
|
|
||||||
|
|
||||||
const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
|
|
||||||
|
|
||||||
type JiraClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
jql: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
project?: string;
|
|
||||||
type: string;
|
|
||||||
summary: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
issue: string;
|
|
||||||
summary?: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
issue: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type TransitionInput = {
|
|
||||||
issue: string;
|
|
||||||
transition: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
|
|
||||||
const fields = (issue.fields ?? {}) as Record<string, unknown>;
|
|
||||||
const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
|
|
||||||
const status = (fields.status ?? {}) as Record<string, unknown>;
|
|
||||||
const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
key: String(issue.key ?? ""),
|
|
||||||
summary: String(fields.summary ?? ""),
|
|
||||||
issueType: String(issueType.name ?? ""),
|
|
||||||
status: String(status.name ?? ""),
|
|
||||||
assignee: assignee.displayName ? String(assignee.displayName) : undefined,
|
|
||||||
created: String(fields.created ?? ""),
|
|
||||||
updated: String(fields.updated ?? ""),
|
|
||||||
url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const url = new URL(path, `${config.jiraBaseUrl}/`);
|
|
||||||
|
|
||||||
return {
|
|
||||||
method,
|
|
||||||
url: url.toString(),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createJiraClient(options: JiraClientOptions) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const request = createRequest(options.config, method, path, body);
|
|
||||||
return sendJsonRequest({
|
|
||||||
config: options.config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send("POST", "/rest/api/3/search", {
|
|
||||||
jql: input.jql,
|
|
||||||
maxResults: input.maxResults,
|
|
||||||
startAt: input.startAt,
|
|
||||||
fields: [...ISSUE_FIELDS],
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const issues = Array.isArray(raw.issues) ? raw.issues : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
|
|
||||||
startAt: Number(raw.startAt ?? input.startAt),
|
|
||||||
maxResults: Number(raw.maxResults ?? input.maxResults),
|
|
||||||
total: Number(raw.total ?? issues.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getIssue(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
|
|
||||||
url.searchParams.set("fields", ISSUE_FIELDS.join(","));
|
|
||||||
|
|
||||||
const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: normalizeIssue(options.config, raw),
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send(
|
|
||||||
"GET",
|
|
||||||
`/rest/api/3/issue/${issue}/transitions`,
|
|
||||||
)) as { transitions?: Array<Record<string, unknown>> };
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
transitions: (raw.transitions ?? []).map((transition) => ({
|
|
||||||
id: String(transition.id ?? ""),
|
|
||||||
name: String(transition.name ?? ""),
|
|
||||||
toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
|
|
||||||
hasScreen: Boolean(transition.hasScreen),
|
|
||||||
})),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const project = input.project || options.config.defaultProject;
|
|
||||||
|
|
||||||
if (!project) {
|
|
||||||
throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
|
|
||||||
fields: {
|
|
||||||
project: { key: project },
|
|
||||||
issuetype: { name: input.type },
|
|
||||||
summary: input.summary,
|
|
||||||
...(input.description ? { description: markdownToAdf(input.description) } : {}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", "/rest/api/3/issue", request.body);
|
|
||||||
return { ok: true, data: raw };
|
|
||||||
},
|
|
||||||
|
|
||||||
async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const fields: Record<string, unknown> = {};
|
|
||||||
|
|
||||||
if (input.summary) {
|
|
||||||
fields.summary = input.summary;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (input.description) {
|
|
||||||
fields.description = markdownToAdf(input.description);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Object.keys(fields).length === 0) {
|
|
||||||
throw new Error("jira-update requires --summary and/or --description-file");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
|
|
||||||
fields,
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
updated: true,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
|
|
||||||
body: markdownToAdf(input.body),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(
|
|
||||||
options.config,
|
|
||||||
"POST",
|
|
||||||
`/rest/api/3/issue/${input.issue}/transitions`,
|
|
||||||
{
|
|
||||||
transition: {
|
|
||||||
id: input.transition,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
);
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
transitioned: true,
|
|
||||||
transition: input.transition,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
import type { CommandOutput, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
function renderText(payload: CommandOutput<unknown>) {
|
|
||||||
const data = payload.data as Record<string, unknown>;
|
|
||||||
|
|
||||||
if (Array.isArray(data?.issues)) {
|
|
||||||
return data.issues
|
|
||||||
.map((issue) => {
|
|
||||||
const item = issue as Record<string, string>;
|
|
||||||
return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (data?.issue && typeof data.issue === "object") {
|
|
||||||
const issue = data.issue as Record<string, string>;
|
|
||||||
return [
|
|
||||||
issue.key,
|
|
||||||
`${issue.issueType} | ${issue.status}`,
|
|
||||||
issue.summary,
|
|
||||||
issue.url,
|
|
||||||
].join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Array.isArray(data?.transitions)) {
|
|
||||||
return data.transitions
|
|
||||||
.map((transition) => {
|
|
||||||
const item = transition as Record<string, string>;
|
|
||||||
return `${item.id} ${item.name} -> ${item.toStatus}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
return JSON.stringify(payload, null, 2);
|
|
||||||
}
|
|
||||||
|
|
||||||
export function writeOutput(
|
|
||||||
writer: Writer,
|
|
||||||
payload: CommandOutput<unknown>,
|
|
||||||
format: OutputFormat = "json",
|
|
||||||
) {
|
|
||||||
const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
|
|
||||||
writer.write(`${body}\n`);
|
|
||||||
}
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
|
|
||||||
const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
|
|
||||||
|
|
||||||
type RawInput = {
|
|
||||||
product: "jira" | "confluence";
|
|
||||||
method: string;
|
|
||||||
path: string;
|
|
||||||
bodyFile?: string;
|
|
||||||
cwd: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function getAllowedPrefixes(product: RawInput["product"]) {
|
|
||||||
return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
|
|
||||||
const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
|
|
||||||
if (!["GET", "POST", "PUT"].includes(method)) {
|
|
||||||
throw new Error("raw only allows GET, POST, and PUT");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function validatePath(product: RawInput["product"], path: string) {
|
|
||||||
const allowedPrefixes = getAllowedPrefixes(product);
|
|
||||||
|
|
||||||
if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
|
|
||||||
throw new Error(`raw path is not allowed for ${product}: ${path}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readRawBody(bodyFile: string | undefined, cwd: string) {
|
|
||||||
if (!bodyFile) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contents = await readWorkspaceFile(bodyFile, cwd);
|
|
||||||
return JSON.parse(contents) as unknown;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runRawCommand(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
input: RawInput,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
validateMethod(input.method);
|
|
||||||
validatePath(input.product, input.path);
|
|
||||||
|
|
||||||
const body = await readRawBody(input.bodyFile, input.cwd);
|
|
||||||
const request = {
|
|
||||||
method: input.method,
|
|
||||||
url: buildUrl(config, input.product, input.path),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const data = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: input.method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Raw request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
export type AtlassianConfig = {
|
|
||||||
baseUrl: string;
|
|
||||||
jiraBaseUrl: string;
|
|
||||||
confluenceBaseUrl: string;
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
defaultProject?: string;
|
|
||||||
defaultSpace?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type CommandOutput<T> = {
|
|
||||||
ok: boolean;
|
|
||||||
data: T;
|
|
||||||
dryRun?: boolean;
|
|
||||||
raw?: unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type JiraIssueSummary = {
|
|
||||||
key: string;
|
|
||||||
summary: string;
|
|
||||||
issueType: string;
|
|
||||||
status: string;
|
|
||||||
assignee?: string;
|
|
||||||
created: string;
|
|
||||||
updated: string;
|
|
||||||
url: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type Writer = {
|
|
||||||
write(chunk: string | Uint8Array): unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type FetchLike = typeof fetch;
|
|
||||||
|
|
||||||
export type OutputFormat = "json" | "text";
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"target": "ES2022",
|
|
||||||
"module": "NodeNext",
|
|
||||||
"moduleResolution": "NodeNext",
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"forceConsistentCasingInFileNames": true,
|
|
||||||
"strict": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"resolveJsonModule": true,
|
|
||||||
"types": ["node"],
|
|
||||||
"outDir": "dist"
|
|
||||||
},
|
|
||||||
"include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
|
|
||||||
}
|
|
||||||
@@ -1,78 +0,0 @@
|
|||||||
---
|
|
||||||
name: atlassian
|
|
||||||
description: Interact with Atlassian Cloud Jira and Confluence through a portable task-oriented CLI for search, issue/page edits, comments, transitions, and bounded raw requests.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Atlassian (OpenCode)
|
|
||||||
|
|
||||||
Portable Atlassian workflows for OpenCode using a shared TypeScript CLI.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Node.js 20+
|
|
||||||
- `pnpm`
|
|
||||||
- Atlassian Cloud account access
|
|
||||||
- `ATLASSIAN_BASE_URL`
|
|
||||||
- `ATLASSIAN_EMAIL`
|
|
||||||
- `ATLASSIAN_API_TOKEN`
|
|
||||||
|
|
||||||
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in `~/.config/opencode/skills/atlassian/scripts`.
|
|
||||||
|
|
||||||
## First-Time Setup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/.config/opencode/skills/atlassian
|
|
||||||
cp -R skills/atlassian/opencode/* ~/.config/opencode/skills/atlassian/
|
|
||||||
cd ~/.config/opencode/skills/atlassian/scripts
|
|
||||||
pnpm install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd ~/.config/opencode/skills/atlassian/scripts
|
|
||||||
node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
|
|
||||||
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
|
|
||||||
pnpm atlassian health
|
|
||||||
```
|
|
||||||
|
|
||||||
If any check fails, stop and return:
|
|
||||||
|
|
||||||
`Missing dependency/config: atlassian requires installed CLI dependencies and valid Atlassian Cloud credentials. Configure ATLASSIAN_* in the shell environment or scripts/.env, then retry.`
|
|
||||||
|
|
||||||
## Supported Commands
|
|
||||||
|
|
||||||
- `pnpm atlassian health`
|
|
||||||
- `pnpm atlassian jira-search --jql "..."`
|
|
||||||
- `pnpm atlassian jira-get --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian jira-transitions --issue ABC-123`
|
|
||||||
- `pnpm atlassian jira-transition ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-search --query "..."`
|
|
||||||
- `pnpm atlassian conf-get --page 12345`
|
|
||||||
- `pnpm atlassian conf-create ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-update ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-comment ... [--dry-run]`
|
|
||||||
- `pnpm atlassian conf-children --page 12345`
|
|
||||||
- `pnpm atlassian raw --product jira|confluence --method GET|POST|PUT --path ...`
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
- `pnpm atlassian jira-transition --issue ENG-123 --transition 31 --dry-run`
|
|
||||||
- `pnpm atlassian conf-create --space OPS --title "Runbook" --body-file page.storage.html --dry-run`
|
|
||||||
- `pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"`
|
|
||||||
|
|
||||||
## Safety Rules
|
|
||||||
|
|
||||||
- Prefer JSON output for machine consumption.
|
|
||||||
- Use `--dry-run` on writes unless the user explicitly asks to commit the remote mutation.
|
|
||||||
- Restrict `--body-file` to project files.
|
|
||||||
- Use `raw` only for unsupported edge cases.
|
|
||||||
- `DELETE` is intentionally unsupported in raw mode.
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Atlassian Cloud is first-class in v1; Data Center support is future work.
|
|
||||||
- The CLI contract is shared across all agent variants so the same usage pattern works everywhere.
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
{
|
|
||||||
"name": "atlassian-skill-scripts",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"description": "Shared runtime for the Atlassian skill",
|
|
||||||
"type": "module",
|
|
||||||
"scripts": {
|
|
||||||
"atlassian": "tsx src/cli.ts",
|
|
||||||
"typecheck": "tsc --noEmit"
|
|
||||||
},
|
|
||||||
"dependencies": {
|
|
||||||
"commander": "^13.1.0",
|
|
||||||
"dotenv": "^16.4.7"
|
|
||||||
},
|
|
||||||
"devDependencies": {
|
|
||||||
"@types/node": "^24.3.0",
|
|
||||||
"tsx": "^4.20.5",
|
|
||||||
"typescript": "^5.9.2"
|
|
||||||
},
|
|
||||||
"packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
|
|
||||||
}
|
|
||||||
361
skills/atlassian/opencode/scripts/pnpm-lock.yaml
generated
361
skills/atlassian/opencode/scripts/pnpm-lock.yaml
generated
@@ -1,361 +0,0 @@
|
|||||||
lockfileVersion: '9.0'
|
|
||||||
|
|
||||||
settings:
|
|
||||||
autoInstallPeers: true
|
|
||||||
excludeLinksFromLockfile: false
|
|
||||||
|
|
||||||
importers:
|
|
||||||
|
|
||||||
.:
|
|
||||||
dependencies:
|
|
||||||
commander:
|
|
||||||
specifier: ^13.1.0
|
|
||||||
version: 13.1.0
|
|
||||||
dotenv:
|
|
||||||
specifier: ^16.4.7
|
|
||||||
version: 16.6.1
|
|
||||||
devDependencies:
|
|
||||||
'@types/node':
|
|
||||||
specifier: ^24.3.0
|
|
||||||
version: 24.12.0
|
|
||||||
tsx:
|
|
||||||
specifier: ^4.20.5
|
|
||||||
version: 4.21.0
|
|
||||||
typescript:
|
|
||||||
specifier: ^5.9.2
|
|
||||||
version: 5.9.3
|
|
||||||
|
|
||||||
packages:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [aix]
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [loong64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [mips64el]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [riscv64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [s390x]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openharmony]
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [sunos]
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
|
|
||||||
|
|
||||||
commander@13.1.0:
|
|
||||||
resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
|
|
||||||
dotenv@16.6.1:
|
|
||||||
resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
|
|
||||||
engines: {node: '>=12'}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
|
|
||||||
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0:
|
|
||||||
resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
|
|
||||||
engines: {node: '>=18.0.0'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
typescript@5.9.3:
|
|
||||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
|
||||||
engines: {node: '>=14.17'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
undici-types@7.16.0:
|
|
||||||
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
|
|
||||||
|
|
||||||
snapshots:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
dependencies:
|
|
||||||
undici-types: 7.16.0
|
|
||||||
|
|
||||||
commander@13.1.0: {}
|
|
||||||
|
|
||||||
dotenv@16.6.1: {}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
optionalDependencies:
|
|
||||||
'@esbuild/aix-ppc64': 0.27.3
|
|
||||||
'@esbuild/android-arm': 0.27.3
|
|
||||||
'@esbuild/android-arm64': 0.27.3
|
|
||||||
'@esbuild/android-x64': 0.27.3
|
|
||||||
'@esbuild/darwin-arm64': 0.27.3
|
|
||||||
'@esbuild/darwin-x64': 0.27.3
|
|
||||||
'@esbuild/freebsd-arm64': 0.27.3
|
|
||||||
'@esbuild/freebsd-x64': 0.27.3
|
|
||||||
'@esbuild/linux-arm': 0.27.3
|
|
||||||
'@esbuild/linux-arm64': 0.27.3
|
|
||||||
'@esbuild/linux-ia32': 0.27.3
|
|
||||||
'@esbuild/linux-loong64': 0.27.3
|
|
||||||
'@esbuild/linux-mips64el': 0.27.3
|
|
||||||
'@esbuild/linux-ppc64': 0.27.3
|
|
||||||
'@esbuild/linux-riscv64': 0.27.3
|
|
||||||
'@esbuild/linux-s390x': 0.27.3
|
|
||||||
'@esbuild/linux-x64': 0.27.3
|
|
||||||
'@esbuild/netbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/netbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/openbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openharmony-arm64': 0.27.3
|
|
||||||
'@esbuild/sunos-x64': 0.27.3
|
|
||||||
'@esbuild/win32-arm64': 0.27.3
|
|
||||||
'@esbuild/win32-ia32': 0.27.3
|
|
||||||
'@esbuild/win32-x64': 0.27.3
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
dependencies:
|
|
||||||
resolve-pkg-maps: 1.0.0
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0: {}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
dependencies:
|
|
||||||
esbuild: 0.27.3
|
|
||||||
get-tsconfig: 4.13.6
|
|
||||||
optionalDependencies:
|
|
||||||
fsevents: 2.3.3
|
|
||||||
|
|
||||||
typescript@5.9.3: {}
|
|
||||||
|
|
||||||
undici-types@7.16.0: {}
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
const TEXT_NODE = "text";
|
|
||||||
|
|
||||||
function textNode(text: string) {
|
|
||||||
return {
|
|
||||||
type: TEXT_NODE,
|
|
||||||
text,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function paragraphNode(lines: string[]) {
|
|
||||||
const content: Array<{ type: string; text?: string }> = [];
|
|
||||||
|
|
||||||
lines.forEach((line, index) => {
|
|
||||||
if (index > 0) {
|
|
||||||
content.push({ type: "hardBreak" });
|
|
||||||
}
|
|
||||||
|
|
||||||
if (line.length > 0) {
|
|
||||||
content.push(textNode(line));
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "paragraph",
|
|
||||||
...(content.length > 0 ? { content } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function markdownToAdf(input: string) {
|
|
||||||
const lines = input.replace(/\r\n/g, "\n").split("\n");
|
|
||||||
const content: Array<Record<string, unknown>> = [];
|
|
||||||
let index = 0;
|
|
||||||
|
|
||||||
while (index < lines.length) {
|
|
||||||
const current = lines[index]?.trimEnd() ?? "";
|
|
||||||
|
|
||||||
if (current.trim().length === 0) {
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const heading = current.match(/^(#{1,6})\s+(.*)$/);
|
|
||||||
|
|
||||||
if (heading) {
|
|
||||||
content.push({
|
|
||||||
type: "heading",
|
|
||||||
attrs: { level: heading[1].length },
|
|
||||||
content: [textNode(heading[2])],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (/^[-*]\s+/.test(current)) {
|
|
||||||
const items: Array<Record<string, unknown>> = [];
|
|
||||||
|
|
||||||
while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
|
|
||||||
items.push({
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push({
|
|
||||||
type: "bulletList",
|
|
||||||
content: items,
|
|
||||||
});
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const paragraphLines: string[] = [];
|
|
||||||
|
|
||||||
while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
|
|
||||||
paragraphLines.push(lines[index] ?? "");
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push(paragraphNode(paragraphLines));
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "doc",
|
|
||||||
version: 1,
|
|
||||||
content,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,332 +0,0 @@
|
|||||||
import process from "node:process";
|
|
||||||
import { pathToFileURL } from "node:url";
|
|
||||||
|
|
||||||
import { Command } from "commander";
|
|
||||||
|
|
||||||
import { createConfluenceClient } from "./confluence.js";
|
|
||||||
import { loadConfig } from "./config.js";
|
|
||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { runHealthCheck } from "./health.js";
|
|
||||||
import { createJiraClient } from "./jira.js";
|
|
||||||
import { writeOutput } from "./output.js";
|
|
||||||
import { runRawCommand } from "./raw.js";
|
|
||||||
import type { FetchLike, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
type CliContext = {
|
|
||||||
cwd?: string;
|
|
||||||
env?: NodeJS.ProcessEnv;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
stdout?: Writer;
|
|
||||||
stderr?: Writer;
|
|
||||||
};
|
|
||||||
|
|
||||||
function resolveFormat(format: string | undefined): OutputFormat {
|
|
||||||
return format === "text" ? "text" : "json";
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRuntime(context: CliContext) {
|
|
||||||
const cwd = context.cwd ?? process.cwd();
|
|
||||||
const env = context.env ?? process.env;
|
|
||||||
const stdout = context.stdout ?? process.stdout;
|
|
||||||
const stderr = context.stderr ?? process.stderr;
|
|
||||||
let configCache: ReturnType<typeof loadConfig> | undefined;
|
|
||||||
let jiraCache: ReturnType<typeof createJiraClient> | undefined;
|
|
||||||
let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
|
|
||||||
|
|
||||||
function getConfig() {
|
|
||||||
configCache ??= loadConfig(env, { cwd });
|
|
||||||
return configCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getJiraClient() {
|
|
||||||
jiraCache ??= createJiraClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return jiraCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getConfluenceClient() {
|
|
||||||
confluenceCache ??= createConfluenceClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return confluenceCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readBodyFile(filePath: string | undefined) {
|
|
||||||
if (!filePath) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
return readWorkspaceFile(filePath, cwd);
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
cwd,
|
|
||||||
stdout,
|
|
||||||
stderr,
|
|
||||||
readBodyFile,
|
|
||||||
getConfig,
|
|
||||||
getJiraClient,
|
|
||||||
getConfluenceClient,
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function buildProgram(context: CliContext = {}) {
|
|
||||||
const runtime = createRuntime(context);
|
|
||||||
const program = new Command()
|
|
||||||
.name("atlassian")
|
|
||||||
.description("Portable Atlassian CLI for multi-agent skills")
|
|
||||||
.version("0.1.0");
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("health")
|
|
||||||
.description("Validate configuration and Atlassian connectivity")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
|
|
||||||
writeOutput(
|
|
||||||
runtime.stdout,
|
|
||||||
payload,
|
|
||||||
resolveFormat(options.format),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-search")
|
|
||||||
.requiredOption("--query <query>", "CQL search query")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().searchPages({
|
|
||||||
query: options.query,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-get")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().getPage(options.page);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-create")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--space <space>", "Confluence space ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().createPage({
|
|
||||||
space: options.space,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-update")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().updatePage({
|
|
||||||
pageId: options.page,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-comment")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().commentPage({
|
|
||||||
pageId: options.page,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-children")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Cursor/start token", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().listChildren(
|
|
||||||
options.page,
|
|
||||||
Number(options.maxResults),
|
|
||||||
Number(options.startAt),
|
|
||||||
);
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("raw")
|
|
||||||
.requiredOption("--product <product>", "jira or confluence")
|
|
||||||
.requiredOption("--method <method>", "GET, POST, or PUT")
|
|
||||||
.requiredOption("--path <path>", "Validated API path")
|
|
||||||
.option("--body-file <path>", "Workspace-relative JSON file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
|
|
||||||
product: options.product,
|
|
||||||
method: String(options.method).toUpperCase(),
|
|
||||||
path: options.path,
|
|
||||||
bodyFile: options.bodyFile,
|
|
||||||
cwd: runtime.cwd,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-search")
|
|
||||||
.requiredOption("--jql <jql>", "JQL expression to execute")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().searchIssues({
|
|
||||||
jql: options.jql,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-get")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getIssue(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-create")
|
|
||||||
.requiredOption("--type <type>", "Issue type name")
|
|
||||||
.requiredOption("--summary <summary>", "Issue summary")
|
|
||||||
.option("--project <project>", "Project key")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().createIssue({
|
|
||||||
project: options.project,
|
|
||||||
type: options.type,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-update")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--summary <summary>", "Updated summary")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().updateIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-comment")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().commentIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transitions")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getTransitions(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transition")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--transition <transition>", "Transition ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().transitionIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
transition: options.transition,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
return program;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runCli(argv = process.argv, context: CliContext = {}) {
|
|
||||||
const program = buildProgram(context);
|
|
||||||
await program.parseAsync(argv);
|
|
||||||
}
|
|
||||||
|
|
||||||
const isDirectExecution =
|
|
||||||
Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
|
|
||||||
|
|
||||||
if (isDirectExecution) {
|
|
||||||
runCli().catch((error: unknown) => {
|
|
||||||
const message = error instanceof Error ? error.message : String(error);
|
|
||||||
process.stderr.write(`${message}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
import path from "node:path";
|
|
||||||
|
|
||||||
import { config as loadDotEnv } from "dotenv";
|
|
||||||
|
|
||||||
import type { AtlassianConfig } from "./types.js";
|
|
||||||
|
|
||||||
function normalizeBaseUrl(value: string) {
|
|
||||||
return value.replace(/\/+$/, "");
|
|
||||||
}
|
|
||||||
|
|
||||||
function readRequired(env: NodeJS.ProcessEnv, key: string) {
|
|
||||||
const value = env[key]?.trim();
|
|
||||||
|
|
||||||
if (!value) {
|
|
||||||
throw new Error(`Missing required environment variable: ${key}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return value;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function loadConfig(
|
|
||||||
env: NodeJS.ProcessEnv = process.env,
|
|
||||||
options?: {
|
|
||||||
cwd?: string;
|
|
||||||
},
|
|
||||||
): AtlassianConfig {
|
|
||||||
loadDotEnv({
|
|
||||||
path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
|
|
||||||
processEnv: env as Record<string, string>,
|
|
||||||
override: false,
|
|
||||||
});
|
|
||||||
|
|
||||||
const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
baseUrl,
|
|
||||||
jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
|
|
||||||
confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
|
|
||||||
email: readRequired(env, "ATLASSIAN_EMAIL"),
|
|
||||||
apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
|
|
||||||
defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
|
|
||||||
defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createBasicAuthHeader(config: {
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
[key: string]: unknown;
|
|
||||||
}) {
|
|
||||||
return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
|
|
||||||
}
|
|
||||||
@@ -1,292 +0,0 @@
|
|||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ConfluenceClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
query: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
space?: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
pageId: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
pageId: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type PageSummary = {
|
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
type: string;
|
|
||||||
status?: string;
|
|
||||||
spaceId?: string;
|
|
||||||
url?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
|
|
||||||
const links = (page._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
id: String(page.id ?? ""),
|
|
||||||
title: String(page.title ?? ""),
|
|
||||||
type: String(page.type ?? "page"),
|
|
||||||
...(page.status ? { status: String(page.status) } : {}),
|
|
||||||
...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
|
|
||||||
...(excerpt ? { excerpt } : {}),
|
|
||||||
...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createConfluenceClient(options: ConfluenceClientOptions) {
|
|
||||||
const config = options.config;
|
|
||||||
|
|
||||||
async function getPageForUpdate(pageId: string) {
|
|
||||||
return (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("cql", input.query);
|
|
||||||
url.searchParams.set("limit", String(input.maxResults));
|
|
||||||
url.searchParams.set("start", String(input.startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((entry) => {
|
|
||||||
const result = entry as Record<string, unknown>;
|
|
||||||
return normalizePage(
|
|
||||||
config.baseUrl,
|
|
||||||
(result.content ?? {}) as Record<string, unknown>,
|
|
||||||
result.excerpt ? String(result.excerpt) : undefined,
|
|
||||||
);
|
|
||||||
}),
|
|
||||||
startAt: Number(raw.start ?? input.startAt),
|
|
||||||
maxResults: Number(raw.limit ?? input.maxResults),
|
|
||||||
total: Number(raw.totalSize ?? raw.size ?? results.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getPage(pageId: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
page: {
|
|
||||||
...normalizePage(config.baseUrl, raw),
|
|
||||||
version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
|
|
||||||
body: body?.value ? String(body.value) : "",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("limit", String(maxResults));
|
|
||||||
url.searchParams.set("cursor", String(startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
const links = (raw._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
|
|
||||||
nextCursor: links.next ? String(links.next) : null,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const spaceId = input.space || config.defaultSpace;
|
|
||||||
|
|
||||||
if (!spaceId) {
|
|
||||||
throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
|
|
||||||
body: {
|
|
||||||
spaceId,
|
|
||||||
title: input.title,
|
|
||||||
status: "current",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const currentPage = await getPageForUpdate(input.pageId);
|
|
||||||
const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
|
|
||||||
const spaceId = String(currentPage.spaceId ?? "");
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "PUT" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
|
|
||||||
body: {
|
|
||||||
id: input.pageId,
|
|
||||||
status: String(currentPage.status ?? "current"),
|
|
||||||
title: input.title,
|
|
||||||
spaceId,
|
|
||||||
version: {
|
|
||||||
number: Number(version) + 1,
|
|
||||||
},
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
handleResponseError(response) {
|
|
||||||
if (response.status === 409) {
|
|
||||||
return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return undefined;
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
|
|
||||||
body: {
|
|
||||||
pageId: input.pageId,
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
import { readFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
export async function readWorkspaceFile(filePath: string, cwd: string) {
|
|
||||||
const resolved = path.resolve(cwd, filePath);
|
|
||||||
const relative = path.relative(cwd, resolved);
|
|
||||||
|
|
||||||
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
|
||||||
throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return readFile(resolved, "utf8");
|
|
||||||
}
|
|
||||||
@@ -1,69 +0,0 @@
|
|||||||
import { createJsonHeaders, createStatusError } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ProductHealth = {
|
|
||||||
ok: boolean;
|
|
||||||
status?: number;
|
|
||||||
message?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runHealthCheck(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
const client = fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!client) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
|
|
||||||
try {
|
|
||||||
const response = await client(url, {
|
|
||||||
method: "GET",
|
|
||||||
headers: createJsonHeaders(config, false),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const error = createStatusError(`${product} health check failed`, response);
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
status: response.status,
|
|
||||||
message: error.message,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
status: response.status,
|
|
||||||
};
|
|
||||||
} catch (error: unknown) {
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
message: error instanceof Error ? error.message : String(error),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
|
|
||||||
const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: jira.ok && confluence.ok,
|
|
||||||
data: {
|
|
||||||
baseUrl: config.baseUrl,
|
|
||||||
jiraBaseUrl: config.jiraBaseUrl,
|
|
||||||
confluenceBaseUrl: config.confluenceBaseUrl,
|
|
||||||
defaultProject: config.defaultProject,
|
|
||||||
defaultSpace: config.defaultSpace,
|
|
||||||
products: {
|
|
||||||
jira,
|
|
||||||
confluence,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
import { createBasicAuthHeader } from "./config.js";
|
|
||||||
import type { AtlassianConfig, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
export type HttpMethod = "GET" | "POST" | "PUT";
|
|
||||||
|
|
||||||
export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
|
|
||||||
const headers: Array<[string, string]> = [
|
|
||||||
["Accept", "application/json"],
|
|
||||||
["Authorization", createBasicAuthHeader(config)],
|
|
||||||
];
|
|
||||||
|
|
||||||
if (includeJsonBody) {
|
|
||||||
headers.push(["Content-Type", "application/json"]);
|
|
||||||
}
|
|
||||||
|
|
||||||
return headers;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function parseResponse(response: Response) {
|
|
||||||
if (response.status === 204) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contentType = response.headers.get("content-type") ?? "";
|
|
||||||
|
|
||||||
if (contentType.includes("application/json")) {
|
|
||||||
try {
|
|
||||||
return await response.json();
|
|
||||||
} catch {
|
|
||||||
throw new Error("Malformed JSON response from Atlassian API");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return response.text();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createStatusError(errorPrefix: string, response: Response) {
|
|
||||||
const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
|
|
||||||
|
|
||||||
switch (response.status) {
|
|
||||||
case 401:
|
|
||||||
return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
|
|
||||||
case 403:
|
|
||||||
return new Error(`${base} - verify product permissions for this account`);
|
|
||||||
case 404:
|
|
||||||
return new Error(`${base} - verify the resource identifier or API path`);
|
|
||||||
case 429:
|
|
||||||
return new Error(`${base} - retry later or reduce request rate`);
|
|
||||||
default:
|
|
||||||
return new Error(base);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function sendJsonRequest(options: {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
url: string;
|
|
||||||
method: HttpMethod;
|
|
||||||
body?: unknown;
|
|
||||||
errorPrefix: string;
|
|
||||||
handleResponseError?: (response: Response) => Error | undefined;
|
|
||||||
}) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await fetchImpl(options.url, {
|
|
||||||
method: options.method,
|
|
||||||
headers: createJsonHeaders(options.config, options.body !== undefined),
|
|
||||||
...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const customError = options.handleResponseError?.(response);
|
|
||||||
|
|
||||||
if (customError) {
|
|
||||||
throw customError;
|
|
||||||
}
|
|
||||||
|
|
||||||
throw createStatusError(options.errorPrefix, response);
|
|
||||||
}
|
|
||||||
|
|
||||||
return parseResponse(response);
|
|
||||||
}
|
|
||||||
@@ -1,264 +0,0 @@
|
|||||||
import { markdownToAdf } from "./adf.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
|
|
||||||
|
|
||||||
const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
|
|
||||||
|
|
||||||
type JiraClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
jql: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
project?: string;
|
|
||||||
type: string;
|
|
||||||
summary: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
issue: string;
|
|
||||||
summary?: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
issue: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type TransitionInput = {
|
|
||||||
issue: string;
|
|
||||||
transition: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
|
|
||||||
const fields = (issue.fields ?? {}) as Record<string, unknown>;
|
|
||||||
const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
|
|
||||||
const status = (fields.status ?? {}) as Record<string, unknown>;
|
|
||||||
const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
key: String(issue.key ?? ""),
|
|
||||||
summary: String(fields.summary ?? ""),
|
|
||||||
issueType: String(issueType.name ?? ""),
|
|
||||||
status: String(status.name ?? ""),
|
|
||||||
assignee: assignee.displayName ? String(assignee.displayName) : undefined,
|
|
||||||
created: String(fields.created ?? ""),
|
|
||||||
updated: String(fields.updated ?? ""),
|
|
||||||
url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const url = new URL(path, `${config.jiraBaseUrl}/`);
|
|
||||||
|
|
||||||
return {
|
|
||||||
method,
|
|
||||||
url: url.toString(),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createJiraClient(options: JiraClientOptions) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const request = createRequest(options.config, method, path, body);
|
|
||||||
return sendJsonRequest({
|
|
||||||
config: options.config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send("POST", "/rest/api/3/search", {
|
|
||||||
jql: input.jql,
|
|
||||||
maxResults: input.maxResults,
|
|
||||||
startAt: input.startAt,
|
|
||||||
fields: [...ISSUE_FIELDS],
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const issues = Array.isArray(raw.issues) ? raw.issues : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
|
|
||||||
startAt: Number(raw.startAt ?? input.startAt),
|
|
||||||
maxResults: Number(raw.maxResults ?? input.maxResults),
|
|
||||||
total: Number(raw.total ?? issues.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getIssue(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
|
|
||||||
url.searchParams.set("fields", ISSUE_FIELDS.join(","));
|
|
||||||
|
|
||||||
const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: normalizeIssue(options.config, raw),
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send(
|
|
||||||
"GET",
|
|
||||||
`/rest/api/3/issue/${issue}/transitions`,
|
|
||||||
)) as { transitions?: Array<Record<string, unknown>> };
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
transitions: (raw.transitions ?? []).map((transition) => ({
|
|
||||||
id: String(transition.id ?? ""),
|
|
||||||
name: String(transition.name ?? ""),
|
|
||||||
toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
|
|
||||||
hasScreen: Boolean(transition.hasScreen),
|
|
||||||
})),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const project = input.project || options.config.defaultProject;
|
|
||||||
|
|
||||||
if (!project) {
|
|
||||||
throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
|
|
||||||
fields: {
|
|
||||||
project: { key: project },
|
|
||||||
issuetype: { name: input.type },
|
|
||||||
summary: input.summary,
|
|
||||||
...(input.description ? { description: markdownToAdf(input.description) } : {}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", "/rest/api/3/issue", request.body);
|
|
||||||
return { ok: true, data: raw };
|
|
||||||
},
|
|
||||||
|
|
||||||
async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const fields: Record<string, unknown> = {};
|
|
||||||
|
|
||||||
if (input.summary) {
|
|
||||||
fields.summary = input.summary;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (input.description) {
|
|
||||||
fields.description = markdownToAdf(input.description);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Object.keys(fields).length === 0) {
|
|
||||||
throw new Error("jira-update requires --summary and/or --description-file");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
|
|
||||||
fields,
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
updated: true,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
|
|
||||||
body: markdownToAdf(input.body),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(
|
|
||||||
options.config,
|
|
||||||
"POST",
|
|
||||||
`/rest/api/3/issue/${input.issue}/transitions`,
|
|
||||||
{
|
|
||||||
transition: {
|
|
||||||
id: input.transition,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
);
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
transitioned: true,
|
|
||||||
transition: input.transition,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
import type { CommandOutput, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
function renderText(payload: CommandOutput<unknown>) {
|
|
||||||
const data = payload.data as Record<string, unknown>;
|
|
||||||
|
|
||||||
if (Array.isArray(data?.issues)) {
|
|
||||||
return data.issues
|
|
||||||
.map((issue) => {
|
|
||||||
const item = issue as Record<string, string>;
|
|
||||||
return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (data?.issue && typeof data.issue === "object") {
|
|
||||||
const issue = data.issue as Record<string, string>;
|
|
||||||
return [
|
|
||||||
issue.key,
|
|
||||||
`${issue.issueType} | ${issue.status}`,
|
|
||||||
issue.summary,
|
|
||||||
issue.url,
|
|
||||||
].join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Array.isArray(data?.transitions)) {
|
|
||||||
return data.transitions
|
|
||||||
.map((transition) => {
|
|
||||||
const item = transition as Record<string, string>;
|
|
||||||
return `${item.id} ${item.name} -> ${item.toStatus}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
return JSON.stringify(payload, null, 2);
|
|
||||||
}
|
|
||||||
|
|
||||||
export function writeOutput(
|
|
||||||
writer: Writer,
|
|
||||||
payload: CommandOutput<unknown>,
|
|
||||||
format: OutputFormat = "json",
|
|
||||||
) {
|
|
||||||
const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
|
|
||||||
writer.write(`${body}\n`);
|
|
||||||
}
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
|
|
||||||
const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
|
|
||||||
|
|
||||||
type RawInput = {
|
|
||||||
product: "jira" | "confluence";
|
|
||||||
method: string;
|
|
||||||
path: string;
|
|
||||||
bodyFile?: string;
|
|
||||||
cwd: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function getAllowedPrefixes(product: RawInput["product"]) {
|
|
||||||
return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
|
|
||||||
const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
|
|
||||||
if (!["GET", "POST", "PUT"].includes(method)) {
|
|
||||||
throw new Error("raw only allows GET, POST, and PUT");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function validatePath(product: RawInput["product"], path: string) {
|
|
||||||
const allowedPrefixes = getAllowedPrefixes(product);
|
|
||||||
|
|
||||||
if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
|
|
||||||
throw new Error(`raw path is not allowed for ${product}: ${path}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readRawBody(bodyFile: string | undefined, cwd: string) {
|
|
||||||
if (!bodyFile) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contents = await readWorkspaceFile(bodyFile, cwd);
|
|
||||||
return JSON.parse(contents) as unknown;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runRawCommand(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
input: RawInput,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
validateMethod(input.method);
|
|
||||||
validatePath(input.product, input.path);
|
|
||||||
|
|
||||||
const body = await readRawBody(input.bodyFile, input.cwd);
|
|
||||||
const request = {
|
|
||||||
method: input.method,
|
|
||||||
url: buildUrl(config, input.product, input.path),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const data = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: input.method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Raw request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
export type AtlassianConfig = {
|
|
||||||
baseUrl: string;
|
|
||||||
jiraBaseUrl: string;
|
|
||||||
confluenceBaseUrl: string;
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
defaultProject?: string;
|
|
||||||
defaultSpace?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type CommandOutput<T> = {
|
|
||||||
ok: boolean;
|
|
||||||
data: T;
|
|
||||||
dryRun?: boolean;
|
|
||||||
raw?: unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type JiraIssueSummary = {
|
|
||||||
key: string;
|
|
||||||
summary: string;
|
|
||||||
issueType: string;
|
|
||||||
status: string;
|
|
||||||
assignee?: string;
|
|
||||||
created: string;
|
|
||||||
updated: string;
|
|
||||||
url: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type Writer = {
|
|
||||||
write(chunk: string | Uint8Array): unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type FetchLike = typeof fetch;
|
|
||||||
|
|
||||||
export type OutputFormat = "json" | "text";
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"target": "ES2022",
|
|
||||||
"module": "NodeNext",
|
|
||||||
"moduleResolution": "NodeNext",
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"forceConsistentCasingInFileNames": true,
|
|
||||||
"strict": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"resolveJsonModule": true,
|
|
||||||
"types": ["node"],
|
|
||||||
"outDir": "dist"
|
|
||||||
},
|
|
||||||
"include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
|
|
||||||
}
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
{
|
|
||||||
"name": "atlassian-skill-scripts",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"description": "Shared runtime for the Atlassian skill",
|
|
||||||
"type": "module",
|
|
||||||
"scripts": {
|
|
||||||
"atlassian": "tsx src/cli.ts",
|
|
||||||
"test": "node --import tsx --test tests/*.test.ts",
|
|
||||||
"typecheck": "tsc --noEmit",
|
|
||||||
"sync:agents": "tsx scripts/sync-agents.ts"
|
|
||||||
},
|
|
||||||
"dependencies": {
|
|
||||||
"commander": "^13.1.0",
|
|
||||||
"dotenv": "^16.4.7"
|
|
||||||
},
|
|
||||||
"devDependencies": {
|
|
||||||
"@types/node": "^24.3.0",
|
|
||||||
"tsx": "^4.20.5",
|
|
||||||
"typescript": "^5.9.2"
|
|
||||||
},
|
|
||||||
"packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
|
|
||||||
}
|
|
||||||
361
skills/atlassian/shared/scripts/pnpm-lock.yaml
generated
361
skills/atlassian/shared/scripts/pnpm-lock.yaml
generated
@@ -1,361 +0,0 @@
|
|||||||
lockfileVersion: '9.0'
|
|
||||||
|
|
||||||
settings:
|
|
||||||
autoInstallPeers: true
|
|
||||||
excludeLinksFromLockfile: false
|
|
||||||
|
|
||||||
importers:
|
|
||||||
|
|
||||||
.:
|
|
||||||
dependencies:
|
|
||||||
commander:
|
|
||||||
specifier: ^13.1.0
|
|
||||||
version: 13.1.0
|
|
||||||
dotenv:
|
|
||||||
specifier: ^16.4.7
|
|
||||||
version: 16.6.1
|
|
||||||
devDependencies:
|
|
||||||
'@types/node':
|
|
||||||
specifier: ^24.3.0
|
|
||||||
version: 24.12.0
|
|
||||||
tsx:
|
|
||||||
specifier: ^4.20.5
|
|
||||||
version: 4.21.0
|
|
||||||
typescript:
|
|
||||||
specifier: ^5.9.2
|
|
||||||
version: 5.9.3
|
|
||||||
|
|
||||||
packages:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [aix]
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [android]
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [freebsd]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [loong64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [mips64el]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ppc64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [riscv64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [s390x]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [linux]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [netbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [openbsd]
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [openharmony]
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [sunos]
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [arm64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [ia32]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
cpu: [x64]
|
|
||||||
os: [win32]
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
|
|
||||||
|
|
||||||
commander@13.1.0:
|
|
||||||
resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
|
|
||||||
dotenv@16.6.1:
|
|
||||||
resolution: {integrity: sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==}
|
|
||||||
engines: {node: '>=12'}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
|
|
||||||
engines: {node: '>=18'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
|
|
||||||
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
|
|
||||||
os: [darwin]
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0:
|
|
||||||
resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
|
|
||||||
engines: {node: '>=18.0.0'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
typescript@5.9.3:
|
|
||||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
|
||||||
engines: {node: '>=14.17'}
|
|
||||||
hasBin: true
|
|
||||||
|
|
||||||
undici-types@7.16.0:
|
|
||||||
resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
|
|
||||||
|
|
||||||
snapshots:
|
|
||||||
|
|
||||||
'@esbuild/aix-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/android-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/darwin-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/freebsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-arm@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-loong64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-mips64el@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-ppc64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-riscv64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-s390x@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/linux-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/netbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openbsd-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/openharmony-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/sunos-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-arm64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-ia32@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@esbuild/win32-x64@0.27.3':
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
'@types/node@24.12.0':
|
|
||||||
dependencies:
|
|
||||||
undici-types: 7.16.0
|
|
||||||
|
|
||||||
commander@13.1.0: {}
|
|
||||||
|
|
||||||
dotenv@16.6.1: {}
|
|
||||||
|
|
||||||
esbuild@0.27.3:
|
|
||||||
optionalDependencies:
|
|
||||||
'@esbuild/aix-ppc64': 0.27.3
|
|
||||||
'@esbuild/android-arm': 0.27.3
|
|
||||||
'@esbuild/android-arm64': 0.27.3
|
|
||||||
'@esbuild/android-x64': 0.27.3
|
|
||||||
'@esbuild/darwin-arm64': 0.27.3
|
|
||||||
'@esbuild/darwin-x64': 0.27.3
|
|
||||||
'@esbuild/freebsd-arm64': 0.27.3
|
|
||||||
'@esbuild/freebsd-x64': 0.27.3
|
|
||||||
'@esbuild/linux-arm': 0.27.3
|
|
||||||
'@esbuild/linux-arm64': 0.27.3
|
|
||||||
'@esbuild/linux-ia32': 0.27.3
|
|
||||||
'@esbuild/linux-loong64': 0.27.3
|
|
||||||
'@esbuild/linux-mips64el': 0.27.3
|
|
||||||
'@esbuild/linux-ppc64': 0.27.3
|
|
||||||
'@esbuild/linux-riscv64': 0.27.3
|
|
||||||
'@esbuild/linux-s390x': 0.27.3
|
|
||||||
'@esbuild/linux-x64': 0.27.3
|
|
||||||
'@esbuild/netbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/netbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openbsd-arm64': 0.27.3
|
|
||||||
'@esbuild/openbsd-x64': 0.27.3
|
|
||||||
'@esbuild/openharmony-arm64': 0.27.3
|
|
||||||
'@esbuild/sunos-x64': 0.27.3
|
|
||||||
'@esbuild/win32-arm64': 0.27.3
|
|
||||||
'@esbuild/win32-ia32': 0.27.3
|
|
||||||
'@esbuild/win32-x64': 0.27.3
|
|
||||||
|
|
||||||
fsevents@2.3.3:
|
|
||||||
optional: true
|
|
||||||
|
|
||||||
get-tsconfig@4.13.6:
|
|
||||||
dependencies:
|
|
||||||
resolve-pkg-maps: 1.0.0
|
|
||||||
|
|
||||||
resolve-pkg-maps@1.0.0: {}
|
|
||||||
|
|
||||||
tsx@4.21.0:
|
|
||||||
dependencies:
|
|
||||||
esbuild: 0.27.3
|
|
||||||
get-tsconfig: 4.13.6
|
|
||||||
optionalDependencies:
|
|
||||||
fsevents: 2.3.3
|
|
||||||
|
|
||||||
typescript@5.9.3: {}
|
|
||||||
|
|
||||||
undici-types@7.16.0: {}
|
|
||||||
@@ -1,60 +0,0 @@
|
|||||||
import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
import { fileURLToPath } from "node:url";
|
|
||||||
|
|
||||||
const __filename = fileURLToPath(import.meta.url);
|
|
||||||
const __dirname = path.dirname(__filename);
|
|
||||||
|
|
||||||
const SHARED_SCRIPTS_DIR = path.resolve(__dirname, "..");
|
|
||||||
const ATLASSIAN_SKILL_DIR = path.resolve(SHARED_SCRIPTS_DIR, "..", "..");
|
|
||||||
const AGENTS = ["codex", "claude-code", "cursor", "opencode"] as const;
|
|
||||||
const ENTRIES_TO_COPY = ["pnpm-lock.yaml", "tsconfig.json", "src"] as const;
|
|
||||||
|
|
||||||
async function replaceEntry(source: string, target: string) {
|
|
||||||
await rm(target, { recursive: true, force: true });
|
|
||||||
await cp(source, target, { recursive: true });
|
|
||||||
}
|
|
||||||
|
|
||||||
async function syncAgent(agent: (typeof AGENTS)[number]) {
|
|
||||||
const targetScriptsDir = path.join(ATLASSIAN_SKILL_DIR, agent, "scripts");
|
|
||||||
await mkdir(targetScriptsDir, { recursive: true });
|
|
||||||
|
|
||||||
for (const entry of ENTRIES_TO_COPY) {
|
|
||||||
await replaceEntry(
|
|
||||||
path.join(SHARED_SCRIPTS_DIR, entry),
|
|
||||||
path.join(targetScriptsDir, entry),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
const sourcePackageJson = JSON.parse(
|
|
||||||
await readFile(path.join(SHARED_SCRIPTS_DIR, "package.json"), "utf8"),
|
|
||||||
) as {
|
|
||||||
scripts?: Record<string, string>;
|
|
||||||
[key: string]: unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
sourcePackageJson.scripts = {
|
|
||||||
atlassian: sourcePackageJson.scripts?.atlassian ?? "tsx src/cli.ts",
|
|
||||||
typecheck: sourcePackageJson.scripts?.typecheck ?? "tsc --noEmit",
|
|
||||||
};
|
|
||||||
|
|
||||||
await writeFile(
|
|
||||||
path.join(targetScriptsDir, "package.json"),
|
|
||||||
`${JSON.stringify(sourcePackageJson, null, 2)}\n`,
|
|
||||||
"utf8",
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function main() {
|
|
||||||
for (const agent of AGENTS) {
|
|
||||||
await syncAgent(agent);
|
|
||||||
}
|
|
||||||
|
|
||||||
console.log(`Synced runtime bundle into ${AGENTS.length} agent script directories.`);
|
|
||||||
}
|
|
||||||
|
|
||||||
main().catch((error: unknown) => {
|
|
||||||
const message = error instanceof Error ? error.message : String(error);
|
|
||||||
console.error(message);
|
|
||||||
process.exitCode = 1;
|
|
||||||
});
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
const TEXT_NODE = "text";
|
|
||||||
|
|
||||||
function textNode(text: string) {
|
|
||||||
return {
|
|
||||||
type: TEXT_NODE,
|
|
||||||
text,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function paragraphNode(lines: string[]) {
|
|
||||||
const content: Array<{ type: string; text?: string }> = [];
|
|
||||||
|
|
||||||
lines.forEach((line, index) => {
|
|
||||||
if (index > 0) {
|
|
||||||
content.push({ type: "hardBreak" });
|
|
||||||
}
|
|
||||||
|
|
||||||
if (line.length > 0) {
|
|
||||||
content.push(textNode(line));
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "paragraph",
|
|
||||||
...(content.length > 0 ? { content } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function markdownToAdf(input: string) {
|
|
||||||
const lines = input.replace(/\r\n/g, "\n").split("\n");
|
|
||||||
const content: Array<Record<string, unknown>> = [];
|
|
||||||
let index = 0;
|
|
||||||
|
|
||||||
while (index < lines.length) {
|
|
||||||
const current = lines[index]?.trimEnd() ?? "";
|
|
||||||
|
|
||||||
if (current.trim().length === 0) {
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const heading = current.match(/^(#{1,6})\s+(.*)$/);
|
|
||||||
|
|
||||||
if (heading) {
|
|
||||||
content.push({
|
|
||||||
type: "heading",
|
|
||||||
attrs: { level: heading[1].length },
|
|
||||||
content: [textNode(heading[2])],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (/^[-*]\s+/.test(current)) {
|
|
||||||
const items: Array<Record<string, unknown>> = [];
|
|
||||||
|
|
||||||
while (index < lines.length && /^[-*]\s+/.test(lines[index] ?? "")) {
|
|
||||||
items.push({
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [textNode((lines[index] ?? "").replace(/^[-*]\s+/, ""))],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push({
|
|
||||||
type: "bulletList",
|
|
||||||
content: items,
|
|
||||||
});
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const paragraphLines: string[] = [];
|
|
||||||
|
|
||||||
while (index < lines.length && (lines[index]?.trim().length ?? 0) > 0) {
|
|
||||||
paragraphLines.push(lines[index] ?? "");
|
|
||||||
index += 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
content.push(paragraphNode(paragraphLines));
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
type: "doc",
|
|
||||||
version: 1,
|
|
||||||
content,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,332 +0,0 @@
|
|||||||
import process from "node:process";
|
|
||||||
import { pathToFileURL } from "node:url";
|
|
||||||
|
|
||||||
import { Command } from "commander";
|
|
||||||
|
|
||||||
import { createConfluenceClient } from "./confluence.js";
|
|
||||||
import { loadConfig } from "./config.js";
|
|
||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { runHealthCheck } from "./health.js";
|
|
||||||
import { createJiraClient } from "./jira.js";
|
|
||||||
import { writeOutput } from "./output.js";
|
|
||||||
import { runRawCommand } from "./raw.js";
|
|
||||||
import type { FetchLike, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
type CliContext = {
|
|
||||||
cwd?: string;
|
|
||||||
env?: NodeJS.ProcessEnv;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
stdout?: Writer;
|
|
||||||
stderr?: Writer;
|
|
||||||
};
|
|
||||||
|
|
||||||
function resolveFormat(format: string | undefined): OutputFormat {
|
|
||||||
return format === "text" ? "text" : "json";
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRuntime(context: CliContext) {
|
|
||||||
const cwd = context.cwd ?? process.cwd();
|
|
||||||
const env = context.env ?? process.env;
|
|
||||||
const stdout = context.stdout ?? process.stdout;
|
|
||||||
const stderr = context.stderr ?? process.stderr;
|
|
||||||
let configCache: ReturnType<typeof loadConfig> | undefined;
|
|
||||||
let jiraCache: ReturnType<typeof createJiraClient> | undefined;
|
|
||||||
let confluenceCache: ReturnType<typeof createConfluenceClient> | undefined;
|
|
||||||
|
|
||||||
function getConfig() {
|
|
||||||
configCache ??= loadConfig(env, { cwd });
|
|
||||||
return configCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getJiraClient() {
|
|
||||||
jiraCache ??= createJiraClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return jiraCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
function getConfluenceClient() {
|
|
||||||
confluenceCache ??= createConfluenceClient({
|
|
||||||
config: getConfig(),
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
});
|
|
||||||
return confluenceCache;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readBodyFile(filePath: string | undefined) {
|
|
||||||
if (!filePath) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
return readWorkspaceFile(filePath, cwd);
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
cwd,
|
|
||||||
stdout,
|
|
||||||
stderr,
|
|
||||||
readBodyFile,
|
|
||||||
getConfig,
|
|
||||||
getJiraClient,
|
|
||||||
getConfluenceClient,
|
|
||||||
fetchImpl: context.fetchImpl,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function buildProgram(context: CliContext = {}) {
|
|
||||||
const runtime = createRuntime(context);
|
|
||||||
const program = new Command()
|
|
||||||
.name("atlassian")
|
|
||||||
.description("Portable Atlassian CLI for multi-agent skills")
|
|
||||||
.version("0.1.0");
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("health")
|
|
||||||
.description("Validate configuration and Atlassian connectivity")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runHealthCheck(runtime.getConfig(), runtime.fetchImpl);
|
|
||||||
writeOutput(
|
|
||||||
runtime.stdout,
|
|
||||||
payload,
|
|
||||||
resolveFormat(options.format),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-search")
|
|
||||||
.requiredOption("--query <query>", "CQL search query")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().searchPages({
|
|
||||||
query: options.query,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-get")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().getPage(options.page);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-create")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--space <space>", "Confluence space ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().createPage({
|
|
||||||
space: options.space,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-update")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--title <title>", "Confluence page title")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().updatePage({
|
|
||||||
pageId: options.page,
|
|
||||||
title: options.title,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-comment")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative storage-format body file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().commentPage({
|
|
||||||
pageId: options.page,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("conf-children")
|
|
||||||
.requiredOption("--page <page>", "Confluence page ID")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Cursor/start token", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getConfluenceClient().listChildren(
|
|
||||||
options.page,
|
|
||||||
Number(options.maxResults),
|
|
||||||
Number(options.startAt),
|
|
||||||
);
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("raw")
|
|
||||||
.requiredOption("--product <product>", "jira or confluence")
|
|
||||||
.requiredOption("--method <method>", "GET, POST, or PUT")
|
|
||||||
.requiredOption("--path <path>", "Validated API path")
|
|
||||||
.option("--body-file <path>", "Workspace-relative JSON file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runRawCommand(runtime.getConfig(), runtime.fetchImpl, {
|
|
||||||
product: options.product,
|
|
||||||
method: String(options.method).toUpperCase(),
|
|
||||||
path: options.path,
|
|
||||||
bodyFile: options.bodyFile,
|
|
||||||
cwd: runtime.cwd,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-search")
|
|
||||||
.requiredOption("--jql <jql>", "JQL expression to execute")
|
|
||||||
.option("--max-results <number>", "Maximum results to return", "50")
|
|
||||||
.option("--start-at <number>", "Result offset", "0")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().searchIssues({
|
|
||||||
jql: options.jql,
|
|
||||||
maxResults: Number(options.maxResults),
|
|
||||||
startAt: Number(options.startAt),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-get")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getIssue(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-create")
|
|
||||||
.requiredOption("--type <type>", "Issue type name")
|
|
||||||
.requiredOption("--summary <summary>", "Issue summary")
|
|
||||||
.option("--project <project>", "Project key")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().createIssue({
|
|
||||||
project: options.project,
|
|
||||||
type: options.type,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-update")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--summary <summary>", "Updated summary")
|
|
||||||
.option("--description-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().updateIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
summary: options.summary,
|
|
||||||
description: await runtime.readBodyFile(options.descriptionFile),
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-comment")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--body-file <path>", "Workspace-relative markdown/text file")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().commentIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
body: (await runtime.readBodyFile(options.bodyFile)) as string,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transitions")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().getTransitions(options.issue);
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
program
|
|
||||||
.command("jira-transition")
|
|
||||||
.requiredOption("--issue <issue>", "Issue key")
|
|
||||||
.requiredOption("--transition <transition>", "Transition ID")
|
|
||||||
.option("--dry-run", "Print the request without sending it")
|
|
||||||
.option("--format <format>", "Output format", "json")
|
|
||||||
.action(async (options) => {
|
|
||||||
const payload = await runtime.getJiraClient().transitionIssue({
|
|
||||||
issue: options.issue,
|
|
||||||
transition: options.transition,
|
|
||||||
dryRun: Boolean(options.dryRun),
|
|
||||||
});
|
|
||||||
|
|
||||||
writeOutput(runtime.stdout, payload, resolveFormat(options.format));
|
|
||||||
});
|
|
||||||
|
|
||||||
return program;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runCli(argv = process.argv, context: CliContext = {}) {
|
|
||||||
const program = buildProgram(context);
|
|
||||||
await program.parseAsync(argv);
|
|
||||||
}
|
|
||||||
|
|
||||||
const isDirectExecution =
|
|
||||||
Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
|
|
||||||
|
|
||||||
if (isDirectExecution) {
|
|
||||||
runCli().catch((error: unknown) => {
|
|
||||||
const message = error instanceof Error ? error.message : String(error);
|
|
||||||
process.stderr.write(`${message}\n`);
|
|
||||||
process.exitCode = 1;
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
import path from "node:path";
|
|
||||||
|
|
||||||
import { config as loadDotEnv } from "dotenv";
|
|
||||||
|
|
||||||
import type { AtlassianConfig } from "./types.js";
|
|
||||||
|
|
||||||
function normalizeBaseUrl(value: string) {
|
|
||||||
return value.replace(/\/+$/, "");
|
|
||||||
}
|
|
||||||
|
|
||||||
function readRequired(env: NodeJS.ProcessEnv, key: string) {
|
|
||||||
const value = env[key]?.trim();
|
|
||||||
|
|
||||||
if (!value) {
|
|
||||||
throw new Error(`Missing required environment variable: ${key}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return value;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function loadConfig(
|
|
||||||
env: NodeJS.ProcessEnv = process.env,
|
|
||||||
options?: {
|
|
||||||
cwd?: string;
|
|
||||||
},
|
|
||||||
): AtlassianConfig {
|
|
||||||
loadDotEnv({
|
|
||||||
path: path.resolve(options?.cwd ?? process.cwd(), ".env"),
|
|
||||||
processEnv: env as Record<string, string>,
|
|
||||||
override: false,
|
|
||||||
});
|
|
||||||
|
|
||||||
const baseUrl = normalizeBaseUrl(readRequired(env, "ATLASSIAN_BASE_URL"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
baseUrl,
|
|
||||||
jiraBaseUrl: normalizeBaseUrl(env.ATLASSIAN_JIRA_BASE_URL?.trim() || baseUrl),
|
|
||||||
confluenceBaseUrl: normalizeBaseUrl(env.ATLASSIAN_CONFLUENCE_BASE_URL?.trim() || baseUrl),
|
|
||||||
email: readRequired(env, "ATLASSIAN_EMAIL"),
|
|
||||||
apiToken: readRequired(env, "ATLASSIAN_API_TOKEN"),
|
|
||||||
defaultProject: env.ATLASSIAN_DEFAULT_PROJECT?.trim() || undefined,
|
|
||||||
defaultSpace: env.ATLASSIAN_DEFAULT_SPACE?.trim() || undefined,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createBasicAuthHeader(config: {
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
[key: string]: unknown;
|
|
||||||
}) {
|
|
||||||
return `Basic ${Buffer.from(`${config.email}:${config.apiToken}`).toString("base64")}`;
|
|
||||||
}
|
|
||||||
@@ -1,292 +0,0 @@
|
|||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ConfluenceClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
query: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
space?: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
pageId: string;
|
|
||||||
title: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
pageId: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type PageSummary = {
|
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
type: string;
|
|
||||||
status?: string;
|
|
||||||
spaceId?: string;
|
|
||||||
url?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function normalizePage(baseUrl: string, page: Record<string, unknown>, excerpt?: string) {
|
|
||||||
const links = (page._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
id: String(page.id ?? ""),
|
|
||||||
title: String(page.title ?? ""),
|
|
||||||
type: String(page.type ?? "page"),
|
|
||||||
...(page.status ? { status: String(page.status) } : {}),
|
|
||||||
...(page.spaceId ? { spaceId: String(page.spaceId) } : {}),
|
|
||||||
...(excerpt ? { excerpt } : {}),
|
|
||||||
...(links.webui ? { url: `${baseUrl}${String(links.webui)}` } : {}),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createConfluenceClient(options: ConfluenceClientOptions) {
|
|
||||||
const config = options.config;
|
|
||||||
|
|
||||||
async function getPageForUpdate(pageId: string) {
|
|
||||||
return (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchPages(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL("/wiki/rest/api/search", `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("cql", input.query);
|
|
||||||
url.searchParams.set("limit", String(input.maxResults));
|
|
||||||
url.searchParams.set("start", String(input.startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((entry) => {
|
|
||||||
const result = entry as Record<string, unknown>;
|
|
||||||
return normalizePage(
|
|
||||||
config.baseUrl,
|
|
||||||
(result.content ?? {}) as Record<string, unknown>,
|
|
||||||
result.excerpt ? String(result.excerpt) : undefined,
|
|
||||||
);
|
|
||||||
}),
|
|
||||||
startAt: Number(raw.start ?? input.startAt),
|
|
||||||
maxResults: Number(raw.limit ?? input.maxResults),
|
|
||||||
total: Number(raw.totalSize ?? raw.size ?? results.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getPage(pageId: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${pageId}?body-format=storage`),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const body = ((raw.body ?? {}) as Record<string, unknown>).storage as Record<string, unknown> | undefined;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
page: {
|
|
||||||
...normalizePage(config.baseUrl, raw),
|
|
||||||
version: Number((((raw.version ?? {}) as Record<string, unknown>).number ?? 0)),
|
|
||||||
body: body?.value ? String(body.value) : "",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async listChildren(pageId: string, maxResults: number, startAt: number): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/wiki/api/v2/pages/${pageId}/direct-children`, `${config.confluenceBaseUrl}/`);
|
|
||||||
url.searchParams.set("limit", String(maxResults));
|
|
||||||
url.searchParams.set("cursor", String(startAt));
|
|
||||||
|
|
||||||
const raw = (await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: url.toString(),
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const results = Array.isArray(raw.results) ? raw.results : [];
|
|
||||||
const links = (raw._links ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: results.map((page) => normalizePage(config.baseUrl, page as Record<string, unknown>)),
|
|
||||||
nextCursor: links.next ? String(links.next) : null,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createPage(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const spaceId = input.space || config.defaultSpace;
|
|
||||||
|
|
||||||
if (!spaceId) {
|
|
||||||
throw new Error("conf-create requires --space or ATLASSIAN_DEFAULT_SPACE");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/pages"),
|
|
||||||
body: {
|
|
||||||
spaceId,
|
|
||||||
title: input.title,
|
|
||||||
status: "current",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async updatePage(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const currentPage = await getPageForUpdate(input.pageId);
|
|
||||||
const version = (((currentPage.version ?? {}) as Record<string, unknown>).number ?? 0) as number;
|
|
||||||
const spaceId = String(currentPage.spaceId ?? "");
|
|
||||||
|
|
||||||
const request = {
|
|
||||||
method: "PUT" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, `/wiki/api/v2/pages/${input.pageId}`),
|
|
||||||
body: {
|
|
||||||
id: input.pageId,
|
|
||||||
status: String(currentPage.status ?? "current"),
|
|
||||||
title: input.title,
|
|
||||||
spaceId,
|
|
||||||
version: {
|
|
||||||
number: Number(version) + 1,
|
|
||||||
},
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
handleResponseError(response) {
|
|
||||||
if (response.status === 409) {
|
|
||||||
return new Error(`Confluence update conflict: page ${input.pageId} was updated by someone else`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return undefined;
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentPage(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = {
|
|
||||||
method: "POST" as const,
|
|
||||||
url: buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/footer-comments"),
|
|
||||||
body: {
|
|
||||||
pageId: input.pageId,
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: input.body,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: request.method,
|
|
||||||
body: request.body,
|
|
||||||
errorPrefix: "Confluence request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
import { readFile } from "node:fs/promises";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
export async function readWorkspaceFile(filePath: string, cwd: string) {
|
|
||||||
const resolved = path.resolve(cwd, filePath);
|
|
||||||
const relative = path.relative(cwd, resolved);
|
|
||||||
|
|
||||||
if (relative.startsWith("..") || path.isAbsolute(relative)) {
|
|
||||||
throw new Error(`--body-file must stay within the active workspace: ${filePath}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return readFile(resolved, "utf8");
|
|
||||||
}
|
|
||||||
@@ -1,69 +0,0 @@
|
|||||||
import { createJsonHeaders, createStatusError } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
type ProductHealth = {
|
|
||||||
ok: boolean;
|
|
||||||
status?: number;
|
|
||||||
message?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
function buildUrl(baseUrl: string, path: string) {
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runHealthCheck(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
const client = fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!client) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function probe(product: "Jira" | "Confluence", url: string): Promise<ProductHealth> {
|
|
||||||
try {
|
|
||||||
const response = await client(url, {
|
|
||||||
method: "GET",
|
|
||||||
headers: createJsonHeaders(config, false),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const error = createStatusError(`${product} health check failed`, response);
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
status: response.status,
|
|
||||||
message: error.message,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
status: response.status,
|
|
||||||
};
|
|
||||||
} catch (error: unknown) {
|
|
||||||
return {
|
|
||||||
ok: false,
|
|
||||||
message: error instanceof Error ? error.message : String(error),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const jira = await probe("Jira", buildUrl(config.jiraBaseUrl, "/rest/api/3/myself"));
|
|
||||||
const confluence = await probe("Confluence", buildUrl(config.confluenceBaseUrl, "/wiki/api/v2/spaces?limit=1"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: jira.ok && confluence.ok,
|
|
||||||
data: {
|
|
||||||
baseUrl: config.baseUrl,
|
|
||||||
jiraBaseUrl: config.jiraBaseUrl,
|
|
||||||
confluenceBaseUrl: config.confluenceBaseUrl,
|
|
||||||
defaultProject: config.defaultProject,
|
|
||||||
defaultSpace: config.defaultSpace,
|
|
||||||
products: {
|
|
||||||
jira,
|
|
||||||
confluence,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
import { createBasicAuthHeader } from "./config.js";
|
|
||||||
import type { AtlassianConfig, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
export type HttpMethod = "GET" | "POST" | "PUT";
|
|
||||||
|
|
||||||
export function createJsonHeaders(config: AtlassianConfig, includeJsonBody: boolean) {
|
|
||||||
const headers: Array<[string, string]> = [
|
|
||||||
["Accept", "application/json"],
|
|
||||||
["Authorization", createBasicAuthHeader(config)],
|
|
||||||
];
|
|
||||||
|
|
||||||
if (includeJsonBody) {
|
|
||||||
headers.push(["Content-Type", "application/json"]);
|
|
||||||
}
|
|
||||||
|
|
||||||
return headers;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function parseResponse(response: Response) {
|
|
||||||
if (response.status === 204) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contentType = response.headers.get("content-type") ?? "";
|
|
||||||
|
|
||||||
if (contentType.includes("application/json")) {
|
|
||||||
try {
|
|
||||||
return await response.json();
|
|
||||||
} catch {
|
|
||||||
throw new Error("Malformed JSON response from Atlassian API");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return response.text();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createStatusError(errorPrefix: string, response: Response) {
|
|
||||||
const base = `${errorPrefix}: ${response.status} ${response.statusText}`;
|
|
||||||
|
|
||||||
switch (response.status) {
|
|
||||||
case 401:
|
|
||||||
return new Error(`${base} - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN`);
|
|
||||||
case 403:
|
|
||||||
return new Error(`${base} - verify product permissions for this account`);
|
|
||||||
case 404:
|
|
||||||
return new Error(`${base} - verify the resource identifier or API path`);
|
|
||||||
case 429:
|
|
||||||
return new Error(`${base} - retry later or reduce request rate`);
|
|
||||||
default:
|
|
||||||
return new Error(base);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function sendJsonRequest(options: {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
url: string;
|
|
||||||
method: HttpMethod;
|
|
||||||
body?: unknown;
|
|
||||||
errorPrefix: string;
|
|
||||||
handleResponseError?: (response: Response) => Error | undefined;
|
|
||||||
}) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await fetchImpl(options.url, {
|
|
||||||
method: options.method,
|
|
||||||
headers: createJsonHeaders(options.config, options.body !== undefined),
|
|
||||||
...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
const customError = options.handleResponseError?.(response);
|
|
||||||
|
|
||||||
if (customError) {
|
|
||||||
throw customError;
|
|
||||||
}
|
|
||||||
|
|
||||||
throw createStatusError(options.errorPrefix, response);
|
|
||||||
}
|
|
||||||
|
|
||||||
return parseResponse(response);
|
|
||||||
}
|
|
||||||
@@ -1,264 +0,0 @@
|
|||||||
import { markdownToAdf } from "./adf.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
|
|
||||||
|
|
||||||
const ISSUE_FIELDS = ["summary", "issuetype", "status", "assignee", "created", "updated"] as const;
|
|
||||||
|
|
||||||
type JiraClientOptions = {
|
|
||||||
config: AtlassianConfig;
|
|
||||||
fetchImpl?: FetchLike;
|
|
||||||
};
|
|
||||||
|
|
||||||
type SearchInput = {
|
|
||||||
jql: string;
|
|
||||||
maxResults: number;
|
|
||||||
startAt: number;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CreateInput = {
|
|
||||||
project?: string;
|
|
||||||
type: string;
|
|
||||||
summary: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type UpdateInput = {
|
|
||||||
issue: string;
|
|
||||||
summary?: string;
|
|
||||||
description?: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type CommentInput = {
|
|
||||||
issue: string;
|
|
||||||
body: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
type TransitionInput = {
|
|
||||||
issue: string;
|
|
||||||
transition: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function normalizeIssue(config: AtlassianConfig, issue: Record<string, unknown>): JiraIssueSummary {
|
|
||||||
const fields = (issue.fields ?? {}) as Record<string, unknown>;
|
|
||||||
const issueType = (fields.issuetype ?? {}) as Record<string, unknown>;
|
|
||||||
const status = (fields.status ?? {}) as Record<string, unknown>;
|
|
||||||
const assignee = (fields.assignee ?? {}) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
key: String(issue.key ?? ""),
|
|
||||||
summary: String(fields.summary ?? ""),
|
|
||||||
issueType: String(issueType.name ?? ""),
|
|
||||||
status: String(status.name ?? ""),
|
|
||||||
assignee: assignee.displayName ? String(assignee.displayName) : undefined,
|
|
||||||
created: String(fields.created ?? ""),
|
|
||||||
updated: String(fields.updated ?? ""),
|
|
||||||
url: `${config.baseUrl}/browse/${issue.key ?? ""}`,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function createRequest(config: AtlassianConfig, method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const url = new URL(path, `${config.jiraBaseUrl}/`);
|
|
||||||
|
|
||||||
return {
|
|
||||||
method,
|
|
||||||
url: url.toString(),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createJiraClient(options: JiraClientOptions) {
|
|
||||||
const fetchImpl = options.fetchImpl ?? globalThis.fetch;
|
|
||||||
|
|
||||||
if (!fetchImpl) {
|
|
||||||
throw new Error("Fetch API is not available in this runtime");
|
|
||||||
}
|
|
||||||
|
|
||||||
async function send(method: "GET" | "POST" | "PUT", path: string, body?: unknown) {
|
|
||||||
const request = createRequest(options.config, method, path, body);
|
|
||||||
return sendJsonRequest({
|
|
||||||
config: options.config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
async searchIssues(input: SearchInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send("POST", "/rest/api/3/search", {
|
|
||||||
jql: input.jql,
|
|
||||||
maxResults: input.maxResults,
|
|
||||||
startAt: input.startAt,
|
|
||||||
fields: [...ISSUE_FIELDS],
|
|
||||||
})) as Record<string, unknown>;
|
|
||||||
|
|
||||||
const issues = Array.isArray(raw.issues) ? raw.issues : [];
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issues: issues.map((issue) => normalizeIssue(options.config, issue as Record<string, unknown>)),
|
|
||||||
startAt: Number(raw.startAt ?? input.startAt),
|
|
||||||
maxResults: Number(raw.maxResults ?? input.maxResults),
|
|
||||||
total: Number(raw.total ?? issues.length),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getIssue(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const url = new URL(`/rest/api/3/issue/${issue}`, `${options.config.jiraBaseUrl}/`);
|
|
||||||
url.searchParams.set("fields", ISSUE_FIELDS.join(","));
|
|
||||||
|
|
||||||
const raw = (await send("GET", `${url.pathname}${url.search}`)) as Record<string, unknown>;
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: normalizeIssue(options.config, raw),
|
|
||||||
},
|
|
||||||
raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async getTransitions(issue: string): Promise<CommandOutput<unknown>> {
|
|
||||||
const raw = (await send(
|
|
||||||
"GET",
|
|
||||||
`/rest/api/3/issue/${issue}/transitions`,
|
|
||||||
)) as { transitions?: Array<Record<string, unknown>> };
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
transitions: (raw.transitions ?? []).map((transition) => ({
|
|
||||||
id: String(transition.id ?? ""),
|
|
||||||
name: String(transition.name ?? ""),
|
|
||||||
toStatus: String(((transition.to ?? {}) as Record<string, unknown>).name ?? ""),
|
|
||||||
hasScreen: Boolean(transition.hasScreen),
|
|
||||||
})),
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async createIssue(input: CreateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const project = input.project || options.config.defaultProject;
|
|
||||||
|
|
||||||
if (!project) {
|
|
||||||
throw new Error("jira-create requires --project or ATLASSIAN_DEFAULT_PROJECT");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "POST", "/rest/api/3/issue", {
|
|
||||||
fields: {
|
|
||||||
project: { key: project },
|
|
||||||
issuetype: { name: input.type },
|
|
||||||
summary: input.summary,
|
|
||||||
...(input.description ? { description: markdownToAdf(input.description) } : {}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", "/rest/api/3/issue", request.body);
|
|
||||||
return { ok: true, data: raw };
|
|
||||||
},
|
|
||||||
|
|
||||||
async updateIssue(input: UpdateInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const fields: Record<string, unknown> = {};
|
|
||||||
|
|
||||||
if (input.summary) {
|
|
||||||
fields.summary = input.summary;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (input.description) {
|
|
||||||
fields.description = markdownToAdf(input.description);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Object.keys(fields).length === 0) {
|
|
||||||
throw new Error("jira-update requires --summary and/or --description-file");
|
|
||||||
}
|
|
||||||
|
|
||||||
const request = createRequest(options.config, "PUT", `/rest/api/3/issue/${input.issue}`, {
|
|
||||||
fields,
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
updated: true,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async commentIssue(input: CommentInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(options.config, "POST", `/rest/api/3/issue/${input.issue}/comment`, {
|
|
||||||
body: markdownToAdf(input.body),
|
|
||||||
});
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: raw,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
async transitionIssue(input: TransitionInput): Promise<CommandOutput<unknown>> {
|
|
||||||
const request = createRequest(
|
|
||||||
options.config,
|
|
||||||
"POST",
|
|
||||||
`/rest/api/3/issue/${input.issue}/transitions`,
|
|
||||||
{
|
|
||||||
transition: {
|
|
||||||
id: input.transition,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
);
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: input.issue,
|
|
||||||
transitioned: true,
|
|
||||||
transition: input.transition,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
import type { CommandOutput, OutputFormat, Writer } from "./types.js";
|
|
||||||
|
|
||||||
function renderText(payload: CommandOutput<unknown>) {
|
|
||||||
const data = payload.data as Record<string, unknown>;
|
|
||||||
|
|
||||||
if (Array.isArray(data?.issues)) {
|
|
||||||
return data.issues
|
|
||||||
.map((issue) => {
|
|
||||||
const item = issue as Record<string, string>;
|
|
||||||
return `${item.key} [${item.status}] ${item.issueType} - ${item.summary}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (data?.issue && typeof data.issue === "object") {
|
|
||||||
const issue = data.issue as Record<string, string>;
|
|
||||||
return [
|
|
||||||
issue.key,
|
|
||||||
`${issue.issueType} | ${issue.status}`,
|
|
||||||
issue.summary,
|
|
||||||
issue.url,
|
|
||||||
].join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
if (Array.isArray(data?.transitions)) {
|
|
||||||
return data.transitions
|
|
||||||
.map((transition) => {
|
|
||||||
const item = transition as Record<string, string>;
|
|
||||||
return `${item.id} ${item.name} -> ${item.toStatus}`;
|
|
||||||
})
|
|
||||||
.join("\n");
|
|
||||||
}
|
|
||||||
|
|
||||||
return JSON.stringify(payload, null, 2);
|
|
||||||
}
|
|
||||||
|
|
||||||
export function writeOutput(
|
|
||||||
writer: Writer,
|
|
||||||
payload: CommandOutput<unknown>,
|
|
||||||
format: OutputFormat = "json",
|
|
||||||
) {
|
|
||||||
const body = format === "text" ? renderText(payload) : JSON.stringify(payload, null, 2);
|
|
||||||
writer.write(`${body}\n`);
|
|
||||||
}
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
import { readWorkspaceFile } from "./files.js";
|
|
||||||
import { sendJsonRequest } from "./http.js";
|
|
||||||
import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
|
|
||||||
|
|
||||||
const JIRA_ALLOWED_PREFIXES = ["/rest/api/3/"] as const;
|
|
||||||
const CONFLUENCE_ALLOWED_PREFIXES = ["/wiki/api/v2/", "/wiki/rest/api/"] as const;
|
|
||||||
|
|
||||||
type RawInput = {
|
|
||||||
product: "jira" | "confluence";
|
|
||||||
method: string;
|
|
||||||
path: string;
|
|
||||||
bodyFile?: string;
|
|
||||||
cwd: string;
|
|
||||||
dryRun?: boolean;
|
|
||||||
};
|
|
||||||
|
|
||||||
function getAllowedPrefixes(product: RawInput["product"]) {
|
|
||||||
return product === "jira" ? JIRA_ALLOWED_PREFIXES : CONFLUENCE_ALLOWED_PREFIXES;
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildUrl(config: AtlassianConfig, product: RawInput["product"], path: string) {
|
|
||||||
const baseUrl = product === "jira" ? config.jiraBaseUrl : config.confluenceBaseUrl;
|
|
||||||
return new URL(path, `${baseUrl}/`).toString();
|
|
||||||
}
|
|
||||||
|
|
||||||
function validateMethod(method: string): asserts method is "GET" | "POST" | "PUT" {
|
|
||||||
if (!["GET", "POST", "PUT"].includes(method)) {
|
|
||||||
throw new Error("raw only allows GET, POST, and PUT");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
function validatePath(product: RawInput["product"], path: string) {
|
|
||||||
const allowedPrefixes = getAllowedPrefixes(product);
|
|
||||||
|
|
||||||
if (!allowedPrefixes.some((prefix) => path.startsWith(prefix))) {
|
|
||||||
throw new Error(`raw path is not allowed for ${product}: ${path}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function readRawBody(bodyFile: string | undefined, cwd: string) {
|
|
||||||
if (!bodyFile) {
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
const contents = await readWorkspaceFile(bodyFile, cwd);
|
|
||||||
return JSON.parse(contents) as unknown;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runRawCommand(
|
|
||||||
config: AtlassianConfig,
|
|
||||||
fetchImpl: FetchLike | undefined,
|
|
||||||
input: RawInput,
|
|
||||||
): Promise<CommandOutput<unknown>> {
|
|
||||||
validateMethod(input.method);
|
|
||||||
validatePath(input.product, input.path);
|
|
||||||
|
|
||||||
const body = await readRawBody(input.bodyFile, input.cwd);
|
|
||||||
const request = {
|
|
||||||
method: input.method,
|
|
||||||
url: buildUrl(config, input.product, input.path),
|
|
||||||
...(body === undefined ? {} : { body }),
|
|
||||||
};
|
|
||||||
|
|
||||||
if (input.dryRun) {
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: request,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const data = await sendJsonRequest({
|
|
||||||
config,
|
|
||||||
fetchImpl,
|
|
||||||
url: request.url,
|
|
||||||
method: input.method,
|
|
||||||
body,
|
|
||||||
errorPrefix: "Raw request failed",
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
ok: true,
|
|
||||||
data,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
export type AtlassianConfig = {
|
|
||||||
baseUrl: string;
|
|
||||||
jiraBaseUrl: string;
|
|
||||||
confluenceBaseUrl: string;
|
|
||||||
email: string;
|
|
||||||
apiToken: string;
|
|
||||||
defaultProject?: string;
|
|
||||||
defaultSpace?: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type CommandOutput<T> = {
|
|
||||||
ok: boolean;
|
|
||||||
data: T;
|
|
||||||
dryRun?: boolean;
|
|
||||||
raw?: unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type JiraIssueSummary = {
|
|
||||||
key: string;
|
|
||||||
summary: string;
|
|
||||||
issueType: string;
|
|
||||||
status: string;
|
|
||||||
assignee?: string;
|
|
||||||
created: string;
|
|
||||||
updated: string;
|
|
||||||
url: string;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type Writer = {
|
|
||||||
write(chunk: string | Uint8Array): unknown;
|
|
||||||
};
|
|
||||||
|
|
||||||
export type FetchLike = typeof fetch;
|
|
||||||
|
|
||||||
export type OutputFormat = "json" | "text";
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
import test from "node:test";
|
|
||||||
import assert from "node:assert/strict";
|
|
||||||
import { spawnSync } from "node:child_process";
|
|
||||||
|
|
||||||
test("CLI help prints the Atlassian skill banner", () => {
|
|
||||||
const result = spawnSync("pnpm", ["exec", "tsx", "src/cli.ts", "--help"], {
|
|
||||||
cwd: new URL("../", import.meta.url),
|
|
||||||
encoding: "utf8",
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.equal(result.status, 0, result.stderr);
|
|
||||||
assert.match(result.stdout, /Portable Atlassian CLI for multi-agent skills/);
|
|
||||||
assert.match(result.stdout, /Usage:/);
|
|
||||||
});
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
import test from "node:test";
|
|
||||||
import assert from "node:assert/strict";
|
|
||||||
|
|
||||||
import { createBasicAuthHeader, loadConfig } from "../src/config.js";
|
|
||||||
|
|
||||||
test("loadConfig derives Jira and Confluence base URLs from ATLASSIAN_BASE_URL", () => {
|
|
||||||
const config = loadConfig({
|
|
||||||
ATLASSIAN_BASE_URL: "https://example.atlassian.net/",
|
|
||||||
ATLASSIAN_EMAIL: "dev@example.com",
|
|
||||||
ATLASSIAN_API_TOKEN: "secret-token",
|
|
||||||
ATLASSIAN_DEFAULT_PROJECT: "ENG",
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(config, {
|
|
||||||
baseUrl: "https://example.atlassian.net",
|
|
||||||
jiraBaseUrl: "https://example.atlassian.net",
|
|
||||||
confluenceBaseUrl: "https://example.atlassian.net",
|
|
||||||
email: "dev@example.com",
|
|
||||||
apiToken: "secret-token",
|
|
||||||
defaultProject: "ENG",
|
|
||||||
defaultSpace: undefined,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("createBasicAuthHeader encodes email and API token for Atlassian Cloud", () => {
|
|
||||||
const header = createBasicAuthHeader({
|
|
||||||
baseUrl: "https://example.atlassian.net",
|
|
||||||
jiraBaseUrl: "https://example.atlassian.net",
|
|
||||||
confluenceBaseUrl: "https://example.atlassian.net",
|
|
||||||
email: "dev@example.com",
|
|
||||||
apiToken: "secret-token",
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.equal(
|
|
||||||
header,
|
|
||||||
`Basic ${Buffer.from("dev@example.com:secret-token").toString("base64")}`,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
@@ -1,351 +0,0 @@
|
|||||||
import test from "node:test";
|
|
||||||
import assert from "node:assert/strict";
|
|
||||||
|
|
||||||
import { createTempWorkspace, jsonResponse, runCli } from "./helpers.js";
|
|
||||||
|
|
||||||
const baseEnv = {
|
|
||||||
ATLASSIAN_BASE_URL: "https://example.atlassian.net",
|
|
||||||
ATLASSIAN_EMAIL: "dev@example.com",
|
|
||||||
ATLASSIAN_API_TOKEN: "secret-token",
|
|
||||||
};
|
|
||||||
|
|
||||||
test("conf-search uses CQL search and normalizes page results", async () => {
|
|
||||||
const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
|
|
||||||
const fetchImpl: typeof fetch = async (input, init) => {
|
|
||||||
calls.push({ url: typeof input === "string" ? input : input.toString(), init });
|
|
||||||
|
|
||||||
return jsonResponse({
|
|
||||||
results: [
|
|
||||||
{
|
|
||||||
content: {
|
|
||||||
id: "123",
|
|
||||||
type: "page",
|
|
||||||
title: "Runbook",
|
|
||||||
_links: { webui: "/spaces/OPS/pages/123/Runbook" },
|
|
||||||
},
|
|
||||||
excerpt: "Operational runbook",
|
|
||||||
},
|
|
||||||
],
|
|
||||||
start: 5,
|
|
||||||
limit: 1,
|
|
||||||
size: 1,
|
|
||||||
totalSize: 7,
|
|
||||||
});
|
|
||||||
};
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["conf-search", "--query", "title ~ \"Runbook\"", "--max-results", "1", "--start-at", "5"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.equal(calls.length, 1);
|
|
||||||
assert.equal(
|
|
||||||
calls[0]?.url,
|
|
||||||
"https://example.atlassian.net/wiki/rest/api/search?cql=title+%7E+%22Runbook%22&limit=1&start=5",
|
|
||||||
);
|
|
||||||
assert.equal(calls[0]?.init?.method, "GET");
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: [
|
|
||||||
{
|
|
||||||
id: "123",
|
|
||||||
title: "Runbook",
|
|
||||||
type: "page",
|
|
||||||
excerpt: "Operational runbook",
|
|
||||||
url: "https://example.atlassian.net/spaces/OPS/pages/123/Runbook",
|
|
||||||
},
|
|
||||||
],
|
|
||||||
startAt: 5,
|
|
||||||
maxResults: 1,
|
|
||||||
total: 7,
|
|
||||||
},
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("conf-get returns normalized page details plus raw payload", async () => {
|
|
||||||
const rawPage = {
|
|
||||||
id: "123",
|
|
||||||
status: "current",
|
|
||||||
title: "Runbook",
|
|
||||||
spaceId: "OPS",
|
|
||||||
version: { number: 4 },
|
|
||||||
body: {
|
|
||||||
storage: {
|
|
||||||
value: "<p>Runbook</p>",
|
|
||||||
representation: "storage",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
_links: {
|
|
||||||
webui: "/spaces/OPS/pages/123/Runbook",
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["conf-get", "--page", "123"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl: async () => jsonResponse(rawPage),
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
page: {
|
|
||||||
id: "123",
|
|
||||||
title: "Runbook",
|
|
||||||
type: "page",
|
|
||||||
status: "current",
|
|
||||||
spaceId: "OPS",
|
|
||||||
version: 4,
|
|
||||||
body: "<p>Runbook</p>",
|
|
||||||
url: "https://example.atlassian.net/spaces/OPS/pages/123/Runbook",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw: rawPage,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("conf-children returns normalized direct children with pagination", async () => {
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["conf-children", "--page", "123", "--max-results", "2", "--start-at", "1"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl: async (input) => {
|
|
||||||
const url = typeof input === "string" ? input : input.toString();
|
|
||||||
assert.equal(
|
|
||||||
url,
|
|
||||||
"https://example.atlassian.net/wiki/api/v2/pages/123/direct-children?limit=2&cursor=1",
|
|
||||||
);
|
|
||||||
|
|
||||||
return jsonResponse({
|
|
||||||
results: [
|
|
||||||
{
|
|
||||||
id: "124",
|
|
||||||
title: "Child page",
|
|
||||||
type: "page",
|
|
||||||
status: "current",
|
|
||||||
spaceId: "OPS",
|
|
||||||
_links: { webui: "/spaces/OPS/pages/124/Child+page" },
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
pages: [
|
|
||||||
{
|
|
||||||
id: "124",
|
|
||||||
title: "Child page",
|
|
||||||
type: "page",
|
|
||||||
status: "current",
|
|
||||||
spaceId: "OPS",
|
|
||||||
url: "https://example.atlassian.net/spaces/OPS/pages/124/Child+page",
|
|
||||||
},
|
|
||||||
],
|
|
||||||
nextCursor: null,
|
|
||||||
},
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("conf-create dry-run emits a storage-format request body", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("page.storage.html", "<p>Runbook</p>");
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: [
|
|
||||||
"conf-create",
|
|
||||||
"--title",
|
|
||||||
"Runbook",
|
|
||||||
"--body-file",
|
|
||||||
"page.storage.html",
|
|
||||||
"--dry-run",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: {
|
|
||||||
...baseEnv,
|
|
||||||
ATLASSIAN_DEFAULT_SPACE: "OPS",
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "POST",
|
|
||||||
url: "https://example.atlassian.net/wiki/api/v2/pages",
|
|
||||||
body: {
|
|
||||||
spaceId: "OPS",
|
|
||||||
title: "Runbook",
|
|
||||||
status: "current",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: "<p>Runbook</p>",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
test("conf-update fetches the current page version and increments it for dry-run", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("page.storage.html", "<p>Updated</p>");
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: [
|
|
||||||
"conf-update",
|
|
||||||
"--page",
|
|
||||||
"123",
|
|
||||||
"--title",
|
|
||||||
"Runbook",
|
|
||||||
"--body-file",
|
|
||||||
"page.storage.html",
|
|
||||||
"--dry-run",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl: async (input, init) => {
|
|
||||||
calls.push({ url: typeof input === "string" ? input : input.toString(), init });
|
|
||||||
return jsonResponse({
|
|
||||||
id: "123",
|
|
||||||
spaceId: "OPS",
|
|
||||||
status: "current",
|
|
||||||
title: "Runbook",
|
|
||||||
version: { number: 4 },
|
|
||||||
body: {
|
|
||||||
storage: {
|
|
||||||
value: "<p>Old</p>",
|
|
||||||
representation: "storage",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.equal(calls.length, 1);
|
|
||||||
assert.equal(
|
|
||||||
calls[0]?.url,
|
|
||||||
"https://example.atlassian.net/wiki/api/v2/pages/123?body-format=storage",
|
|
||||||
);
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "PUT",
|
|
||||||
url: "https://example.atlassian.net/wiki/api/v2/pages/123",
|
|
||||||
body: {
|
|
||||||
id: "123",
|
|
||||||
status: "current",
|
|
||||||
title: "Runbook",
|
|
||||||
spaceId: "OPS",
|
|
||||||
version: {
|
|
||||||
number: 5,
|
|
||||||
},
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: "<p>Updated</p>",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
test("conf-comment dry-run targets footer comments", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("comment.storage.html", "<p>Looks good</p>");
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["conf-comment", "--page", "123", "--body-file", "comment.storage.html", "--dry-run"],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "POST",
|
|
||||||
url: "https://example.atlassian.net/wiki/api/v2/footer-comments",
|
|
||||||
body: {
|
|
||||||
pageId: "123",
|
|
||||||
body: {
|
|
||||||
representation: "storage",
|
|
||||||
value: "<p>Looks good</p>",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
test("conf-update surfaces version conflicts clearly", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("page.storage.html", "<p>Updated</p>");
|
|
||||||
|
|
||||||
await assert.rejects(
|
|
||||||
runCli({
|
|
||||||
args: [
|
|
||||||
"conf-update",
|
|
||||||
"--page",
|
|
||||||
"123",
|
|
||||||
"--title",
|
|
||||||
"Runbook",
|
|
||||||
"--body-file",
|
|
||||||
"page.storage.html",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl: async (input, init) => {
|
|
||||||
const url = typeof input === "string" ? input : input.toString();
|
|
||||||
|
|
||||||
if (url.endsWith("?body-format=storage")) {
|
|
||||||
return jsonResponse({
|
|
||||||
id: "123",
|
|
||||||
spaceId: "OPS",
|
|
||||||
status: "current",
|
|
||||||
title: "Runbook",
|
|
||||||
version: { number: 4 },
|
|
||||||
body: {
|
|
||||||
storage: {
|
|
||||||
value: "<p>Old</p>",
|
|
||||||
representation: "storage",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
assert.equal(init?.method, "PUT");
|
|
||||||
return new Response(JSON.stringify({ message: "Conflict" }), {
|
|
||||||
status: 409,
|
|
||||||
statusText: "Conflict",
|
|
||||||
headers: { "content-type": "application/json" },
|
|
||||||
});
|
|
||||||
},
|
|
||||||
}),
|
|
||||||
/Confluence update conflict: page 123 was updated by someone else/,
|
|
||||||
);
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
@@ -1,72 +0,0 @@
|
|||||||
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
|
||||||
import { tmpdir } from "node:os";
|
|
||||||
import path from "node:path";
|
|
||||||
|
|
||||||
import { buildProgram } from "../src/cli.js";
|
|
||||||
|
|
||||||
type RunCliOptions = {
|
|
||||||
args: string[];
|
|
||||||
cwd?: string;
|
|
||||||
env?: NodeJS.ProcessEnv;
|
|
||||||
fetchImpl?: typeof fetch;
|
|
||||||
};
|
|
||||||
|
|
||||||
class MemoryWriter {
|
|
||||||
private readonly chunks: string[] = [];
|
|
||||||
|
|
||||||
write(chunk: string | Uint8Array) {
|
|
||||||
this.chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
|
|
||||||
return true;
|
|
||||||
}
|
|
||||||
|
|
||||||
toString() {
|
|
||||||
return this.chunks.join("");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function runCli(options: RunCliOptions) {
|
|
||||||
const stdout = new MemoryWriter();
|
|
||||||
const stderr = new MemoryWriter();
|
|
||||||
const program = buildProgram({
|
|
||||||
cwd: options.cwd,
|
|
||||||
env: options.env,
|
|
||||||
fetchImpl: options.fetchImpl,
|
|
||||||
stdout,
|
|
||||||
stderr,
|
|
||||||
});
|
|
||||||
|
|
||||||
await program.parseAsync(options.args, { from: "user" });
|
|
||||||
|
|
||||||
return {
|
|
||||||
stdout: stdout.toString(),
|
|
||||||
stderr: stderr.toString(),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function createTempWorkspace() {
|
|
||||||
const cwd = mkdtempSync(path.join(tmpdir(), "atlassian-skill-"));
|
|
||||||
|
|
||||||
return {
|
|
||||||
cwd,
|
|
||||||
cleanup() {
|
|
||||||
rmSync(cwd, { recursive: true, force: true });
|
|
||||||
},
|
|
||||||
write(relativePath: string, contents: string) {
|
|
||||||
const target = path.join(cwd, relativePath);
|
|
||||||
mkdirSync(path.dirname(target), { recursive: true });
|
|
||||||
writeFileSync(target, contents, "utf8");
|
|
||||||
return target;
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export function jsonResponse(payload: unknown, init?: ResponseInit) {
|
|
||||||
return new Response(JSON.stringify(payload), {
|
|
||||||
status: init?.status ?? 200,
|
|
||||||
statusText: init?.statusText,
|
|
||||||
headers: {
|
|
||||||
"content-type": "application/json",
|
|
||||||
...(init?.headers ?? {}),
|
|
||||||
},
|
|
||||||
});
|
|
||||||
}
|
|
||||||
@@ -1,131 +0,0 @@
|
|||||||
import test from "node:test";
|
|
||||||
import assert from "node:assert/strict";
|
|
||||||
|
|
||||||
import { sendJsonRequest } from "../src/http.js";
|
|
||||||
import { runCli } from "./helpers.js";
|
|
||||||
|
|
||||||
const baseConfig = {
|
|
||||||
baseUrl: "https://example.atlassian.net",
|
|
||||||
jiraBaseUrl: "https://example.atlassian.net",
|
|
||||||
confluenceBaseUrl: "https://example.atlassian.net",
|
|
||||||
email: "dev@example.com",
|
|
||||||
apiToken: "secret-token",
|
|
||||||
};
|
|
||||||
|
|
||||||
const baseEnv = {
|
|
||||||
ATLASSIAN_BASE_URL: "https://example.atlassian.net",
|
|
||||||
ATLASSIAN_EMAIL: "dev@example.com",
|
|
||||||
ATLASSIAN_API_TOKEN: "secret-token",
|
|
||||||
};
|
|
||||||
|
|
||||||
test("health probes Jira and Confluence independently", async () => {
|
|
||||||
const calls: string[] = [];
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["health"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl: async (input) => {
|
|
||||||
const url = typeof input === "string" ? input : input.toString();
|
|
||||||
calls.push(url);
|
|
||||||
|
|
||||||
if (url.endsWith("/rest/api/3/myself")) {
|
|
||||||
return new Response(JSON.stringify({ accountId: "1" }), {
|
|
||||||
status: 200,
|
|
||||||
headers: { "content-type": "application/json" },
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
return new Response(JSON.stringify({ message: "Forbidden" }), {
|
|
||||||
status: 403,
|
|
||||||
statusText: "Forbidden",
|
|
||||||
headers: { "content-type": "application/json" },
|
|
||||||
});
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(calls, [
|
|
||||||
"https://example.atlassian.net/rest/api/3/myself",
|
|
||||||
"https://example.atlassian.net/wiki/api/v2/spaces?limit=1",
|
|
||||||
]);
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: false,
|
|
||||||
data: {
|
|
||||||
baseUrl: "https://example.atlassian.net",
|
|
||||||
jiraBaseUrl: "https://example.atlassian.net",
|
|
||||||
confluenceBaseUrl: "https://example.atlassian.net",
|
|
||||||
products: {
|
|
||||||
jira: {
|
|
||||||
ok: true,
|
|
||||||
status: 200,
|
|
||||||
},
|
|
||||||
confluence: {
|
|
||||||
ok: false,
|
|
||||||
status: 403,
|
|
||||||
message:
|
|
||||||
"Confluence health check failed: 403 Forbidden - verify product permissions for this account",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("sendJsonRequest maps 401, 403, 404, and 429 to actionable messages", async () => {
|
|
||||||
const cases = [
|
|
||||||
{
|
|
||||||
status: 401,
|
|
||||||
statusText: "Unauthorized",
|
|
||||||
expected: /401 Unauthorized - check ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN/,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
status: 403,
|
|
||||||
statusText: "Forbidden",
|
|
||||||
expected: /403 Forbidden - verify product permissions for this account/,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
status: 404,
|
|
||||||
statusText: "Not Found",
|
|
||||||
expected: /404 Not Found - verify the resource identifier or API path/,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
status: 429,
|
|
||||||
statusText: "Too Many Requests",
|
|
||||||
expected: /429 Too Many Requests - retry later or reduce request rate/,
|
|
||||||
},
|
|
||||||
] as const;
|
|
||||||
|
|
||||||
for (const entry of cases) {
|
|
||||||
await assert.rejects(
|
|
||||||
sendJsonRequest({
|
|
||||||
config: baseConfig,
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue/ENG-1",
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
fetchImpl: async () =>
|
|
||||||
new Response(JSON.stringify({ message: entry.statusText }), {
|
|
||||||
status: entry.status,
|
|
||||||
statusText: entry.statusText,
|
|
||||||
headers: { "content-type": "application/json" },
|
|
||||||
}),
|
|
||||||
}),
|
|
||||||
entry.expected,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
test("sendJsonRequest reports malformed JSON responses clearly", async () => {
|
|
||||||
await assert.rejects(
|
|
||||||
sendJsonRequest({
|
|
||||||
config: baseConfig,
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue/ENG-1",
|
|
||||||
method: "GET",
|
|
||||||
errorPrefix: "Jira request failed",
|
|
||||||
fetchImpl: async () =>
|
|
||||||
new Response("{", {
|
|
||||||
status: 200,
|
|
||||||
headers: { "content-type": "application/json" },
|
|
||||||
}),
|
|
||||||
}),
|
|
||||||
/Malformed JSON response from Atlassian API/,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
@@ -1,321 +0,0 @@
|
|||||||
import test from "node:test";
|
|
||||||
import assert from "node:assert/strict";
|
|
||||||
|
|
||||||
import { markdownToAdf } from "../src/adf.js";
|
|
||||||
import { createTempWorkspace, jsonResponse, runCli } from "./helpers.js";
|
|
||||||
|
|
||||||
const baseEnv = {
|
|
||||||
ATLASSIAN_BASE_URL: "https://example.atlassian.net",
|
|
||||||
ATLASSIAN_EMAIL: "dev@example.com",
|
|
||||||
ATLASSIAN_API_TOKEN: "secret-token",
|
|
||||||
};
|
|
||||||
|
|
||||||
test("jira-search emits normalized results and uses pagination inputs", async () => {
|
|
||||||
const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
|
|
||||||
|
|
||||||
const fetchImpl: typeof fetch = async (input, init) => {
|
|
||||||
const url = typeof input === "string" ? input : input.toString();
|
|
||||||
calls.push({ url, init });
|
|
||||||
|
|
||||||
return jsonResponse({
|
|
||||||
startAt: 10,
|
|
||||||
maxResults: 2,
|
|
||||||
total: 25,
|
|
||||||
issues: [
|
|
||||||
{
|
|
||||||
key: "ENG-1",
|
|
||||||
fields: {
|
|
||||||
summary: "Add Jira search command",
|
|
||||||
issuetype: { name: "Story" },
|
|
||||||
status: { name: "In Progress" },
|
|
||||||
assignee: { displayName: "Ada Lovelace" },
|
|
||||||
created: "2026-03-01T00:00:00.000Z",
|
|
||||||
updated: "2026-03-02T00:00:00.000Z",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
};
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["jira-search", "--jql", "project = ENG", "--max-results", "2", "--start-at", "10"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.equal(calls.length, 1);
|
|
||||||
assert.equal(calls[0]?.url, "https://example.atlassian.net/rest/api/3/search");
|
|
||||||
assert.equal(calls[0]?.init?.method, "POST");
|
|
||||||
assert.match(String(calls[0]?.init?.headers), /Authorization/);
|
|
||||||
assert.deepEqual(JSON.parse(String(calls[0]?.init?.body)), {
|
|
||||||
jql: "project = ENG",
|
|
||||||
maxResults: 2,
|
|
||||||
startAt: 10,
|
|
||||||
fields: ["summary", "issuetype", "status", "assignee", "created", "updated"],
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issues: [
|
|
||||||
{
|
|
||||||
key: "ENG-1",
|
|
||||||
summary: "Add Jira search command",
|
|
||||||
issueType: "Story",
|
|
||||||
status: "In Progress",
|
|
||||||
assignee: "Ada Lovelace",
|
|
||||||
created: "2026-03-01T00:00:00.000Z",
|
|
||||||
updated: "2026-03-02T00:00:00.000Z",
|
|
||||||
url: "https://example.atlassian.net/browse/ENG-1",
|
|
||||||
},
|
|
||||||
],
|
|
||||||
startAt: 10,
|
|
||||||
maxResults: 2,
|
|
||||||
total: 25,
|
|
||||||
},
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("jira-get returns normalized fields plus the raw Jira payload", async () => {
|
|
||||||
const rawIssue = {
|
|
||||||
key: "ENG-42",
|
|
||||||
fields: {
|
|
||||||
summary: "Ship v1",
|
|
||||||
issuetype: { name: "Task" },
|
|
||||||
status: { name: "Done" },
|
|
||||||
assignee: { displayName: "Grace Hopper" },
|
|
||||||
created: "2026-03-03T00:00:00.000Z",
|
|
||||||
updated: "2026-03-04T00:00:00.000Z",
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
const fetchImpl: typeof fetch = async () => jsonResponse(rawIssue);
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["jira-get", "--issue", "ENG-42"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
issue: {
|
|
||||||
key: "ENG-42",
|
|
||||||
summary: "Ship v1",
|
|
||||||
issueType: "Task",
|
|
||||||
status: "Done",
|
|
||||||
assignee: "Grace Hopper",
|
|
||||||
created: "2026-03-03T00:00:00.000Z",
|
|
||||||
updated: "2026-03-04T00:00:00.000Z",
|
|
||||||
url: "https://example.atlassian.net/browse/ENG-42",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
raw: rawIssue,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("markdownToAdf converts headings, paragraphs, and bullet lists", () => {
|
|
||||||
assert.deepEqual(markdownToAdf("# Summary\n\nBuild the Jira skill.\n\n- Search\n- Comment"), {
|
|
||||||
type: "doc",
|
|
||||||
version: 1,
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "heading",
|
|
||||||
attrs: { level: 1 },
|
|
||||||
content: [{ type: "text", text: "Summary" }],
|
|
||||||
},
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [{ type: "text", text: "Build the Jira skill." }],
|
|
||||||
},
|
|
||||||
{
|
|
||||||
type: "bulletList",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [{ type: "text", text: "Search" }],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
{
|
|
||||||
type: "listItem",
|
|
||||||
content: [
|
|
||||||
{
|
|
||||||
type: "paragraph",
|
|
||||||
content: [{ type: "text", text: "Comment" }],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("jira-create dry-run emits an ADF request body without calling Jira", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("description.md", "# New story\n\n- one\n- two");
|
|
||||||
let called = false;
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: [
|
|
||||||
"jira-create",
|
|
||||||
"--type",
|
|
||||||
"Story",
|
|
||||||
"--summary",
|
|
||||||
"Create the Atlassian skill",
|
|
||||||
"--description-file",
|
|
||||||
"description.md",
|
|
||||||
"--dry-run",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: {
|
|
||||||
...baseEnv,
|
|
||||||
ATLASSIAN_DEFAULT_PROJECT: "ENG",
|
|
||||||
},
|
|
||||||
fetchImpl: async () => {
|
|
||||||
called = true;
|
|
||||||
return jsonResponse({});
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.equal(called, false);
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "POST",
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue",
|
|
||||||
body: {
|
|
||||||
fields: {
|
|
||||||
project: { key: "ENG" },
|
|
||||||
issuetype: { name: "Story" },
|
|
||||||
summary: "Create the Atlassian skill",
|
|
||||||
description: markdownToAdf("# New story\n\n- one\n- two"),
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
test("jira-update, jira-comment, and jira-transition dry-runs build the expected Jira requests", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("issue.md", "Updated description");
|
|
||||||
workspace.write("comment.md", "Comment body");
|
|
||||||
|
|
||||||
const update = await runCli({
|
|
||||||
args: [
|
|
||||||
"jira-update",
|
|
||||||
"--issue",
|
|
||||||
"ENG-9",
|
|
||||||
"--summary",
|
|
||||||
"Updated summary",
|
|
||||||
"--description-file",
|
|
||||||
"issue.md",
|
|
||||||
"--dry-run",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
});
|
|
||||||
|
|
||||||
const comment = await runCli({
|
|
||||||
args: ["jira-comment", "--issue", "ENG-9", "--body-file", "comment.md", "--dry-run"],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
});
|
|
||||||
|
|
||||||
const transition = await runCli({
|
|
||||||
args: ["jira-transition", "--issue", "ENG-9", "--transition", "31", "--dry-run"],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(update.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "PUT",
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue/ENG-9",
|
|
||||||
body: {
|
|
||||||
fields: {
|
|
||||||
summary: "Updated summary",
|
|
||||||
description: markdownToAdf("Updated description"),
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(comment.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "POST",
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue/ENG-9/comment",
|
|
||||||
body: {
|
|
||||||
body: markdownToAdf("Comment body"),
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(transition.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "POST",
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue/ENG-9/transitions",
|
|
||||||
body: {
|
|
||||||
transition: {
|
|
||||||
id: "31",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
test("jira-transitions returns normalized transition options", async () => {
|
|
||||||
const fetchImpl: typeof fetch = async () =>
|
|
||||||
jsonResponse({
|
|
||||||
transitions: [
|
|
||||||
{
|
|
||||||
id: "21",
|
|
||||||
name: "Start Progress",
|
|
||||||
to: { name: "In Progress" },
|
|
||||||
hasScreen: false,
|
|
||||||
},
|
|
||||||
],
|
|
||||||
});
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["jira-transitions", "--issue", "ENG-9"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
transitions: [
|
|
||||||
{
|
|
||||||
id: "21",
|
|
||||||
name: "Start Progress",
|
|
||||||
toStatus: "In Progress",
|
|
||||||
hasScreen: false,
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,129 +0,0 @@
|
|||||||
import test from "node:test";
|
|
||||||
import assert from "node:assert/strict";
|
|
||||||
|
|
||||||
import { createTempWorkspace, jsonResponse, runCli } from "./helpers.js";
|
|
||||||
|
|
||||||
const baseEnv = {
|
|
||||||
ATLASSIAN_BASE_URL: "https://example.atlassian.net",
|
|
||||||
ATLASSIAN_EMAIL: "dev@example.com",
|
|
||||||
ATLASSIAN_API_TOKEN: "secret-token",
|
|
||||||
};
|
|
||||||
|
|
||||||
test("raw rejects DELETE requests", async () => {
|
|
||||||
await assert.rejects(
|
|
||||||
runCli({
|
|
||||||
args: ["raw", "--product", "jira", "--method", "DELETE", "--path", "/rest/api/3/issue/ENG-1"],
|
|
||||||
env: baseEnv,
|
|
||||||
}),
|
|
||||||
/raw only allows GET, POST, and PUT/,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
test("raw rejects unsupported Jira and Confluence prefixes", async () => {
|
|
||||||
await assert.rejects(
|
|
||||||
runCli({
|
|
||||||
args: ["raw", "--product", "jira", "--method", "GET", "--path", "/wiki/api/v2/pages"],
|
|
||||||
env: baseEnv,
|
|
||||||
}),
|
|
||||||
/raw path is not allowed for jira/,
|
|
||||||
);
|
|
||||||
|
|
||||||
await assert.rejects(
|
|
||||||
runCli({
|
|
||||||
args: ["raw", "--product", "confluence", "--method", "GET", "--path", "/rest/api/3/issue/ENG-1"],
|
|
||||||
env: baseEnv,
|
|
||||||
}),
|
|
||||||
/raw path is not allowed for confluence/,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
test("raw GET executes against the validated Jira endpoint", async () => {
|
|
||||||
let call: { url: string; init: RequestInit | undefined } | undefined;
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: ["raw", "--product", "jira", "--method", "GET", "--path", "/rest/api/3/issue/ENG-1"],
|
|
||||||
env: baseEnv,
|
|
||||||
fetchImpl: async (input, init) => {
|
|
||||||
call = { url: typeof input === "string" ? input : input.toString(), init };
|
|
||||||
return jsonResponse({ id: "10001", key: "ENG-1" });
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(call, {
|
|
||||||
url: "https://example.atlassian.net/rest/api/3/issue/ENG-1",
|
|
||||||
init: {
|
|
||||||
method: "GET",
|
|
||||||
headers: [
|
|
||||||
["Accept", "application/json"],
|
|
||||||
["Authorization", `Basic ${Buffer.from("dev@example.com:secret-token").toString("base64")}`],
|
|
||||||
],
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
data: {
|
|
||||||
id: "10001",
|
|
||||||
key: "ENG-1",
|
|
||||||
},
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test("raw POST dry-run reads only workspace-scoped body files", async () => {
|
|
||||||
const workspace = createTempWorkspace();
|
|
||||||
|
|
||||||
try {
|
|
||||||
workspace.write("payload.json", "{\"title\":\"Runbook\"}");
|
|
||||||
|
|
||||||
const result = await runCli({
|
|
||||||
args: [
|
|
||||||
"raw",
|
|
||||||
"--product",
|
|
||||||
"confluence",
|
|
||||||
"--method",
|
|
||||||
"POST",
|
|
||||||
"--path",
|
|
||||||
"/wiki/api/v2/pages",
|
|
||||||
"--body-file",
|
|
||||||
"payload.json",
|
|
||||||
"--dry-run",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
});
|
|
||||||
|
|
||||||
assert.deepEqual(JSON.parse(result.stdout), {
|
|
||||||
ok: true,
|
|
||||||
dryRun: true,
|
|
||||||
data: {
|
|
||||||
method: "POST",
|
|
||||||
url: "https://example.atlassian.net/wiki/api/v2/pages",
|
|
||||||
body: {
|
|
||||||
title: "Runbook",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
});
|
|
||||||
|
|
||||||
await assert.rejects(
|
|
||||||
runCli({
|
|
||||||
args: [
|
|
||||||
"raw",
|
|
||||||
"--product",
|
|
||||||
"confluence",
|
|
||||||
"--method",
|
|
||||||
"POST",
|
|
||||||
"--path",
|
|
||||||
"/wiki/api/v2/pages",
|
|
||||||
"--body-file",
|
|
||||||
"../outside.json",
|
|
||||||
"--dry-run",
|
|
||||||
],
|
|
||||||
cwd: workspace.cwd,
|
|
||||||
env: baseEnv,
|
|
||||||
}),
|
|
||||||
/--body-file must stay within the active workspace/,
|
|
||||||
);
|
|
||||||
} finally {
|
|
||||||
workspace.cleanup();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
{
|
|
||||||
"compilerOptions": {
|
|
||||||
"target": "ES2022",
|
|
||||||
"module": "NodeNext",
|
|
||||||
"moduleResolution": "NodeNext",
|
|
||||||
"esModuleInterop": true,
|
|
||||||
"forceConsistentCasingInFileNames": true,
|
|
||||||
"strict": true,
|
|
||||||
"skipLibCheck": true,
|
|
||||||
"resolveJsonModule": true,
|
|
||||||
"types": ["node"],
|
|
||||||
"outDir": "dist"
|
|
||||||
},
|
|
||||||
"include": ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.ts"]
|
|
||||||
}
|
|
||||||
@@ -1,15 +1,15 @@
|
|||||||
---
|
---
|
||||||
name: create-plan
|
name: create-plan
|
||||||
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
|
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Create Plan (Claude Code)
|
# Create Plan (Claude Code)
|
||||||
|
|
||||||
Create and maintain a local plan folder under `ai_plan/` at project root.
|
Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use).
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
## Prerequisite Check (MANDATORY)
|
||||||
|
|
||||||
This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation.
|
This skill depends on Superpowers planning skills. Before proceeding, verify required dependencies exist.
|
||||||
|
|
||||||
Required:
|
Required:
|
||||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||||
@@ -23,480 +23,37 @@ If any dependency is missing, stop immediately and return:
|
|||||||
## Process
|
## Process
|
||||||
|
|
||||||
### Phase 1: Analyze
|
### Phase 1: Analyze
|
||||||
- Explore the codebase with exploration agents.
|
- Explore the codebase and existing patterns.
|
||||||
- Understand existing patterns and context.
|
|
||||||
|
|
||||||
### Phase 2: Gather Requirements
|
### Phase 2: Gather Requirements
|
||||||
- Ask questions ONE AT A TIME until user says ready.
|
- Ask questions one at a time until user says ready.
|
||||||
- Cover scope, constraints, success criteria, dependencies.
|
- Confirm scope, constraints, success criteria, dependencies.
|
||||||
- Summarize before proceeding.
|
|
||||||
|
|
||||||
### Phase 3: Configure Reviewer
|
### Phase 3: Design
|
||||||
|
- Invoke `superpowers:brainstorming`.
|
||||||
|
- Propose 2-3 approaches and recommend one.
|
||||||
|
|
||||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
### Phase 4: Plan
|
||||||
|
- Invoke `superpowers:writing-plans`.
|
||||||
|
- Break into milestones and bite-sized stories.
|
||||||
|
|
||||||
1. **Which CLI should review the plan?**
|
### Phase 5: Generate Plan Files (MANDATORY)
|
||||||
- `codex` — OpenAI Codex CLI (`codex exec`)
|
|
||||||
- `claude` — Claude Code CLI (`claude -p`)
|
|
||||||
- `cursor` — Cursor Agent CLI (`cursor-agent -p`)
|
|
||||||
- `skip` — No external review, proceed directly to file generation
|
|
||||||
|
|
||||||
2. **Which model?** (only if a CLI was chosen)
|
Create `docs/plans/YYYY-MM-DD-<short-title>/` with all files below:
|
||||||
- For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
|
1. `original-plan.md` - copy of original planner-generated plan.
|
||||||
- For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
|
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||||
- For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
|
3. `milestone-plan.md` - full implementation spec (from template).
|
||||||
- Accept any model string the user provides
|
4. `story-tracker.md` - story/milestone status tracker (from template).
|
||||||
|
5. `continuation-runbook.md` - execution instructions and context (from template).
|
||||||
|
|
||||||
3. **Max review rounds for the plan?** (default: 10)
|
Use templates from this skill's `templates/` folder.
|
||||||
- If the user does not provide a value, set `MAX_ROUNDS=10`.
|
|
||||||
|
|
||||||
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
|
### Phase 6: Handoff
|
||||||
|
|
||||||
### Phase 4: Design (REQUIRED SUB-SKILL)
|
Always instruct the executing agent:
|
||||||
- Invoke `superpowers:brainstorming` explicitly.
|
> Read `docs/plans/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
|
||||||
- Present 2-3 approaches and recommend one.
|
|
||||||
- Validate design in sections.
|
|
||||||
|
|
||||||
### Phase 5: Plan (REQUIRED SUB-SKILL)
|
Do not rely on planner-private files during implementation.
|
||||||
- Invoke `superpowers:writing-plans` explicitly.
|
|
||||||
- Break into milestones and bite-sized stories (2-5 min each).
|
|
||||||
- Story IDs: `S-{milestone}{sequence}`.
|
|
||||||
|
|
||||||
### Phase 6: Iterative Plan Review
|
|
||||||
|
|
||||||
Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
|
|
||||||
|
|
||||||
**Skip this phase entirely if reviewer was set to `skip`.**
|
|
||||||
|
|
||||||
#### Step 1: Generate Session ID
|
|
||||||
|
|
||||||
```bash
|
|
||||||
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
|
||||||
```
|
|
||||||
|
|
||||||
Use for temp artifacts:
|
|
||||||
- `/tmp/plan-${REVIEW_ID}.md`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.stderr`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.status`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.sh`
|
|
||||||
|
|
||||||
Resolve the shared reviewer helper from the installed Claude Code skills directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
REVIEWER_RUNTIME=~/.claude/skills/reviewer-runtime/run-review.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Set helper success-artifact args before writing the command script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
HELPER_SUCCESS_FILE_ARGS=()
|
|
||||||
case "$REVIEWER_CLI" in
|
|
||||||
codex)
|
|
||||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
|
|
||||||
;;
|
|
||||||
cursor)
|
|
||||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 2: Write Plan to Temp File
|
|
||||||
|
|
||||||
Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
|
|
||||||
|
|
||||||
#### Review Contract (Applies to Every Round)
|
|
||||||
|
|
||||||
The reviewer response must use this structure:
|
|
||||||
|
|
||||||
```text
|
|
||||||
## Summary
|
|
||||||
...
|
|
||||||
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
- ...
|
|
||||||
### P1
|
|
||||||
- ...
|
|
||||||
### P2
|
|
||||||
- ...
|
|
||||||
### P3
|
|
||||||
- ...
|
|
||||||
|
|
||||||
## Verdict
|
|
||||||
VERDICT: APPROVED
|
|
||||||
```
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from `P0` to `P3`.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
|
|
||||||
- The calling agent should still try to fix `P3` findings when they are cheap and safe.
|
|
||||||
|
|
||||||
#### Liveness Contract (Applies While Review Is Running)
|
|
||||||
|
|
||||||
- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
|
|
||||||
- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
|
|
||||||
- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
|
|
||||||
- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
|
|
||||||
|
|
||||||
#### Step 3: Submit to Reviewer (Round 1)
|
|
||||||
|
|
||||||
Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
set -euo pipefail
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `codex`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
codex exec \
|
|
||||||
-m ${REVIEWER_MODEL} \
|
|
||||||
-s read-only \
|
|
||||||
-o /tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
"Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
|
|
||||||
```
|
|
||||||
|
|
||||||
Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `claude`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude -p \
|
|
||||||
"Review the implementation plan below. Focus on:
|
|
||||||
|
|
||||||
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
||||||
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--strict-mcp-config \
|
|
||||||
--setting-sources user
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `cursor`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent -p \
|
|
||||||
--mode=ask \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--trust \
|
|
||||||
--output-format json \
|
|
||||||
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
|
|
||||||
> /tmp/plan-review-${REVIEW_ID}.json
|
|
||||||
```
|
|
||||||
|
|
||||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
|
|
||||||
|
|
||||||
Run the command script through the shared helper when available:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x "$REVIEWER_RUNTIME" ]; then
|
|
||||||
"$REVIEWER_RUNTIME" \
|
|
||||||
--command-file /tmp/plan-review-${REVIEW_ID}.sh \
|
|
||||||
--stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
|
|
||||||
--stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
|
|
||||||
--status-file /tmp/plan-review-${REVIEW_ID}.status \
|
|
||||||
"${HELPER_SUCCESS_FILE_ARGS[@]}"
|
|
||||||
else
|
|
||||||
echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
|
|
||||||
bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
|
||||||
|
|
||||||
After the command completes:
|
|
||||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
|
|
||||||
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
|
|
||||||
- If `REVIEWER_CLI=claude`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Fallback is allowed only when the helper is missing or not executable.
|
|
||||||
|
|
||||||
#### Step 4: Read Review & Check Verdict
|
|
||||||
|
|
||||||
1. Read `/tmp/plan-review-${REVIEW_ID}.md`
|
|
||||||
2. If the review failed, produced empty output, or reached helper timeout, also read:
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.stderr`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.status`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
|
||||||
3. Present review to the user:
|
|
||||||
|
|
||||||
```
|
|
||||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
|
||||||
|
|
||||||
[Reviewer feedback]
|
|
||||||
```
|
|
||||||
|
|
||||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
|
||||||
5. Check verdict:
|
|
||||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
|
||||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
|
||||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
|
||||||
- No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
|
|
||||||
- Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
|
|
||||||
- Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
|
|
||||||
- Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
|
|
||||||
|
|
||||||
#### Step 5: Revise the Plan
|
|
||||||
|
|
||||||
Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
|
|
||||||
|
|
||||||
Summarize revisions for the user:
|
|
||||||
|
|
||||||
```
|
|
||||||
### Revisions (Round N)
|
|
||||||
- [Change and reason, one bullet per issue addressed]
|
|
||||||
```
|
|
||||||
|
|
||||||
If a revision contradicts the user's explicit requirements, skip it and note it for the user.
|
|
||||||
|
|
||||||
#### Step 6: Re-submit to Reviewer (Rounds 2-N)
|
|
||||||
|
|
||||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `codex`:**
|
|
||||||
|
|
||||||
Resume the existing session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
codex exec resume ${CODEX_SESSION_ID} \
|
|
||||||
-o /tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
|
|
||||||
```
|
|
||||||
|
|
||||||
If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `claude`:**
|
|
||||||
|
|
||||||
Fresh call with accumulated context (Claude CLI has no session resume):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude -p \
|
|
||||||
"You previously reviewed an implementation plan and requested revisions.
|
|
||||||
|
|
||||||
Previous feedback summary: [key points from last review]
|
|
||||||
|
|
||||||
I've revised the plan. Updated version is below.
|
|
||||||
|
|
||||||
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--strict-mcp-config \
|
|
||||||
--setting-sources user
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `cursor`:**
|
|
||||||
|
|
||||||
Resume the existing session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent --resume ${CURSOR_SESSION_ID} -p \
|
|
||||||
--mode=ask \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--trust \
|
|
||||||
--output-format json \
|
|
||||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
|
|
||||||
> /tmp/plan-review-${REVIEW_ID}.json
|
|
||||||
|
|
||||||
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
|
||||||
|
|
||||||
After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
|
||||||
|
|
||||||
Return to Step 4.
|
|
||||||
|
|
||||||
#### Step 7: Present Final Result
|
|
||||||
|
|
||||||
```
|
|
||||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
|
||||||
|
|
||||||
**Status:** Approved after N round(s)
|
|
||||||
[or]
|
|
||||||
**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
|
|
||||||
|
|
||||||
[Final feedback / remaining concerns]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 8: Cleanup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
rm -f /tmp/plan-${REVIEW_ID}.md \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.json \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.stderr \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.status \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.runner.out \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
|
|
||||||
|
|
||||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
|
||||||
|
|
||||||
At project root:
|
|
||||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
|
||||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
|
||||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
|
||||||
|
|
||||||
Recommended commit message:
|
|
||||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
|
||||||
|
|
||||||
### Phase 8: Generate Plan Files (MANDATORY - DO NOT SKIP)
|
|
||||||
|
|
||||||
**PLAN MODE CHECK:** If currently in plan mode:
|
|
||||||
1. Inform user that plan files cannot be written while in plan mode.
|
|
||||||
2. Instruct user to exit plan mode (approve plan or use ExitPlanMode).
|
|
||||||
3. Proceed with file generation only after exiting plan mode.
|
|
||||||
|
|
||||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
|
|
||||||
1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is.
|
|
||||||
2. `final-transcript.md` - Copy of final planning transcript for reference.
|
|
||||||
3. `milestone-plan.md` - Full specification (template-based).
|
|
||||||
4. `story-tracker.md` - Status tracking (template-based, all stories start as `pending`).
|
|
||||||
5. `continuation-runbook.md` - Resume context and execution protocol (template-based).
|
|
||||||
|
|
||||||
Use templates from this skill's `templates/` folder (or `~/.claude/skills/create-plan/templates/` when installed directly in Claude Code).
|
|
||||||
|
|
||||||
### Phase 9: Handoff Instructions
|
|
||||||
|
|
||||||
When handing off to execution, instruct:
|
|
||||||
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from `ai_plan` files only.
|
|
||||||
|
|
||||||
Private plan files under `~/.claude/plans/` are planning artifacts and must not be used as execution source of truth.
|
|
||||||
|
|
||||||
### Phase 10: Telegram Notification (MANDATORY)
|
|
||||||
|
|
||||||
Resolve the Telegram notifier helper from the installed Claude Code skills directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
TELEGRAM_NOTIFY_RUNTIME=~/.claude/skills/reviewer-runtime/notify-telegram.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
|
|
||||||
"$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
|
||||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
|
||||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
|
||||||
- If Telegram is not configured, state that no Telegram notification was sent.
|
|
||||||
|
|
||||||
## Tracker Discipline (MANDATORY)
|
|
||||||
|
|
||||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
|
||||||
|
|
||||||
Before starting any story:
|
|
||||||
1. Open `story-tracker.md`
|
|
||||||
2. Mark story `in-dev`
|
|
||||||
3. Add notes if relevant
|
|
||||||
4. Then begin implementation
|
|
||||||
|
|
||||||
After completing any story:
|
|
||||||
1. Mark story `completed`
|
|
||||||
2. Add commit hash in Notes
|
|
||||||
3. Review pending stories
|
|
||||||
4. Update Last Updated and Stories Complete counts
|
|
||||||
|
|
||||||
## Execution Rules to Include in Plan (MANDATORY)
|
## Execution Rules to Include in Plan (MANDATORY)
|
||||||
|
|
||||||
@@ -511,24 +68,14 @@ After completing any story:
|
|||||||
|
|
||||||
## Gitignore Note
|
## Gitignore Note
|
||||||
|
|
||||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
|
If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user.
|
||||||
|
|
||||||
## Verification Checklist
|
## Verification Checklist
|
||||||
|
|
||||||
- [ ] `ai_plan/` exists at project root
|
- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`)
|
||||||
- [ ] `.gitignore` includes `/ai_plan/`
|
- [ ] `original-plan.md` present
|
||||||
- [ ] `.gitignore` ignore-rule commit was created if needed
|
|
||||||
- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
|
|
||||||
- [ ] Reviewer configured or explicitly skipped
|
|
||||||
- [ ] Max review rounds confirmed (default: 10)
|
|
||||||
- [ ] Plan review completed (approved or max rounds) — or skipped
|
|
||||||
- [ ] `original-plan.md` copied from `~/.claude/plans/` plan file
|
|
||||||
- [ ] `final-transcript.md` present
|
- [ ] `final-transcript.md` present
|
||||||
- [ ] `milestone-plan.md` present
|
- [ ] `milestone-plan.md` present
|
||||||
- [ ] `story-tracker.md` created with all stories as `pending`
|
- [ ] `story-tracker.md` present
|
||||||
- [ ] `continuation-runbook.md` present
|
- [ ] `continuation-runbook.md` present
|
||||||
- [ ] Handoff explicitly says to read runbook first and execute from plan folder
|
- [ ] Handoff explicitly says to read runbook first and execute from plan folder
|
||||||
- [ ] Telegram notification attempted if configured
|
|
||||||
|
|
||||||
## Exit Triggers for Question Phase
|
|
||||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
|
||||||
|
|||||||
@@ -28,7 +28,7 @@ Do NOT reference planner-private files during implementation.
|
|||||||
|
|
||||||
## Mandatory Execution Workflow
|
## Mandatory Execution Workflow
|
||||||
|
|
||||||
Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
|
Work from this folder (`docs/plans/YYYY-MM-DD-<short-title>/` or repo-specific `docs/plan/...`) and always follow this order:
|
||||||
|
|
||||||
1. Read `continuation-runbook.md` first.
|
1. Read `continuation-runbook.md` first.
|
||||||
2. Execute stories milestone by milestone.
|
2. Execute stories milestone by milestone.
|
||||||
@@ -51,7 +51,7 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
|||||||
|
|
||||||
## Git Note
|
## Git Note
|
||||||
|
|
||||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
|
If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -93,7 +93,7 @@
|
|||||||
|
|
||||||
## Related Plan Files
|
## Related Plan Files
|
||||||
|
|
||||||
This file is part of the plan folder under `ai_plan/`:
|
This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used):
|
||||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||||
- `milestone-plan.md` - This file (full specification)
|
- `milestone-plan.md` - This file (full specification)
|
||||||
|
|||||||
@@ -1,468 +1,48 @@
|
|||||||
---
|
---
|
||||||
name: create-plan
|
name: create-plan
|
||||||
description: Use when a user asks to create or maintain a structured implementation plan in Codex, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan.
|
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Create Plan (Codex Native Superpowers)
|
# Create Plan (Codex)
|
||||||
|
|
||||||
Create and maintain a local plan workspace under `ai_plan/` at project root.
|
Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use).
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
This skill wraps the current Superpowers flow for Codex:
|
|
||||||
1. Design first with `superpowers:brainstorming`
|
|
||||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
|
||||||
3. Review the plan iteratively with a second model/provider
|
|
||||||
4. Persist a local execution package in `ai_plan/YYYY-MM-DD-<short-title>/`
|
|
||||||
|
|
||||||
**Core principle:** Codex uses native skill discovery from `~/.agents/skills/`. Do not use deprecated `superpowers-codex bootstrap` or `use-skill` CLI commands.
|
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
## Prerequisite Check (MANDATORY)
|
||||||
|
|
||||||
|
This skill depends on Superpowers planning skills. Before proceeding, verify required dependencies exist.
|
||||||
|
|
||||||
Required:
|
Required:
|
||||||
- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||||
- `superpowers:brainstorming`
|
- `brainstorming` skill
|
||||||
- `superpowers:writing-plans`
|
- `writing-plans` skill
|
||||||
|
|
||||||
Verify before proceeding:
|
If any dependency is missing, stop immediately and return:
|
||||||
|
|
||||||
```bash
|
"Missing dependency: Superpowers planning skills are required (`brainstorming`, `writing-plans`). Install from https://github.com/obra/superpowers, then retry."
|
||||||
test -L ~/.agents/skills/superpowers
|
|
||||||
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md
|
|
||||||
test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md
|
|
||||||
```
|
|
||||||
|
|
||||||
If any dependency is missing, stop and return:
|
|
||||||
|
|
||||||
`Missing dependency: native Superpowers skills are required (superpowers:brainstorming, superpowers:writing-plans). Ensure ~/.agents/skills/superpowers is configured, then retry.`
|
|
||||||
|
|
||||||
## Required Skill Invocation Rules
|
|
||||||
|
|
||||||
- Invoke relevant skills through native discovery (no CLI wrapper).
|
|
||||||
- Announce skill usage explicitly:
|
|
||||||
- `I've read the [Skill Name] skill and I'm using it to [purpose].`
|
|
||||||
- For skills with checklists, track checklist items with `update_plan` todos.
|
|
||||||
- Tool mapping for Codex:
|
|
||||||
- `TodoWrite` -> `update_plan`
|
|
||||||
- `Task` subagents -> unavailable in Codex; do the work directly and state the limitation
|
|
||||||
- `Skill` -> use native skill discovery from `~/.agents/skills/`
|
|
||||||
|
|
||||||
## Process
|
## Process
|
||||||
|
|
||||||
### Phase 1: Analyze
|
### Phase 1: Bootstrap
|
||||||
|
- Invoke Codex superpowers bootstrap and planning skills when available.
|
||||||
|
|
||||||
|
### Phase 2: Analyze
|
||||||
- Explore the codebase and existing patterns.
|
- Explore the codebase and existing patterns.
|
||||||
|
|
||||||
### Phase 2: Gather Requirements
|
### Phase 3: Gather Requirements
|
||||||
- Ask questions one at a time until user says ready.
|
- Ask questions one at a time until user says ready.
|
||||||
- Confirm scope, constraints, success criteria, dependencies.
|
- Confirm scope, constraints, success criteria, dependencies.
|
||||||
|
|
||||||
### Phase 3: Configure Reviewer
|
### Phase 4: Design
|
||||||
|
- Use brainstorming workflow.
|
||||||
|
- Propose 2-3 approaches and recommend one.
|
||||||
|
|
||||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with claude sonnet"), use those values. Otherwise, ask:
|
### Phase 5: Plan
|
||||||
|
- Use writing-plans workflow.
|
||||||
|
- Break into milestones and bite-sized stories.
|
||||||
|
|
||||||
1. **Which CLI should review the plan?**
|
### Phase 6: Generate Plan Files (MANDATORY)
|
||||||
- `codex` — OpenAI Codex CLI (`codex exec`)
|
|
||||||
- `claude` — Claude Code CLI (`claude -p`)
|
|
||||||
- `cursor` — Cursor Agent CLI (`cursor-agent -p`)
|
|
||||||
- `skip` — No external review, proceed directly to file generation
|
|
||||||
|
|
||||||
2. **Which model?** (only if a CLI was chosen)
|
Create `docs/plans/YYYY-MM-DD-<short-title>/` with all files below:
|
||||||
- For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
|
|
||||||
- For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
|
|
||||||
- For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
|
|
||||||
- Accept any model string the user provides
|
|
||||||
|
|
||||||
3. **Max review rounds for the plan?** (default: 10)
|
|
||||||
- If the user does not provide a value, set `MAX_ROUNDS=10`.
|
|
||||||
|
|
||||||
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
|
|
||||||
|
|
||||||
### Phase 4: Design (REQUIRED SUB-SKILL)
|
|
||||||
|
|
||||||
Invoke `superpowers:brainstorming`, then propose 2-3 approaches and recommend one.
|
|
||||||
|
|
||||||
### Phase 5: Plan (REQUIRED SUB-SKILL)
|
|
||||||
|
|
||||||
Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories.
|
|
||||||
|
|
||||||
### Phase 6: Iterative Plan Review
|
|
||||||
|
|
||||||
Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
|
|
||||||
|
|
||||||
**Skip this phase entirely if reviewer was set to `skip`.**
|
|
||||||
|
|
||||||
#### Step 1: Generate Session ID
|
|
||||||
|
|
||||||
```bash
|
|
||||||
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
|
||||||
```
|
|
||||||
|
|
||||||
Use for temp artifacts:
|
|
||||||
- `/tmp/plan-${REVIEW_ID}.md` - plan payload
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.md` - normalized review text presented to the user
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.json` - raw Cursor JSON (only for `cursor`)
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.stderr` - reviewer stderr
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.status` - helper heartbeat/status log
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out` - helper-managed stdout from the reviewer command process
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.sh` - reviewer command script
|
|
||||||
|
|
||||||
Resolve the shared reviewer helper from the installed Codex skills directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
REVIEWER_RUNTIME=~/.codex/skills/reviewer-runtime/run-review.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Set helper success-artifact args before writing the command script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
HELPER_SUCCESS_FILE_ARGS=()
|
|
||||||
case "$REVIEWER_CLI" in
|
|
||||||
codex)
|
|
||||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
|
|
||||||
;;
|
|
||||||
cursor)
|
|
||||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 2: Write Plan to Temp File
|
|
||||||
|
|
||||||
Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
|
|
||||||
|
|
||||||
#### Review Contract (Applies to Every Round)
|
|
||||||
|
|
||||||
The reviewer response must use this structure:
|
|
||||||
|
|
||||||
```text
|
|
||||||
## Summary
|
|
||||||
...
|
|
||||||
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
- ...
|
|
||||||
### P1
|
|
||||||
- ...
|
|
||||||
### P2
|
|
||||||
- ...
|
|
||||||
### P3
|
|
||||||
- ...
|
|
||||||
|
|
||||||
## Verdict
|
|
||||||
VERDICT: APPROVED
|
|
||||||
```
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from `P0` to `P3`.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
|
|
||||||
- The calling agent should still try to fix `P3` findings when they are cheap and safe.
|
|
||||||
|
|
||||||
#### Liveness Contract (Applies While Review Is Running)
|
|
||||||
|
|
||||||
- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
|
|
||||||
- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
|
|
||||||
- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
|
|
||||||
- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
|
|
||||||
|
|
||||||
#### Step 3: Submit to Reviewer (Round 1)
|
|
||||||
|
|
||||||
Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
set -euo pipefail
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `codex`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
codex exec \
|
|
||||||
-m ${REVIEWER_MODEL} \
|
|
||||||
-s read-only \
|
|
||||||
-o /tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
"Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
|
|
||||||
```
|
|
||||||
|
|
||||||
Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `claude`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude -p \
|
|
||||||
"Review the implementation plan below. Focus on:
|
|
||||||
|
|
||||||
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
||||||
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--strict-mcp-config \
|
|
||||||
--setting-sources user
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `cursor`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent -p \
|
|
||||||
--mode=ask \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--trust \
|
|
||||||
--output-format json \
|
|
||||||
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
|
|
||||||
> /tmp/plan-review-${REVIEW_ID}.json
|
|
||||||
```
|
|
||||||
|
|
||||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
|
|
||||||
|
|
||||||
Run the command script through the shared helper when available:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x "$REVIEWER_RUNTIME" ]; then
|
|
||||||
"$REVIEWER_RUNTIME" \
|
|
||||||
--command-file /tmp/plan-review-${REVIEW_ID}.sh \
|
|
||||||
--stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
|
|
||||||
--stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
|
|
||||||
--status-file /tmp/plan-review-${REVIEW_ID}.status \
|
|
||||||
"${HELPER_SUCCESS_FILE_ARGS[@]}"
|
|
||||||
else
|
|
||||||
echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
|
|
||||||
bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
|
||||||
|
|
||||||
After the command completes:
|
|
||||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
|
|
||||||
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
|
|
||||||
- If `REVIEWER_CLI=claude`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Fallback is allowed only when the helper is missing or not executable.
|
|
||||||
|
|
||||||
#### Step 4: Read Review & Check Verdict
|
|
||||||
|
|
||||||
1. Read `/tmp/plan-review-${REVIEW_ID}.md`
|
|
||||||
2. If the review failed, produced empty output, or reached helper timeout, also read:
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.stderr`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.status`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
|
||||||
3. Present review to the user:
|
|
||||||
|
|
||||||
```
|
|
||||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
|
||||||
|
|
||||||
[Reviewer feedback]
|
|
||||||
```
|
|
||||||
|
|
||||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
|
||||||
5. Check verdict:
|
|
||||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
|
||||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
|
||||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
|
||||||
- No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
|
|
||||||
- Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
|
|
||||||
- Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
|
|
||||||
- Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
|
|
||||||
|
|
||||||
#### Step 5: Revise the Plan
|
|
||||||
|
|
||||||
Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
|
|
||||||
|
|
||||||
Summarize revisions for the user:
|
|
||||||
|
|
||||||
```
|
|
||||||
### Revisions (Round N)
|
|
||||||
- [Change and reason, one bullet per issue addressed]
|
|
||||||
```
|
|
||||||
|
|
||||||
If a revision contradicts the user's explicit requirements, skip it and note it for the user.
|
|
||||||
|
|
||||||
#### Step 6: Re-submit to Reviewer (Rounds 2-N)
|
|
||||||
|
|
||||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `codex`:**
|
|
||||||
|
|
||||||
Resume the existing session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
codex exec resume ${CODEX_SESSION_ID} \
|
|
||||||
-o /tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
|
|
||||||
```
|
|
||||||
|
|
||||||
If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `claude`:**
|
|
||||||
|
|
||||||
Fresh call with accumulated context (Claude CLI has no session resume):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude -p \
|
|
||||||
"You previously reviewed an implementation plan and requested revisions.
|
|
||||||
|
|
||||||
Previous feedback summary: [key points from last review]
|
|
||||||
|
|
||||||
I've revised the plan. Updated version is below.
|
|
||||||
|
|
||||||
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--strict-mcp-config \
|
|
||||||
--setting-sources user
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `cursor`:**
|
|
||||||
|
|
||||||
Resume the existing session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent --resume ${CURSOR_SESSION_ID} -p \
|
|
||||||
--mode=ask \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--trust \
|
|
||||||
--output-format json \
|
|
||||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
|
|
||||||
> /tmp/plan-review-${REVIEW_ID}.json
|
|
||||||
|
|
||||||
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
|
||||||
|
|
||||||
After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
|
||||||
|
|
||||||
Return to Step 4.
|
|
||||||
|
|
||||||
#### Step 7: Present Final Result
|
|
||||||
|
|
||||||
```
|
|
||||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
|
||||||
|
|
||||||
**Status:** Approved after N round(s)
|
|
||||||
[or]
|
|
||||||
**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
|
|
||||||
|
|
||||||
[Final feedback / remaining concerns]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 8: Cleanup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
rm -f /tmp/plan-${REVIEW_ID}.md \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.json \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.stderr \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.status \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.runner.out \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
|
|
||||||
|
|
||||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
|
||||||
|
|
||||||
At project root:
|
|
||||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
|
||||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
|
||||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
|
||||||
|
|
||||||
Recommended commit message:
|
|
||||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
|
||||||
|
|
||||||
### Phase 8: Generate Plan Files (MANDATORY)
|
|
||||||
|
|
||||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
|
||||||
1. `original-plan.md` - copy of original planner-generated plan.
|
1. `original-plan.md` - copy of original planner-generated plan.
|
||||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||||
3. `milestone-plan.md` - full implementation spec (from template).
|
3. `milestone-plan.md` - full implementation spec (from template).
|
||||||
@@ -471,50 +51,13 @@ Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
|||||||
|
|
||||||
Use templates from this skill's `templates/` folder.
|
Use templates from this skill's `templates/` folder.
|
||||||
|
|
||||||
### Phase 9: Handoff
|
### Phase 7: Handoff
|
||||||
|
|
||||||
Always instruct the executing agent:
|
Always instruct the executing agent:
|
||||||
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
|
> Read `docs/plans/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
|
||||||
|
|
||||||
Do not rely on planner-private files during implementation.
|
Do not rely on planner-private files during implementation.
|
||||||
|
|
||||||
### Phase 10: Telegram Notification (MANDATORY)
|
|
||||||
|
|
||||||
Resolve the Telegram notifier helper from the installed Codex skills directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
TELEGRAM_NOTIFY_RUNTIME=~/.codex/skills/reviewer-runtime/notify-telegram.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
|
|
||||||
"$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
|
||||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
|
||||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
|
||||||
- If Telegram is not configured, state that no Telegram notification was sent.
|
|
||||||
|
|
||||||
## Quick Reference
|
|
||||||
|
|
||||||
| Phase | Action | Required Output |
|
|
||||||
|---|---|---|
|
|
||||||
| 1 | Analyze codebase/context | Constraints and known patterns |
|
|
||||||
| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria |
|
|
||||||
| 3 | Configure reviewer CLI and model | `REVIEWER_CLI`, `REVIEWER_MODEL`, `MAX_ROUNDS` (or `skip`) |
|
|
||||||
| 4 | Invoke `superpowers:brainstorming` | Chosen design approach |
|
|
||||||
| 5 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories |
|
|
||||||
| 6 | Iterative plan review (max `MAX_ROUNDS` rounds) | Reviewer approval or max-rounds warning |
|
|
||||||
| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
|
|
||||||
| 8 | Build plan package from templates | Full plan folder with required files |
|
|
||||||
| 9 | Handoff with runbook-first instruction | Resumable execution context |
|
|
||||||
| 10 | Send Telegram notification | User notified or notification status reported |
|
|
||||||
|
|
||||||
## Execution Rules to Include in Plan (MANDATORY)
|
## Execution Rules to Include in Plan (MANDATORY)
|
||||||
|
|
||||||
- Run lint/typecheck/tests after each milestone.
|
- Run lint/typecheck/tests after each milestone.
|
||||||
@@ -528,52 +71,14 @@ Rules:
|
|||||||
|
|
||||||
## Gitignore Note
|
## Gitignore Note
|
||||||
|
|
||||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
|
If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user.
|
||||||
|
|
||||||
## Common Mistakes
|
|
||||||
|
|
||||||
- Using deprecated commands like `superpowers-codex bootstrap` or `superpowers-codex use-skill`.
|
|
||||||
- Jumping to implementation planning without running `superpowers:brainstorming` first.
|
|
||||||
- Asking multiple requirement questions in one message.
|
|
||||||
- Forgetting to create/update `.gitignore` for `/ai_plan/`.
|
|
||||||
- Omitting one or more required files in the plan package.
|
|
||||||
- Handoff without explicit "read runbook first" direction.
|
|
||||||
- Skipping the reviewer phase without explicit user opt-out.
|
|
||||||
- Not capturing the Codex session ID for resume in subsequent review rounds.
|
|
||||||
- Using any notification path other than Telegram.
|
|
||||||
|
|
||||||
## Rationalizations and Counters
|
|
||||||
|
|
||||||
| Rationalization | Counter |
|
|
||||||
|---|---|
|
|
||||||
| "Bootstrap CLI is faster" | Deprecated for Codex; native discovery is the supported path. |
|
|
||||||
| "I can skip brainstorming for small tasks" | Creative/planning work still requires design validation first. |
|
|
||||||
| "I don't need `update_plan` for checklist skills" | Checklist tracking is mandatory for execution reliability. |
|
|
||||||
| "I can keep plan files outside `ai_plan/`" | This skill standardizes local resumable planning under `ai_plan/`. |
|
|
||||||
| "The reviewer approved, I can skip my own validation" | Reviewer feedback supplements but does not replace your own verification. |
|
|
||||||
|
|
||||||
## Red Flags - Stop and Correct
|
|
||||||
|
|
||||||
- You are about to run any `superpowers-codex` command.
|
|
||||||
- You started writing milestones before design validation.
|
|
||||||
- You did not announce which skill you invoked and why.
|
|
||||||
- You are marking planning complete without all required files.
|
|
||||||
- Handoff does not explicitly point to `continuation-runbook.md`.
|
|
||||||
- You are applying a reviewer suggestion that contradicts user requirements.
|
|
||||||
|
|
||||||
## Verification Checklist
|
## Verification Checklist
|
||||||
|
|
||||||
- [ ] `ai_plan/` exists at project root
|
- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`)
|
||||||
- [ ] `.gitignore` includes `/ai_plan/`
|
|
||||||
- [ ] `.gitignore` ignore-rule commit was created if needed
|
|
||||||
- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
|
|
||||||
- [ ] Reviewer configured or explicitly skipped
|
|
||||||
- [ ] Max review rounds confirmed (default: 10)
|
|
||||||
- [ ] Plan review completed (approved or max rounds) — or skipped
|
|
||||||
- [ ] `original-plan.md` present
|
- [ ] `original-plan.md` present
|
||||||
- [ ] `final-transcript.md` present
|
- [ ] `final-transcript.md` present
|
||||||
- [ ] `milestone-plan.md` present
|
- [ ] `milestone-plan.md` present
|
||||||
- [ ] `story-tracker.md` present
|
- [ ] `story-tracker.md` present
|
||||||
- [ ] `continuation-runbook.md` present
|
- [ ] `continuation-runbook.md` present
|
||||||
- [ ] Handoff explicitly says to read runbook first and execute from plan folder
|
- [ ] Handoff explicitly says to read runbook first and execute from plan folder
|
||||||
- [ ] Telegram notification attempted if configured
|
|
||||||
|
|||||||
@@ -14,13 +14,6 @@ Upon resumption, these files in this folder are the ONLY source of truth:
|
|||||||
|
|
||||||
Do NOT reference planner-private files during implementation.
|
Do NOT reference planner-private files during implementation.
|
||||||
|
|
||||||
## Skill Workflow Guardrails
|
|
||||||
|
|
||||||
- Invoke relevant skills before action using native skill discovery.
|
|
||||||
- Announce which skill is being used and why.
|
|
||||||
- If a checklist-driven skill applies, track checklist execution explicitly.
|
|
||||||
- Do not use deprecated CLI wrappers for skill invocation.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Resume Instructions
|
## Quick Resume Instructions
|
||||||
@@ -35,7 +28,7 @@ Do NOT reference planner-private files during implementation.
|
|||||||
|
|
||||||
## Mandatory Execution Workflow
|
## Mandatory Execution Workflow
|
||||||
|
|
||||||
Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
|
Work from this folder (`docs/plans/YYYY-MM-DD-<short-title>/` or repo-specific `docs/plan/...`) and always follow this order:
|
||||||
|
|
||||||
1. Read `continuation-runbook.md` first.
|
1. Read `continuation-runbook.md` first.
|
||||||
2. Execute stories milestone by milestone.
|
2. Execute stories milestone by milestone.
|
||||||
@@ -58,7 +51,7 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
|||||||
|
|
||||||
## Git Note
|
## Git Note
|
||||||
|
|
||||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
|
If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -109,17 +102,17 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
|||||||
|
|
||||||
### Lint (changed files first)
|
### Lint (changed files first)
|
||||||
```bash
|
```bash
|
||||||
# example: <lint-command> <changed-file-1> <changed-file-2>
|
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Typecheck
|
### Typecheck
|
||||||
```bash
|
```bash
|
||||||
# example: <typecheck-command>
|
# example: pnpm tsc --noEmit
|
||||||
```
|
```
|
||||||
|
|
||||||
### Tests (target changed scope first)
|
### Tests (target changed scope first)
|
||||||
```bash
|
```bash
|
||||||
# example: <test-command> <related spec/file>
|
# example: pnpm test -- <related spec/file>
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -5,12 +5,6 @@
|
|||||||
- **Created:** YYYY-MM-DD
|
- **Created:** YYYY-MM-DD
|
||||||
- **Status:** In Progress | Complete
|
- **Status:** In Progress | Complete
|
||||||
|
|
||||||
## Planning Guardrails
|
|
||||||
- This plan assumes design was validated before implementation planning.
|
|
||||||
- Skills are invoked via native discovery (Codex: `~/.agents/skills/`).
|
|
||||||
- Deprecated CLI wrappers (for example, `superpowers-codex bootstrap` / `use-skill`) are not part of this workflow.
|
|
||||||
- Milestones require verification + local commits + explicit approval before proceeding.
|
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
### Requirements
|
### Requirements
|
||||||
@@ -75,17 +69,17 @@
|
|||||||
|
|
||||||
### Types & Interfaces
|
### Types & Interfaces
|
||||||
```typescript
|
```typescript
|
||||||
// Key type definitions (or equivalent language constructs)
|
// Key type definitions
|
||||||
```
|
```
|
||||||
|
|
||||||
### API Contracts
|
### API Contracts
|
||||||
```typescript
|
```typescript
|
||||||
// Endpoint signatures, request/response shapes (if applicable)
|
// Endpoint signatures, request/response shapes
|
||||||
```
|
```
|
||||||
|
|
||||||
### Constants & Enums
|
### Constants & Enums
|
||||||
```typescript
|
```typescript
|
||||||
// Shared constants (if applicable)
|
// Shared constants
|
||||||
```
|
```
|
||||||
|
|
||||||
## Files Inventory
|
## Files Inventory
|
||||||
@@ -99,7 +93,7 @@
|
|||||||
|
|
||||||
## Related Plan Files
|
## Related Plan Files
|
||||||
|
|
||||||
This file is part of the plan folder under `ai_plan/`:
|
This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used):
|
||||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||||
- `milestone-plan.md` - This file (full specification)
|
- `milestone-plan.md` - This file (full specification)
|
||||||
|
|||||||
@@ -6,12 +6,6 @@
|
|||||||
- **Milestones Approved:** 0/M
|
- **Milestones Approved:** 0/M
|
||||||
- **Last Updated:** YYYY-MM-DD
|
- **Last Updated:** YYYY-MM-DD
|
||||||
|
|
||||||
## Tracking Guardrails
|
|
||||||
- Update status immediately when work starts (`in-dev`) and when work completes (`completed`).
|
|
||||||
- Require explicit user approval at each milestone boundary before continuing.
|
|
||||||
- Do not push until all milestones are approved and permission is explicitly granted.
|
|
||||||
- Keep this file and `milestone-plan.md` synchronized.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Milestones
|
## Milestones
|
||||||
|
|||||||
@@ -1,600 +0,0 @@
|
|||||||
---
|
|
||||||
name: create-plan
|
|
||||||
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context in Cursor Agent CLI workflows. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Create Plan (Cursor Agent CLI)
|
|
||||||
|
|
||||||
Create and maintain a local plan folder under `ai_plan/` at project root.
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-agent`):
|
|
||||||
1. Design first with `superpowers:brainstorming`
|
|
||||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
|
||||||
3. Review the plan iteratively with a second model/provider
|
|
||||||
4. Persist a local execution package in `ai_plan/YYYY-MM-DD-<short-title>/`
|
|
||||||
|
|
||||||
**Core principle:** Cursor Agent CLI discovers skills from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global). It also reads `AGENTS.md` at the repo root for additional instructions.
|
|
||||||
|
|
||||||
## Prerequisite Check (MANDATORY)
|
|
||||||
|
|
||||||
Required:
|
|
||||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
|
|
||||||
- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
|
|
||||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
|
||||||
- Superpowers skills installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
|
|
||||||
- `superpowers:brainstorming`
|
|
||||||
- `superpowers:writing-plans`
|
|
||||||
|
|
||||||
Verify before proceeding:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent --version
|
|
||||||
test -f .cursor/skills/superpowers/skills/brainstorming/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md
|
|
||||||
test -f .cursor/skills/superpowers/skills/writing-plans/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/writing-plans/SKILL.md
|
|
||||||
# Only if using cursor as reviewer CLI:
|
|
||||||
# jq --version
|
|
||||||
```
|
|
||||||
|
|
||||||
If any dependency is missing, stop and return:
|
|
||||||
|
|
||||||
`Missing dependency: Superpowers planning skills are required (superpowers:brainstorming, superpowers:writing-plans). Install from https://github.com/obra/superpowers and copy into .cursor/skills/ or ~/.cursor/skills/, then retry.`
|
|
||||||
|
|
||||||
## Required Skill Invocation Rules
|
|
||||||
|
|
||||||
- Invoke relevant skills through workspace discovery (`.cursor/skills/`).
|
|
||||||
- Announce skill usage explicitly:
|
|
||||||
- `I've read the [Skill Name] skill and I'm using it to [purpose].`
|
|
||||||
- For skills with checklists, track checklist items explicitly in conversation.
|
|
||||||
|
|
||||||
## Process
|
|
||||||
|
|
||||||
### Phase 1: Analyze
|
|
||||||
- Explore the codebase and existing patterns.
|
|
||||||
|
|
||||||
### Phase 2: Gather Requirements
|
|
||||||
- Ask questions one at a time until user says ready.
|
|
||||||
- Confirm scope, constraints, success criteria, dependencies.
|
|
||||||
|
|
||||||
### Phase 3: Configure Reviewer
|
|
||||||
|
|
||||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
|
||||||
|
|
||||||
1. **Which CLI should review the plan?**
|
|
||||||
- `codex` — OpenAI Codex CLI (`codex exec`)
|
|
||||||
- `claude` — Claude Code CLI (`claude -p`)
|
|
||||||
- `cursor` — Cursor Agent CLI (`cursor-agent -p`)
|
|
||||||
- `skip` — No external review, proceed directly to file generation
|
|
||||||
|
|
||||||
2. **Which model?** (only if a CLI was chosen)
|
|
||||||
- For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
|
|
||||||
- For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
|
|
||||||
- For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
|
|
||||||
- Accept any model string the user provides
|
|
||||||
|
|
||||||
3. **Max review rounds for the plan?** (default: 10)
|
|
||||||
- If the user does not provide a value, set `MAX_ROUNDS=10`.
|
|
||||||
|
|
||||||
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
|
|
||||||
|
|
||||||
### Phase 4: Design (REQUIRED SUB-SKILL)
|
|
||||||
|
|
||||||
Invoke `superpowers:brainstorming`, then propose 2-3 approaches and recommend one.
|
|
||||||
|
|
||||||
### Phase 5: Plan (REQUIRED SUB-SKILL)
|
|
||||||
|
|
||||||
Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories.
|
|
||||||
Story IDs: `S-{milestone}{sequence}`.
|
|
||||||
|
|
||||||
### Phase 6: Iterative Plan Review
|
|
||||||
|
|
||||||
Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
|
|
||||||
|
|
||||||
**Skip this phase entirely if reviewer was set to `skip`.**
|
|
||||||
|
|
||||||
#### Step 1: Generate Session ID
|
|
||||||
|
|
||||||
```bash
|
|
||||||
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
|
||||||
```
|
|
||||||
|
|
||||||
Use for temp artifacts:
|
|
||||||
- `/tmp/plan-${REVIEW_ID}.md`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.stderr`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.status`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.sh`
|
|
||||||
|
|
||||||
Resolve the shared reviewer helper from Cursor's installed skills directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x .cursor/skills/reviewer-runtime/run-review.sh ]; then
|
|
||||||
REVIEWER_RUNTIME=.cursor/skills/reviewer-runtime/run-review.sh
|
|
||||||
else
|
|
||||||
REVIEWER_RUNTIME=~/.cursor/skills/reviewer-runtime/run-review.sh
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Set helper success-artifact args before writing the command script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
HELPER_SUCCESS_FILE_ARGS=()
|
|
||||||
case "$REVIEWER_CLI" in
|
|
||||||
codex)
|
|
||||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
|
|
||||||
;;
|
|
||||||
cursor)
|
|
||||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 2: Write Plan to Temp File
|
|
||||||
|
|
||||||
Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
|
|
||||||
|
|
||||||
#### Review Contract (Applies to Every Round)
|
|
||||||
|
|
||||||
The reviewer response must use this structure:
|
|
||||||
|
|
||||||
```text
|
|
||||||
## Summary
|
|
||||||
...
|
|
||||||
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
- ...
|
|
||||||
### P1
|
|
||||||
- ...
|
|
||||||
### P2
|
|
||||||
- ...
|
|
||||||
### P3
|
|
||||||
- ...
|
|
||||||
|
|
||||||
## Verdict
|
|
||||||
VERDICT: APPROVED
|
|
||||||
```
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from `P0` to `P3`.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
|
|
||||||
- The calling agent should still try to fix `P3` findings when they are cheap and safe.
|
|
||||||
|
|
||||||
#### Liveness Contract (Applies While Review Is Running)
|
|
||||||
|
|
||||||
- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
|
|
||||||
- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
|
|
||||||
- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
|
|
||||||
- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
|
|
||||||
|
|
||||||
#### Step 3: Submit to Reviewer (Round 1)
|
|
||||||
|
|
||||||
Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
set -euo pipefail
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `codex`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
codex exec \
|
|
||||||
-m ${REVIEWER_MODEL} \
|
|
||||||
-s read-only \
|
|
||||||
-o /tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
"Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
|
|
||||||
```
|
|
||||||
|
|
||||||
Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `claude`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude -p \
|
|
||||||
"Review the implementation plan below. Focus on:
|
|
||||||
|
|
||||||
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
||||||
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--strict-mcp-config \
|
|
||||||
--setting-sources user
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `cursor`:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent -p \
|
|
||||||
--mode=ask \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--trust \
|
|
||||||
--output-format json \
|
|
||||||
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
|
|
||||||
1. Correctness — Will this plan achieve the stated goals?
|
|
||||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
|
||||||
3. Missing steps — Is anything forgotten?
|
|
||||||
4. Alternatives — Is there a simpler or better approach?
|
|
||||||
5. Security — Any security concerns?
|
|
||||||
|
|
||||||
Return exactly these sections in order:
|
|
||||||
## Summary
|
|
||||||
## Findings
|
|
||||||
### P0
|
|
||||||
### P1
|
|
||||||
### P2
|
|
||||||
### P3
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Order findings from highest severity to lowest.
|
|
||||||
- Use `- None.` when a severity has no findings.
|
|
||||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
|
||||||
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
|
|
||||||
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
|
|
||||||
> /tmp/plan-review-${REVIEW_ID}.json
|
|
||||||
```
|
|
||||||
|
|
||||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
|
|
||||||
|
|
||||||
Notes on Cursor flags:
|
|
||||||
- `--mode=ask` — read-only mode, no file modifications
|
|
||||||
- `--trust` — trust workspace without prompting (required for non-interactive use)
|
|
||||||
- `-p` / `--print` — non-interactive mode, output to stdout
|
|
||||||
- `--output-format json` — structured output with `session_id` and `result` fields
|
|
||||||
|
|
||||||
Run the command script through the shared helper when available:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x "$REVIEWER_RUNTIME" ]; then
|
|
||||||
"$REVIEWER_RUNTIME" \
|
|
||||||
--command-file /tmp/plan-review-${REVIEW_ID}.sh \
|
|
||||||
--stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
|
|
||||||
--stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
|
|
||||||
--status-file /tmp/plan-review-${REVIEW_ID}.status \
|
|
||||||
"${HELPER_SUCCESS_FILE_ARGS[@]}"
|
|
||||||
else
|
|
||||||
echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
|
|
||||||
bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
|
||||||
|
|
||||||
After the command completes:
|
|
||||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
|
|
||||||
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
|
|
||||||
- If `REVIEWER_CLI=claude`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 4: Read Review & Check Verdict
|
|
||||||
|
|
||||||
1. Read `/tmp/plan-review-${REVIEW_ID}.md`
|
|
||||||
2. If the review failed, produced empty output, or reached helper timeout, also read:
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.stderr`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.status`
|
|
||||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
|
||||||
3. Present review to the user:
|
|
||||||
|
|
||||||
```
|
|
||||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
|
||||||
|
|
||||||
[Reviewer feedback]
|
|
||||||
```
|
|
||||||
|
|
||||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
|
||||||
5. Check verdict:
|
|
||||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
|
||||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
|
||||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
|
||||||
- No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
|
|
||||||
- Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
|
|
||||||
- Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
|
|
||||||
- Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
|
|
||||||
|
|
||||||
#### Step 5: Revise the Plan
|
|
||||||
|
|
||||||
Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
|
|
||||||
|
|
||||||
Summarize revisions for the user:
|
|
||||||
|
|
||||||
```
|
|
||||||
### Revisions (Round N)
|
|
||||||
- [Change and reason, one bullet per issue addressed]
|
|
||||||
```
|
|
||||||
|
|
||||||
If a revision contradicts the user's explicit requirements, skip it and note it for the user.
|
|
||||||
|
|
||||||
#### Step 6: Re-submit to Reviewer (Rounds 2-N)
|
|
||||||
|
|
||||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `codex`:**
|
|
||||||
|
|
||||||
Resume the existing session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
codex exec resume ${CODEX_SESSION_ID} \
|
|
||||||
-o /tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
|
|
||||||
```
|
|
||||||
|
|
||||||
If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `claude`:**
|
|
||||||
|
|
||||||
Fresh call with accumulated context (Claude CLI has no session resume):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
claude -p \
|
|
||||||
"You previously reviewed an implementation plan and requested revisions.
|
|
||||||
|
|
||||||
Previous feedback summary: [key points from last review]
|
|
||||||
|
|
||||||
I've revised the plan. Updated version is below.
|
|
||||||
|
|
||||||
$(cat /tmp/plan-${REVIEW_ID}.md)
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--strict-mcp-config \
|
|
||||||
--setting-sources user
|
|
||||||
```
|
|
||||||
|
|
||||||
**If `REVIEWER_CLI` is `cursor`:**
|
|
||||||
|
|
||||||
Resume the existing session:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cursor-agent --resume ${CURSOR_SESSION_ID} -p \
|
|
||||||
--mode=ask \
|
|
||||||
--model ${REVIEWER_MODEL} \
|
|
||||||
--trust \
|
|
||||||
--output-format json \
|
|
||||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
|
||||||
|
|
||||||
Changes made:
|
|
||||||
[List specific changes]
|
|
||||||
|
|
||||||
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
|
|
||||||
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
|
|
||||||
> /tmp/plan-review-${REVIEW_ID}.json
|
|
||||||
|
|
||||||
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
|
|
||||||
```
|
|
||||||
|
|
||||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
|
||||||
|
|
||||||
After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
|
||||||
|
|
||||||
Return to Step 4.
|
|
||||||
|
|
||||||
#### Step 7: Present Final Result
|
|
||||||
|
|
||||||
```
|
|
||||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
|
||||||
|
|
||||||
**Status:** Approved after N round(s)
|
|
||||||
[or]
|
|
||||||
**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
|
|
||||||
|
|
||||||
[Final feedback / remaining concerns]
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Step 8: Cleanup
|
|
||||||
|
|
||||||
```bash
|
|
||||||
rm -f /tmp/plan-${REVIEW_ID}.md \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.md \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.json \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.stderr \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.status \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.runner.out \
|
|
||||||
/tmp/plan-review-${REVIEW_ID}.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
|
|
||||||
|
|
||||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
|
||||||
|
|
||||||
At project root:
|
|
||||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
|
||||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
|
||||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
|
||||||
|
|
||||||
Recommended commit message:
|
|
||||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
|
||||||
|
|
||||||
### Phase 8: Generate Plan Files (MANDATORY)
|
|
||||||
|
|
||||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
|
||||||
1. `original-plan.md` - copy of original planner-generated plan.
|
|
||||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
|
||||||
3. `milestone-plan.md` - full implementation spec (from template).
|
|
||||||
4. `story-tracker.md` - story/milestone status tracker (from template).
|
|
||||||
5. `continuation-runbook.md` - execution instructions and context (from template).
|
|
||||||
|
|
||||||
Use templates from this skill's `templates/` folder.
|
|
||||||
|
|
||||||
### Phase 9: Handoff
|
|
||||||
|
|
||||||
Always instruct the executing agent:
|
|
||||||
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.
|
|
||||||
|
|
||||||
Do not rely on planner-private files during implementation.
|
|
||||||
|
|
||||||
### Phase 10: Telegram Notification (MANDATORY)
|
|
||||||
|
|
||||||
Resolve the Telegram notifier helper from Cursor's installed skills directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x .cursor/skills/reviewer-runtime/notify-telegram.sh ]; then
|
|
||||||
TELEGRAM_NOTIFY_RUNTIME=.cursor/skills/reviewer-runtime/notify-telegram.sh
|
|
||||||
else
|
|
||||||
TELEGRAM_NOTIFY_RUNTIME=~/.cursor/skills/reviewer-runtime/notify-telegram.sh
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
|
|
||||||
"$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
|
||||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
|
||||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
|
||||||
- If Telegram is not configured, state that no Telegram notification was sent.
|
|
||||||
|
|
||||||
## Quick Reference
|
|
||||||
|
|
||||||
| Phase | Action | Required Output |
|
|
||||||
|---|---|---|
|
|
||||||
| 1 | Analyze codebase/context | Constraints and known patterns |
|
|
||||||
| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria |
|
|
||||||
| 3 | Configure reviewer CLI and model | `REVIEWER_CLI`, `REVIEWER_MODEL`, `MAX_ROUNDS` (or `skip`) |
|
|
||||||
| 4 | Invoke `superpowers:brainstorming` | Chosen design approach |
|
|
||||||
| 5 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories |
|
|
||||||
| 6 | Iterative plan review (max `MAX_ROUNDS` rounds) | Reviewer approval or max-rounds warning |
|
|
||||||
| 7 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
|
|
||||||
| 8 | Build plan package from templates | Full plan folder with required files |
|
|
||||||
| 9 | Handoff with runbook-first instruction | Resumable execution context |
|
|
||||||
| 10 | Send Telegram notification | User notified or notification status reported |
|
|
||||||
|
|
||||||
## Tracker Discipline (MANDATORY)
|
|
||||||
|
|
||||||
Before starting any story:
|
|
||||||
1. Open `story-tracker.md`
|
|
||||||
2. Mark story `in-dev`
|
|
||||||
3. Add notes if relevant
|
|
||||||
4. Then begin implementation
|
|
||||||
|
|
||||||
After completing any story:
|
|
||||||
1. Mark story `completed`
|
|
||||||
2. Add commit hash in Notes
|
|
||||||
3. Review pending stories
|
|
||||||
4. Update Last Updated and Stories Complete counts
|
|
||||||
|
|
||||||
## Execution Rules to Include in Plan (MANDATORY)
|
|
||||||
|
|
||||||
- Run lint/typecheck/tests after each milestone.
|
|
||||||
- Prefer linting changed files only for speed.
|
|
||||||
- Commit locally after each completed milestone (**do not push**).
|
|
||||||
- Stop and ask user for feedback.
|
|
||||||
- Apply feedback, rerun checks, and commit again.
|
|
||||||
- Move to next milestone only after user approval.
|
|
||||||
- After all milestones are completed and approved, ask permission to push.
|
|
||||||
- Only after approved push: mark plan as completed.
|
|
||||||
|
|
||||||
## Gitignore Note
|
|
||||||
|
|
||||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
|
|
||||||
|
|
||||||
## Common Mistakes
|
|
||||||
|
|
||||||
- Forgetting `--trust` flag when running `cursor-agent` non-interactively (causes interactive prompt).
|
|
||||||
- Using `--mode=agent` or `--force` for reviews (reviewer should be read-only, use `--mode=ask`).
|
|
||||||
- Jumping to implementation planning without running `superpowers:brainstorming` first.
|
|
||||||
- Asking multiple requirement questions in one message.
|
|
||||||
- Forgetting to create/update `.gitignore` for `/ai_plan/`.
|
|
||||||
- Omitting one or more required files in the plan package.
|
|
||||||
- Handoff without explicit "read runbook first" direction.
|
|
||||||
- Skipping the reviewer phase without explicit user opt-out.
|
|
||||||
- Using any notification path other than Telegram.
|
|
||||||
|
|
||||||
## Red Flags - Stop and Correct
|
|
||||||
|
|
||||||
- You started writing milestones before design validation.
|
|
||||||
- You did not announce which skill you invoked and why.
|
|
||||||
- You are marking planning complete without all required files.
|
|
||||||
- Handoff does not explicitly point to `continuation-runbook.md`.
|
|
||||||
- You are applying a reviewer suggestion that contradicts user requirements.
|
|
||||||
- Reviewer CLI is running with write permissions (must be read-only).
|
|
||||||
|
|
||||||
## Verification Checklist
|
|
||||||
|
|
||||||
- [ ] `ai_plan/` exists at project root
|
|
||||||
- [ ] `.gitignore` includes `/ai_plan/`
|
|
||||||
- [ ] `.gitignore` ignore-rule commit was created if needed
|
|
||||||
- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
|
|
||||||
- [ ] Reviewer configured or explicitly skipped
|
|
||||||
- [ ] Max review rounds confirmed (default: 10)
|
|
||||||
- [ ] Plan review completed (approved or max rounds) — or skipped
|
|
||||||
- [ ] `original-plan.md` present
|
|
||||||
- [ ] `final-transcript.md` present
|
|
||||||
- [ ] `milestone-plan.md` present
|
|
||||||
- [ ] `story-tracker.md` present
|
|
||||||
- [ ] `continuation-runbook.md` present
|
|
||||||
- [ ] Handoff explicitly says to read runbook first and execute from plan folder
|
|
||||||
- [ ] Telegram notification attempted if configured
|
|
||||||
|
|
||||||
## Exit Triggers for Question Phase
|
|
||||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
|
||||||
@@ -1,134 +0,0 @@
|
|||||||
# Continuation Runbook: [Plan Title]
|
|
||||||
|
|
||||||
## Reference Files (START HERE)
|
|
||||||
|
|
||||||
Upon resumption, these files in this folder are the ONLY source of truth:
|
|
||||||
|
|
||||||
| File | Purpose | When to Use |
|
|
||||||
|------|---------|-------------|
|
|
||||||
| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST |
|
|
||||||
| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story |
|
|
||||||
| `milestone-plan.md` | Complete plan with specifications | Reference implementation details |
|
|
||||||
| `original-plan.md` | Original approved plan | Reference original intent |
|
|
||||||
| `final-transcript.md` | Final planning transcript | Reference reasoning/context |
|
|
||||||
|
|
||||||
Do NOT reference planner-private files during implementation.
|
|
||||||
|
|
||||||
## Skill Workflow Guardrails
|
|
||||||
|
|
||||||
- Invoke relevant skills before action using workspace discovery (`.cursor/skills/`).
|
|
||||||
- Announce which skill is being used and why.
|
|
||||||
- If a checklist-driven skill applies, track checklist execution explicitly.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Resume Instructions
|
|
||||||
|
|
||||||
1. Read this runbook completely.
|
|
||||||
2. Check `story-tracker.md`.
|
|
||||||
3. Find next `pending` story and mark as `in-dev` before starting.
|
|
||||||
4. Implement the story.
|
|
||||||
5. Update tracker immediately after each change.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Mandatory Execution Workflow
|
|
||||||
|
|
||||||
Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
|
|
||||||
|
|
||||||
1. Read `continuation-runbook.md` first.
|
|
||||||
2. Execute stories milestone by milestone.
|
|
||||||
3. After completing a milestone:
|
|
||||||
- Run lint/typecheck/tests, prioritizing changed files for speed.
|
|
||||||
- Commit locally (**DO NOT PUSH**).
|
|
||||||
- Stop and ask user for feedback.
|
|
||||||
4. If feedback is provided:
|
|
||||||
- Apply feedback changes.
|
|
||||||
- Re-run checks for changed files.
|
|
||||||
- Commit locally again.
|
|
||||||
- Ask for milestone approval.
|
|
||||||
5. Only move to next milestone after explicit approval.
|
|
||||||
6. After all milestones are completed and approved:
|
|
||||||
- Ask permission to push.
|
|
||||||
- If approved, push.
|
|
||||||
- Mark plan status as `completed`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Git Note
|
|
||||||
|
|
||||||
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Full Context Reproduction
|
|
||||||
|
|
||||||
### Project Overview
|
|
||||||
[What this project/feature is about]
|
|
||||||
|
|
||||||
### User Requirements
|
|
||||||
[All gathered requirements]
|
|
||||||
|
|
||||||
### Scope
|
|
||||||
[In scope / out of scope]
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
[External dependencies, prerequisites, related systems]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Specifications
|
|
||||||
|
|
||||||
### Type Definitions
|
|
||||||
```typescript
|
|
||||||
// Copy-paste ready type definitions
|
|
||||||
```
|
|
||||||
|
|
||||||
### Enums & Constants
|
|
||||||
```typescript
|
|
||||||
// All enums/constants needed
|
|
||||||
```
|
|
||||||
|
|
||||||
### API Endpoints
|
|
||||||
```typescript
|
|
||||||
// Request/response shapes
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Critical Design Decisions
|
|
||||||
|
|
||||||
| Decision | Chosen Approach | Alternatives Rejected | Rationale |
|
|
||||||
|----------|-----------------|----------------------|-----------|
|
|
||||||
| [Topic] | [What we chose] | [Other options] | [Why] |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Verification Commands
|
|
||||||
|
|
||||||
### Lint (changed files first)
|
|
||||||
```bash
|
|
||||||
# example: <lint-command> <changed-file-1> <changed-file-2>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Typecheck
|
|
||||||
```bash
|
|
||||||
# example: <typecheck-command>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Tests (target changed scope first)
|
|
||||||
```bash
|
|
||||||
# example: <test-command> <related spec/file>
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Quick Reference
|
|
||||||
|
|
||||||
| File | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `original-plan.md` | Original approved plan |
|
|
||||||
| `final-transcript.md` | Final planning transcript |
|
|
||||||
| `milestone-plan.md` | Full specification |
|
|
||||||
| `story-tracker.md` | Current progress tracker |
|
|
||||||
| `continuation-runbook.md` | This runbook |
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user