atli 0.5.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
atli/jira/fields.py ADDED
@@ -0,0 +1,75 @@
1
+ """Build Jira `fields` payloads from CLI options."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+ UNASSIGN = "x"
9
+ _UNASSIGN_ALIASES = frozenset({UNASSIGN, "none"})
10
+
11
+
12
+ def _coerce_field_value(value: str) -> Any:
13
+ """Parse JSON array/object values into real lists/dicts; scalars stay strings."""
14
+ stripped = value.strip()
15
+ if stripped[:1] not in ("[", "{"):
16
+ return value
17
+ try:
18
+ parsed = json.loads(stripped)
19
+ except json.JSONDecodeError:
20
+ return value
21
+ return parsed if isinstance(parsed, (list, dict)) else value
22
+
23
+ def parse_field_options(values: tuple[str, ...] | list[str]) -> dict[str, Any]:
24
+ """Parse repeatable `--field KEY=VALUE` options."""
25
+ out: dict[str, Any] = {}
26
+ for raw in values:
27
+ if "=" not in raw:
28
+ raise ValueError(f"--field expects KEY=VALUE, got {raw!r}")
29
+ key, value = raw.split("=", 1)
30
+ if not key:
31
+ raise ValueError(f"--field expects KEY=VALUE, got {raw!r}")
32
+ out[key] = _coerce_field_value(value)
33
+ return out
34
+
35
+
36
+ def build_issue_fields(
37
+ *,
38
+ summary: str | None = None,
39
+ description: str | None = None,
40
+ issue_type: str | None = None,
41
+ priority: str | None = None,
42
+ assignee: str | None = None,
43
+ labels: tuple[str, ...] | list[str] | None = None,
44
+ components: tuple[str, ...] | list[str] | None = None,
45
+ parent: str | None = None,
46
+ extra: dict[str, Any] | None = None,
47
+ ) -> dict[str, Any]:
48
+ """Return a Jira `fields` fragment with only set keys.
49
+
50
+ Assignee values ``x`` / ``none`` (case-insensitive) become JSON ``null``
51
+ (unassign). Omit assignee entirely when the argument is ``None``.
52
+ """
53
+ fields: dict[str, Any] = {}
54
+ if summary is not None:
55
+ fields["summary"] = summary
56
+ if description is not None:
57
+ fields["description"] = description
58
+ if issue_type is not None:
59
+ fields["issuetype"] = {"name": issue_type}
60
+ if priority is not None:
61
+ fields["priority"] = {"name": priority}
62
+ if assignee is not None:
63
+ if assignee.casefold() in _UNASSIGN_ALIASES:
64
+ fields["assignee"] = None
65
+ else:
66
+ fields["assignee"] = {"name": assignee}
67
+ if labels is not None:
68
+ fields["labels"] = list(labels)
69
+ if components is not None:
70
+ fields["components"] = [{"name": c} for c in components]
71
+ if parent is not None:
72
+ fields["parent"] = {"key": parent}
73
+ if extra:
74
+ fields.update(extra)
75
+ return fields
atli/jira/jql.py ADDED
@@ -0,0 +1,69 @@
1
+ """Helpers for composing JQL used by `atli jira list`."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ def jql_user_or_func(value: str) -> str:
7
+ """Format a username or JQL function (e.g. currentUser())."""
8
+ if value.endswith(")") and "(" in value:
9
+ return value
10
+ return f'"{value}"'
11
+
12
+
13
+ def jql_relative_or_keyword(value: str, *, field: str, before: bool = False) -> str:
14
+ """Build a created/updated clause.
15
+
16
+ Accepts relative tokens (``-7d``, ``-1h``) or keywords ``week`` / ``month``.
17
+ """
18
+ v = value.strip()
19
+ op = "<=" if before else ">="
20
+ lower = v.casefold()
21
+ if lower == "week":
22
+ bound = "startOfWeek()" if not before else "endOfWeek()"
23
+ return f"{field} {op} {bound}"
24
+ if lower == "month":
25
+ bound = "startOfMonth()" if not before else "endOfMonth()"
26
+ return f"{field} {op} {bound}"
27
+ return f"{field} {op} {v}"
28
+
29
+
30
+ def build_list_jql(
31
+ *,
32
+ project: str,
33
+ status: str | None = None,
34
+ assignee: str | None = None,
35
+ reporter: str | None = None,
36
+ priority: str | None = None,
37
+ labels: tuple[str, ...] | list[str] | None = None,
38
+ watching: bool = False,
39
+ created: str | None = None,
40
+ created_before: str | None = None,
41
+ updated: str | None = None,
42
+ updated_before: str | None = None,
43
+ order_by: str = "updated",
44
+ reverse: bool = False,
45
+ ) -> str:
46
+ parts = [f"project = {project}"]
47
+ if status:
48
+ parts.append(f'status = "{status}"')
49
+ if assignee:
50
+ parts.append(f"assignee = {jql_user_or_func(assignee)}")
51
+ if reporter:
52
+ parts.append(f"reporter = {jql_user_or_func(reporter)}")
53
+ if priority:
54
+ parts.append(f'priority = "{priority}"')
55
+ if labels:
56
+ for label in labels:
57
+ parts.append(f'labels = "{label}"')
58
+ if watching:
59
+ parts.append("watcher = currentUser()")
60
+ if created:
61
+ parts.append(jql_relative_or_keyword(created, field="created"))
62
+ if created_before:
63
+ parts.append(jql_relative_or_keyword(created_before, field="created", before=True))
64
+ if updated:
65
+ parts.append(jql_relative_or_keyword(updated, field="updated"))
66
+ if updated_before:
67
+ parts.append(jql_relative_or_keyword(updated_before, field="updated", before=True))
68
+ direction = "ASC" if reverse else "DESC"
69
+ return " AND ".join(parts) + f" ORDER BY {order_by} {direction}"
atli/output.py ADDED
@@ -0,0 +1,54 @@
1
+ """Shared output helpers for atli commands.
2
+
3
+ Two modes:
4
+ * default — human-readable rich output (tables, key/value blocks)
5
+ * json — `print(json.dumps(...))` for shell pipelines
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import sys
12
+ from typing import Any
13
+
14
+ from rich.console import Console
15
+ from rich.table import Table
16
+
17
+ console = Console()
18
+ err_console = Console(stderr=True)
19
+
20
+
21
+ def emit_json(data: Any) -> None:
22
+ """Print compact-but-readable JSON to stdout."""
23
+ json.dump(data, sys.stdout, indent=2, ensure_ascii=False)
24
+ sys.stdout.write("\n")
25
+
26
+
27
+ def emit_kv(rows: list[tuple[str, Any]], json_mode: bool, payload: Any | None = None) -> None:
28
+ """Show key/value rows; in JSON mode emit `payload` (or dict from rows)."""
29
+ if json_mode:
30
+ emit_json(payload if payload is not None else dict(rows))
31
+ return
32
+ width = max((len(k) for k, _ in rows), default=0)
33
+ for key, value in rows:
34
+ if value is None or value == "":
35
+ continue
36
+ console.print(f"[bold]{key:<{width}}[/bold] {value}")
37
+
38
+
39
+ def emit_table(headers: list[str], rows: list[list[Any]], json_mode: bool, payload: Any | None = None) -> None:
40
+ if json_mode:
41
+ emit_json(payload if payload is not None else [dict(zip(headers, r)) for r in rows])
42
+ return
43
+ table = Table(show_header=True, header_style="bold")
44
+ for h in headers:
45
+ table.add_column(h)
46
+ for r in rows:
47
+ table.add_row(*[str(c) if c is not None else "" for c in r])
48
+ console.print(table)
49
+
50
+
51
+ def fail(message: str, code: int = 1) -> None:
52
+ """Print error to stderr and exit with `code`."""
53
+ err_console.print(f"[red]error:[/red] {message}")
54
+ sys.exit(code)
@@ -0,0 +1,173 @@
1
+ ---
2
+ name: atli-confluence
3
+ description: Use when creating, viewing, updating, listing, or searching Confluence pages via the `atli` CLI. Covers storage format vs wiki markup, upsert pattern, and CQL search.
4
+ ---
5
+
6
+ # atli conf — Confluence operations
7
+
8
+ Run `atli config show` first to confirm Confluence is configured (see using-atli skill).
9
+
10
+ ## Commands
11
+
12
+ ```
13
+ atli conf create --space TEAM --title "..." (--file body | --content "...") [--format storage|wiki|markdown|markdown-macro] [--parent-id 123]
14
+ atli conf view --space TEAM --title "..." [--body]
15
+ atli conf update --space TEAM --title "..." (--file body | --content "...") [--create-if-missing] [--format storage|wiki|markdown|markdown-macro]
16
+ atli conf delete (--id <id> | --space TEAM --title "...") [--yes]
17
+ atli conf list --space TEAM
18
+ atli conf search [QUERY] [--cql] [--space TEAM] [--label draft] [--title "..."] [--text "..."] [--limit N]
19
+ # QUERY is text search by default; use --cql for raw CQL
20
+ # or use convenience filters: --space / --label / --title / --text
21
+ atli conf children (--space TEAM --title "..." | --id ID) [--limit 100]
22
+ atli conf move --id PAGE_ID --parent NEW_PARENT_ID
23
+ atli conf attach --space TEAM --title "..." --file /path/to/file
24
+ atli conf attachment list (--space TEAM --title "..." | --id ID) [--limit 50]
25
+ atli conf attachment download ATTACHMENT_ID [-o output_path]
26
+ atli conf property list (--space TEAM --title "..." | --id ID)
27
+ atli conf property get KEY (--space TEAM --title "..." | --id ID)
28
+ atli conf property set KEY VALUE (--space TEAM --title "..." | --id ID)
29
+ atli conf property delete KEY (--space TEAM --title "..." | --id ID)
30
+ atli conf label list (--space TEAM --title "..." | --id ID)
31
+ atli conf label add LABEL [LABEL ...] (--space TEAM --title "..." | --id ID)
32
+ atli conf label delete LABEL (--space TEAM --title "..." | --id ID)
33
+ atli conf space list [--type global|personal] [--limit 100]
34
+ atli conf space view SPACE_KEY
35
+ atli conf space create --key KEY --name "..." [--description "..."]
36
+ atli conf space update SPACE_KEY [--name "..."] [--description "..."]
37
+ atli conf space delete SPACE_KEY [--yes]
38
+ atli conf children (--space TEAM --title "..." | --id ID) [--limit 100]
39
+ ```
40
+
41
+ ## The body format gotcha
42
+
43
+ Confluence stores pages in **storage format** — an XHTML-flavored XML that is *not* HTML, *not* markdown, and *not* wiki markup. Common mistakes:
44
+
45
+ | Input you have | What to do |
46
+ |----------------|------------|
47
+ | Markdown (`.md`) | Pass `--format markdown` — `atli` converts via pandoc (preferred) or markdown-it-py (fallback). Code blocks render as Confluence code macros. For inline content, the same flag applies. |
48
+ | Markdown intended for the wiki's Markdown macro plugin (Mermaid etc.) | Pass `--format markdown-macro` — atli wraps the body in `<ac:structured-macro ac:name="markdown">` so the plugin renders client-side. Requires the plugin to be installed. |
49
+ | Plain HTML | Mostly works in storage format, but self-closing tags must be XML-style: `<br/>` not `<br>`. |
50
+ | Confluence wiki markup | Pass `--format wiki`. The instance has to support the wiki representation (most Server/DC instances do). |
51
+ | Already in storage format | Pass through with default `--format storage`. |
52
+
53
+ Confluence-specific macros (panels, info boxes, code blocks) use storage-format XML like `<ac:structured-macro ac:name="info">...</ac:structured-macro>`. Generating these is fragile — when the user wants a code block or info panel, ask whether they want a quick `<pre>...</pre>` (works) or a full Confluence macro (more work, but renders nicer).
54
+
55
+ ## Pattern: publish or refresh a design doc
56
+
57
+ ```bash
58
+ # Idempotent: create if missing, else update
59
+ atli conf update \
60
+ --space TEAM \
61
+ --title "Search Design v1" \
62
+ --file plan.md \
63
+ --format markdown \
64
+ --create-if-missing
65
+ ```
66
+
67
+ `--create-if-missing` is the upsert mode. Without it, `update` errors if the page doesn't exist.
68
+
69
+ ## Pattern: attach a file to a page
70
+
71
+ ```bash
72
+ # Upload a PDF report to an existing page
73
+ atli conf attach \
74
+ --space TEAM \
75
+ --title "Sprint Review 2024-Q4" \
76
+ --file ./report.pdf
77
+
78
+ # If the file already exists as an attachment, Confluence creates a new version
79
+ ```
80
+
81
+ Maximum file size: 100 MB. Supported formats: PDFs, images, Office docs, etc.
82
+
83
+ ## Pattern: append a section to an existing page
84
+
85
+ There is no native append. Do it explicitly:
86
+
87
+ ```bash
88
+ # 1. Pull current body
89
+ atli --json conf view --space TEAM --title "Runbook" \
90
+ | jq -r '.body.storage.value' > /tmp/current.html
91
+
92
+ # 2. Add new section — ensure content is XML-safe
93
+ # Escape &, <, > or wrap in CDATA if needed to keep storage format valid
94
+ cat <<'EOF' >> /tmp/current.html
95
+ <h2>2026-05-10 incident</h2><p>...</p>
96
+ EOF
97
+
98
+ # 3. Update — version is bumped automatically
99
+ atli conf update --space TEAM --title "Runbook" --file /tmp/current.html
100
+ ```
101
+
102
+ ## Pattern: search
103
+
104
+ Default search constructs CQL `type = page AND text ~ "query"`. For more control, pass `--cql`:
105
+
106
+ ```bash
107
+ # Text search (only pages, not blogposts or attachments)
108
+ atli conf search "incident response"
109
+
110
+ # Raw CQL (full power: space filter, label filter, contributor filter, ...)
111
+ atli conf search --cql 'space = TEAM AND label = "runbook" AND lastModified > now("-7d")'
112
+ ```
113
+
114
+ CQL field reference:
115
+ - `space = TEAM`
116
+ - `type = page` (also: blogpost, comment, attachment)
117
+ - `label = "name"`
118
+ - `creator = "username"`
119
+ - `lastModified > now("-7d")`
120
+ - `text ~ "phrase"` (full-text)
121
+
122
+ ## Output shape (`--json`)
123
+
124
+ `view` / `find`:
125
+ ```json
126
+ {
127
+ "id": "9001",
128
+ "title": "Search Design",
129
+ "space": {"key": "TEAM"},
130
+ "version": {"number": 3},
131
+ "body": {"storage": {"value": "<p>...</p>", "representation": "storage"}},
132
+ "_links": {"webui": "/spaces/TEAM/pages/9001"}
133
+ }
134
+ ```
135
+
136
+ `--body` only affects non-JSON output (prints the raw page body). In `--json` mode the full page object—including `body`—is always returned.
137
+
138
+ `search` / `list`:
139
+ ```json
140
+ {"results": [ {"id": "...", "title": "...", "space": {...}}, ... ], "size": 5}
141
+ ```
142
+
143
+ ## Limitations
144
+
145
+ - **Cannot change parent page via update**: The `update` command does not accept `--parent-id`. The underlying `upsert_page()` only passes `parent_id` when creating a new page; updating an existing page never changes its parent. To move a page, use the Confluence web UI or the REST API directly.
146
+ - **view only supports space + title**: Unlike `delete` (which supports both `--id` and `--space + --title`), `view` only supports `--space` and `--title`. There is no `--id` option for `view`.
147
+ - **Pagination**: `list` defaults to 25 results and `search` defaults to 10 results (`--limit` controls page size). There is no built-in pagination helper; for large result sets, manage `start` manually via raw CQL.
148
+
149
+ ## Constraints
150
+
151
+ 1. **When an operation is unsupported, explain why and provide evidence**
152
+ - If `atli conf` does not support an operation (e.g. page permission changes, bulk label management, attachment uploads, page moves, space creation), **clearly tell the user the operation cannot be done via `atli conf`**, explain the specific reason (command does not exist, API limitation, outside CLI scope), and provide evidence (e.g. `atli conf --help` output, or reference the Atlassian REST API docs).
153
+ - **Do not** unilaterally fall back to alternatives (e.g. raw `curl`, direct API calls, web UI actions). You may **suggest** alternatives, but must get user confirmation before executing.
154
+
155
+ 2. **Ask for confirmation when instructions are ambiguous**
156
+ - When parameters are missing or the intent is unclear, **stop and ask the user** rather than inferring intent or choosing defaults.
157
+ - Example: when asked to "update a Confluence page" without specifying space, title, or format, **first ask for these required fields**; when asked to "create a page" without `--format`, **ask the user for the input format** (Markdown / HTML / wiki markup / storage format) rather than defaulting to `markdown`.
158
+ - For optional parameters like parent page, labels, or permissions, ask the user whether they want to set them; do not decide on their behalf.
159
+
160
+ 3. **Confirm before destructive operations**
161
+ - For any `atli conf` operation that modifies or deletes data (e.g. `atli conf update`, `atli conf delete`), before executing:
162
+ 1. **Show the user the operation details** (target page space, title, ID, change content, etc.).
163
+ 2. **Get explicit user approval** before proceeding.
164
+ - For delete operations (`atli conf delete`), do not use `--yes` to skip confirmation unless the user has explicitly authorized it. Note: when `--json` is set, `--yes` is **required** because JSON mode cannot prompt interactively.
165
+
166
+ ## Anti-patterns
167
+
168
+ - ❌ Passing a `.md` file without `--format markdown`. The CLI emits a warning, uploads the file as-is, and the page renders the raw markdown text instead of formatted HTML.
169
+ - ❌ Using `--format markdown` and expecting Mermaid blocks to render as diagrams. The CLI converts the fence to a Confluence code macro with `language=mermaid`, which is just a syntax-highlight hint — the page shows the source. Use `--format markdown-macro` if the wiki has the Markdown plugin installed.
170
+ - ❌ Storing a token in a script. Use `~/.config/atli/config.toml` or env.
171
+ - ❌ Updating a page without confirming title and space — Confluence allows different spaces to have pages with the same title; `view` returns the first match. Pass `--space` correctly.
172
+ - ❌ Generating Confluence macros by hand without verifying with the user that the rendered result looks right. Storage XML is verbose and easy to break.
173
+ - ❌ Deleting without first listing or viewing the target. The CLI's prompt shows id + title, but if you pass `--yes` you skip that safety net. Run `atli conf list` or `atli conf view` first when in doubt.
@@ -0,0 +1,209 @@
1
+ ---
2
+ name: atli-jira
3
+ description: Use when operating Jira via the `atli` CLI — issues, links, epics/sprints/boards, worklogs, watchers, clone/delete. Covers JQL, Agile, and JSON-mode parsing.
4
+ ---
5
+
6
+ # atli jira — Jira operations
7
+
8
+ Run `atli config show` first to confirm Jira is configured (see using-atli skill).
9
+
10
+ ## Commands
11
+
12
+ ```
13
+ atli jira create --project PROJ --title "..." --type Bug|Task|Story
14
+ [--description "..."] [--file path] [--assignee alice]
15
+ [--priority High] [--label x] [--component y] [--parent KEY]
16
+ [--field KEY=VALUE]
17
+ atli jira edit PROJ-123 [--title "..."] [--description "..."] [--file path]
18
+ [--type Task] [--priority High] [--assignee alice|x]
19
+ [--label x] [--component y] [--parent KEY] [--field KEY=VALUE]
20
+ atli jira assign PROJ-123 alice|x|none
21
+ atli jira link INWARD OUTWARD TYPE # e.g. PROJ-1 PROJ-2 Blocks
22
+ atli jira unlink PROJ-1 PROJ-2
23
+ atli jira remote-link add KEY URL [TITLE]
24
+ atli jira remote-link list KEY
25
+ atli jira remote-link update KEY LINK_ID URL [--title ...]
26
+ atli jira remote-link delete KEY LINK_ID [--yes]
27
+ atli jira user search QUERY [--project PROJ] [--issue KEY] [--limit 20]
28
+ atli jira me
29
+ atli jira view PROJ-123
30
+ atli jira list --project PROJ [--status ...] [--assignee ...] [--reporter ...]
31
+ [--priority ...] [--label ...] [--watching]
32
+ [--created -7d|week|month] [--created-before YYYY-MM-DD]
33
+ [--updated-before YYYY-MM-DD]
34
+ [--order-by updated] [--reverse] [--limit 20]
35
+ atli jira search "<JQL>" [--limit 20]
36
+ atli jira comment add PROJ-123 (--text "..." | --file path) [--internal]
37
+ atli jira comment list PROJ-123 [--limit 50]
38
+ atli jira comment update PROJ-123 COMMENT_ID (--text "..." | --file path)
39
+ atli jira comment delete PROJ-123 COMMENT_ID [--yes]
40
+ atli jira transition PROJ-123 --to "Done" [--comment "..."] [--resolution Fixed] [--assignee alice]
41
+ atli jira project list
42
+ atli jira board list [--project PROJ]
43
+ atli jira release list --project PROJ
44
+ atli jira epic list --project PROJ
45
+ atli jira epic list EPIC-KEY
46
+ atli jira epic create --project PROJ --title "..." --name "epic-name"
47
+ atli jira epic add EPIC-KEY ISSUE-1 [ISSUE-2 ...]
48
+ atli jira epic remove ISSUE-1 [ISSUE-2 ...]
49
+ atli jira sprint list --board ID [--state active,future,closed]
50
+ atli jira sprint list --board ID --current|--prev|--next
51
+ atli jira sprint list SPRINT_ID
52
+ atli jira sprint create --board ID --name "..." [--start ISO] [--end ISO] [--goal "..."]
53
+ atli jira sprint update SPRINT_ID [--name "..."] [--start ISO] [--end ISO] [--goal "..."]
54
+ atli jira sprint start SPRINT_ID [--start ISO] [--end ISO]
55
+ atli jira sprint add SPRINT_ID ISSUE-1 [...]
56
+ atli jira sprint remove SPRINT_ID ISSUE-1 [...]
57
+ atli jira sprint close SPRINT_ID [--yes]
58
+ atli jira clone KEY [--title ...] [--replace OLD:NEW] [--assignee ...]
59
+ atli jira delete KEY [--cascade] [--yes]
60
+ atli jira worklog add KEY TIME [--comment ...]
61
+ atli jira worklog list KEY
62
+ atli jira worklog update KEY WORKLOG_ID TIME [--comment ...]
63
+ atli jira worklog delete KEY WORKLOG_ID [--yes]
64
+ atli jira watch add KEY [USERNAME]
65
+ atli jira watch list KEY
66
+ atli jira watch remove KEY [USERNAME]
67
+ atli jira bulk-create --file issues.json
68
+ # JSON array of {project, title, type, description?, assignee?, priority?, labels?, components?, parent?}
69
+ # or {issueUpdates: [{fields: {...}}]}
70
+ atli jira meta priorities
71
+ atli jira meta issue-types
72
+ atli jira meta statuses
73
+ atli jira meta resolutions
74
+ atli jira fields KEY # show all fields on an issue (includes custom field IDs)
75
+ atli jira editmeta KEY # show editable fields and their schemas
76
+ atli jira open [KEY]
77
+ ```
78
+
79
+ Top-level commands (not under `atli jira`):
80
+ ```
81
+ atli completion bash|zsh|fish
82
+ ```
83
+
84
+ All commands accept the global `--json` flag for machine-readable output, and `--profile <name>` to switch instances.
85
+
86
+ `--description` / comment `--text` are plain text (or `--file` / stdin). No GFM→wiki conversion — strings are passed through as-is. On `edit`/`create`, `--label` and `--component` **replace** the full list when provided. Unassign with assignee `x` or `none`. Classic epic-link custom fields: `--field customfield_XXXX=EPIC-KEY`.
87
+
88
+
89
+ ## Agile (Server/DC)
90
+
91
+ Classic epics: Epic Name / Epic Link custom fields are auto-discovered (`gh-epic-label` / `gh-epic-link`). Issue type name is `Epic`.
92
+
93
+ Sprints require a board id (`atli jira board list --project PROJ`). Prefer `--current` over guessing sprint ids. **Do not** close sprints without explicit user confirmation (`sprint close` prompts; `--json` requires `--yes`).
94
+
95
+ ## Issue links
96
+
97
+ `atli jira link INWARD OUTWARD TYPE` uses Jira link semantics (same as jira-cli): for type `Blocks`, OUTWARD **blocks** INWARD (INWARD *is blocked by* OUTWARD). Discover types via the instance if unsure (`Blocks`, `Relates`, `Duplicate`, …).
98
+
99
+ `--internal` on comments sets the Service Management property `sd.public.comment`; on plain Jira Software it may be ignored or rejected depending on plugins.
100
+
101
+ ## Pattern: create then transition
102
+
103
+ ```bash
104
+ KEY=$(atli --json jira create --project PROJ --type Story \
105
+ --title "feat: full-text search" \
106
+ --description "Search across all spaces" \
107
+ | jq -r .key)
108
+ echo "Created $KEY"
109
+ # ... do work ...
110
+ atli jira transition "$KEY" --to "In Progress"
111
+ # ... finish work ...
112
+ atli jira transition "$KEY" --to "Done"
113
+ ```
114
+
115
+ ## Pattern: list "what should I work on"
116
+
117
+ ```bash
118
+ atli jira list --project PROJ --assignee currentUser\(\) --status "Open"
119
+ ```
120
+
121
+ `currentUser()` is a JQL function — escape parens for the shell. Or use raw search:
122
+
123
+ ```bash
124
+ atli jira search "assignee = currentUser() AND status = Open ORDER BY priority DESC"
125
+ ```
126
+
127
+ ## Pattern: triage open bugs
128
+
129
+ ```bash
130
+ atli --json jira search 'project = PROJ AND type = Bug AND status = Open' \
131
+ | jq -r '.issues[] | "\(.key)\t\(.fields.priority.name)\t\(.fields.summary)"'
132
+ ```
133
+
134
+ ## Transitions: name vs ID
135
+
136
+ The CLI accepts the **name** (e.g. `--to "Done"`); internally it lists transitions for the issue and matches case-insensitively. Two failure modes:
137
+
138
+ 1. **Workflow doesn't allow the target from the current state.** The error lists what *is* available — show that to the user and ask which one they meant.
139
+ 2. **Custom workflow uses non-standard names** (e.g. "Code Review" vs "In Review"). When in doubt, attempt the transition and read the error message — it lists the available transition names.
140
+
141
+ ```bash
142
+ # This will fail with a message listing available transitions
143
+ atli jira transition PROJ-123 --to "Probably Wrong Name"
144
+ ```
145
+
146
+ ## JQL tips
147
+
148
+ - Quote strings with double quotes; reserved words (status, project) are unquoted.
149
+ - `project = PROJ AND status = "In Progress"`
150
+ - Use functions: `currentUser()`, `now()`, `startOfDay()`.
151
+ - Order: append `ORDER BY <field> ASC|DESC`.
152
+ - Custom fields: reference by ID (`cf[10001]`) — ask the user if they need a custom field filter and you don't know the ID.
153
+
154
+ ## Output shape (`--json`)
155
+
156
+ `view`:
157
+ ```json
158
+ {
159
+ "key": "PROJ-123",
160
+ "fields": {
161
+ "summary": "...",
162
+ "status": {"name": "In Progress"},
163
+ "assignee": {"displayName": "Alice"},
164
+ "issuetype": {"name": "Bug"}
165
+ }
166
+ }
167
+ ```
168
+
169
+ `search` / `list`:
170
+ ```json
171
+ {
172
+ "issues": [ {"key": "...", "fields": {...}}, ... ],
173
+ "total": 42
174
+ }
175
+ ```
176
+
177
+ `create`:
178
+ ```json
179
+ {"id": "10001", "key": "PROJ-101", "self": "https://..."}
180
+ ```
181
+
182
+ ## Limitations
183
+
184
+ - **Custom fields**: Use repeatable `--field KEY=VALUE` on `create` / `edit`. Values that parse as JSON arrays/objects (e.g. `--field 'fixVersions=[{"name":"1.0"}]'`) are deserialized before sending; other scalars pass through as strings.
185
+ - **Pagination**: `list` and `search` default to 20 results (`--limit` controls the page size). There is no built-in pagination helper; for large result sets, use `search` with raw JQL and manage `startAt` manually.
186
+ - **`list` builds JQL internally**: `atli jira list --project PROJ --status "Open"` constructs `project = PROJ AND status = "Open" ORDER BY updated DESC` under the hood. For complex filters, use `search` with raw JQL instead.
187
+
188
+ ## Constraints
189
+
190
+ 1. **When an operation is unsupported, explain why and provide evidence**
191
+ - If `atli jira` does not support an operation (e.g. bulk updates, dedicated sub-task create helper), **clearly tell the user the operation cannot be done via `atli jira`**, explain the specific reason (command does not exist, API limitation, outside CLI scope), and provide evidence (e.g. `atli jira --help` output, or reference the Atlassian REST API docs). Linking, epics/sprints, clone, worklog, and watch **are** supported.
192
+ - **Do not** unilaterally fall back to alternatives (e.g. raw `curl`, direct API calls, web UI actions). You may **suggest** alternatives, but must get user confirmation before executing.
193
+
194
+ 2. **Ask for confirmation when instructions are ambiguous**
195
+ - When parameters are missing or the intent is unclear, **stop and ask the user** rather than inferring intent or choosing defaults.
196
+ - Example: when asked to "link Jira issue XXX to YYY" without specifying the link type (blocks / is blocked by / relates to / duplicates), **first list the supported link types** for that instance (via `atli --json jira view XXX` or ask the user about their Jira config), then ask the user to confirm which link type to use.
197
+ - Before transitioning, show the available transition options and get user approval before executing `--to`.
198
+
199
+ 3. **Confirm before destructive operations**
200
+ - For any `atli jira` operation that modifies data (e.g. `edit`, `assign`, `transition`, `comment`), before executing:
201
+ 1. **Show the user the operation details** (target issue, change content, impact scope).
202
+ 2. **Get explicit user approval** before proceeding.
203
+ - For deletions or state transitions, do not auto-execute; wait for explicit user confirmation.
204
+
205
+ ## Anti-patterns
206
+
207
+ - ❌ `atli jira transition PROJ-1 --to done` without confirming with the user that "done" is the right terminal state for their workflow. Workflows often have "Closed", "Resolved", "Won't Do" etc.
208
+ - ❌ Adding a comment in lieu of a transition when the user really wants a status change. Comments don't move the ticket.
209
+ - ❌ Using `list` when the filter is complex; `search` with raw JQL is more powerful.