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.
@@ -0,0 +1,454 @@
1
+ """Agile / project meta Click commands registered under `atli jira`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import click
6
+
7
+ from atli.client import AtlassianAPIError
8
+ from atli.config import Config, ConfigError
9
+ from atli.jira.agile import AgileClient
10
+ from atli.output import emit_json, emit_kv, emit_table, fail
11
+
12
+
13
+ def _client(ctx: click.Context) -> AgileClient:
14
+ # Import here to avoid circular dependency
15
+ from atli.cli import _ensure_config
16
+ cfg = _ensure_config(ctx)
17
+ try:
18
+ cfg.require_jira()
19
+ except ConfigError as e:
20
+ fail(str(e))
21
+ return AgileClient(cfg.jira_url, cfg.jira_token)
22
+
23
+
24
+ def _name(node: dict | None) -> str:
25
+ return (node or {}).get("name", "")
26
+
27
+
28
+ def _person(node: dict | None) -> str:
29
+ if not node:
30
+ return ""
31
+ return node.get("displayName") or node.get("name") or node.get("emailAddress") or ""
32
+
33
+
34
+ def _emit_issue_table(ctx: click.Context, result: dict) -> None:
35
+ if ctx.obj["json"]:
36
+ emit_json(result)
37
+ return
38
+ rows = []
39
+ for issue in result.get("issues", []):
40
+ f = issue.get("fields", {})
41
+ rows.append(
42
+ [
43
+ issue.get("key", ""),
44
+ _name(f.get("issuetype")),
45
+ _name(f.get("status")),
46
+ _person(f.get("assignee")),
47
+ f.get("summary", ""),
48
+ ]
49
+ )
50
+ emit_table(["Key", "Type", "Status", "Assignee", "Title"], rows, json_mode=False)
51
+
52
+
53
+ def register(jira: click.Group) -> None:
54
+ """Attach P2 command groups to the existing ``jira`` group."""
55
+ jira.add_command(project)
56
+ jira.add_command(board)
57
+ jira.add_command(release)
58
+ jira.add_command(epic)
59
+ jira.add_command(sprint)
60
+
61
+
62
+ @click.group("project")
63
+ def project() -> None:
64
+ """List Jira projects."""
65
+
66
+
67
+ @project.command("list")
68
+ @click.pass_context
69
+ def project_list(ctx: click.Context) -> None:
70
+ """List projects visible to the current user."""
71
+ client = _client(ctx)
72
+ try:
73
+ projects = client.list_projects()
74
+ except AtlassianAPIError as e:
75
+ fail(str(e))
76
+ if ctx.obj["json"]:
77
+ emit_json(projects)
78
+ return
79
+ rows = [[p.get("key", ""), p.get("name", ""), p.get("projectTypeKey", "")] for p in projects]
80
+ emit_table(["Key", "Name", "Type"], rows, json_mode=False)
81
+
82
+
83
+ @click.group("board")
84
+ def board() -> None:
85
+ """List Agile boards."""
86
+
87
+
88
+ @board.command("list")
89
+ @click.option("--project", default=None, help="Filter by project key")
90
+ @click.option("--limit", default=50, show_default=True, help="Max results")
91
+ @click.pass_context
92
+ def board_list(ctx: click.Context, project: str | None, limit: int) -> None:
93
+ """List boards (optionally filtered by project)."""
94
+ client = _client(ctx)
95
+ try:
96
+ data = client.list_boards(project=project, max_results=limit)
97
+ except AtlassianAPIError as e:
98
+ fail(str(e))
99
+ if ctx.obj["json"]:
100
+ emit_json(data)
101
+ return
102
+ rows = [
103
+ [str(b.get("id", "")), b.get("name", ""), b.get("type", "")]
104
+ for b in data.get("values", [])
105
+ ]
106
+ emit_table(["ID", "Name", "Type"], rows, json_mode=False)
107
+
108
+
109
+ @click.group("release")
110
+ def release() -> None:
111
+ """List project versions (releases)."""
112
+
113
+
114
+ @release.command("list")
115
+ @click.option("--project", required=True, help="Project key")
116
+ @click.pass_context
117
+ def release_list(ctx: click.Context, project: str) -> None:
118
+ """List versions/releases for a project."""
119
+ client = _client(ctx)
120
+ try:
121
+ versions = client.list_versions(project)
122
+ except AtlassianAPIError as e:
123
+ fail(str(e))
124
+ if ctx.obj["json"]:
125
+ emit_json(versions)
126
+ return
127
+ rows = [
128
+ [
129
+ str(v.get("id", "")),
130
+ v.get("name", ""),
131
+ "yes" if v.get("released") else "no",
132
+ "yes" if v.get("archived") else "no",
133
+ ]
134
+ for v in versions
135
+ ]
136
+ emit_table(["ID", "Name", "Released", "Archived"], rows, json_mode=False)
137
+
138
+
139
+ @click.group("epic")
140
+ def epic() -> None:
141
+ """Manage epics and their issues."""
142
+
143
+
144
+ @epic.command("list")
145
+ @click.argument("epic_key", required=False, default=None)
146
+ @click.option("--project", default=None, help="Project key (required when listing epics)")
147
+ @click.option("--limit", default=50, show_default=True, help="Max results")
148
+ @click.pass_context
149
+ def epic_list(
150
+ ctx: click.Context,
151
+ epic_key: str | None,
152
+ project: str | None,
153
+ limit: int,
154
+ ) -> None:
155
+ """List epics in a project, or issues in an epic when KEY is given."""
156
+ client = _client(ctx)
157
+ try:
158
+ if epic_key:
159
+ result = client.epic_issues(epic_key, max_results=limit)
160
+ else:
161
+ if not project:
162
+ fail("--project is required when listing epics (omit KEY)")
163
+ result = client.list_epics(project, max_results=limit)
164
+ except AtlassianAPIError as e:
165
+ fail(str(e))
166
+ _emit_issue_table(ctx, result)
167
+
168
+
169
+ @epic.command("create")
170
+ @click.option("--project", required=True, help="Project key")
171
+ @click.option("--title", required=True, help="Epic summary")
172
+ @click.option("--name", required=True, help="Epic Name (GreenHopper field)")
173
+ @click.option("--description", default=None, help="Description (plain text)")
174
+ @click.pass_context
175
+ def epic_create(
176
+ ctx: click.Context,
177
+ project: str,
178
+ title: str,
179
+ name: str,
180
+ description: str | None,
181
+ ) -> None:
182
+ """Create an epic."""
183
+ client = _client(ctx)
184
+ try:
185
+ result = client.create_epic(
186
+ project=project, title=title, name=name, description=description
187
+ )
188
+ except AtlassianAPIError as e:
189
+ fail(str(e))
190
+ if ctx.obj["json"]:
191
+ emit_json(result)
192
+ return
193
+ emit_kv(
194
+ [("Epic", result.get("key", "")), ("Title", title), ("Name", name)],
195
+ json_mode=False,
196
+ )
197
+
198
+
199
+ @epic.command("add")
200
+ @click.argument("epic_key")
201
+ @click.argument("issues", nargs=-1, required=True)
202
+ @click.pass_context
203
+ def epic_add(ctx: click.Context, epic_key: str, issues: tuple[str, ...]) -> None:
204
+ """Add one or more issues to an epic."""
205
+ client = _client(ctx)
206
+ try:
207
+ client.epic_add_issues(epic_key, list(issues))
208
+ except AtlassianAPIError as e:
209
+ fail(str(e))
210
+ if ctx.obj["json"]:
211
+ emit_json({"epic": epic_key, "added": list(issues)})
212
+ return
213
+ emit_kv([("Epic", epic_key), ("Added", ", ".join(issues))], json_mode=False)
214
+
215
+
216
+ @epic.command("remove")
217
+ @click.argument("issues", nargs=-1, required=True)
218
+ @click.pass_context
219
+ def epic_remove(ctx: click.Context, issues: tuple[str, ...]) -> None:
220
+ """Remove issues from their epic (move to no epic)."""
221
+ client = _client(ctx)
222
+ try:
223
+ client.epic_remove_issues(list(issues))
224
+ except AtlassianAPIError as e:
225
+ fail(str(e))
226
+ if ctx.obj["json"]:
227
+ emit_json({"removed": list(issues)})
228
+ return
229
+ emit_kv([("Removed from epic", ", ".join(issues))], json_mode=False)
230
+
231
+
232
+ @click.group("sprint")
233
+ def sprint() -> None:
234
+ """Manage sprints and sprint issues."""
235
+
236
+
237
+ @sprint.command("list")
238
+ @click.argument("sprint_id", required=False, default=None)
239
+ @click.option("--board", "board_id", type=int, default=None, help="Board ID")
240
+ @click.option(
241
+ "--state",
242
+ default=None,
243
+ help="Comma-separated sprint states: active,future,closed",
244
+ )
245
+ @click.option("--current", is_flag=True, help="Show issues in the active sprint")
246
+ @click.option("--prev", is_flag=True, help="Show issues in the previous closed sprint")
247
+ @click.option("--next", "next_", is_flag=True, help="Show issues in the next future sprint")
248
+ @click.option("--limit", default=50, show_default=True, help="Max results")
249
+ @click.pass_context
250
+ def sprint_list(
251
+ ctx: click.Context,
252
+ sprint_id: str | None,
253
+ board_id: int | None,
254
+ state: str | None,
255
+ current: bool,
256
+ prev: bool,
257
+ next_: bool,
258
+ limit: int,
259
+ ) -> None:
260
+ """List sprints on a board, or issues in a sprint.
261
+
262
+ Modes:
263
+ - ``--board N`` → list sprints
264
+ - ``--board N --current|--prev|--next`` → issues in that sprint
265
+ - ``SPRINT_ID`` → issues in that sprint
266
+ """
267
+ client = _client(ctx)
268
+ try:
269
+ if sprint_id is not None:
270
+ result = client.sprint_issues(int(sprint_id), max_results=limit)
271
+ _emit_issue_table(ctx, result)
272
+ return
273
+
274
+ if board_id is None:
275
+ fail("--board is required when listing sprints (or pass SPRINT_ID)")
276
+
277
+ if current or prev or next_:
278
+ picked = client.pick_sprint(
279
+ board_id, current=current, prev=prev, next_=next_
280
+ )
281
+ sid = int(picked["id"])
282
+ result = client.sprint_issues(sid, max_results=limit)
283
+ if ctx.obj["json"]:
284
+ emit_json({"sprint": picked, "issues": result})
285
+ return
286
+ click.echo(f"Sprint {sid}: {picked.get('name', '')} ({picked.get('state', '')})")
287
+ _emit_issue_table(ctx, result)
288
+ return
289
+
290
+ data = client.list_sprints(board_id, state=state, max_results=limit)
291
+ except AtlassianAPIError as e:
292
+ fail(str(e))
293
+
294
+ if ctx.obj["json"]:
295
+ emit_json(data)
296
+ return
297
+ rows = [
298
+ [
299
+ str(s.get("id", "")),
300
+ s.get("name", ""),
301
+ s.get("state", ""),
302
+ (s.get("startDate") or "")[:10],
303
+ (s.get("endDate") or "")[:10],
304
+ ]
305
+ for s in data.get("values", [])
306
+ ]
307
+ emit_table(["ID", "Name", "State", "Start", "End"], rows, json_mode=False)
308
+
309
+
310
+ @sprint.command("add")
311
+ @click.argument("sprint_id", type=int)
312
+ @click.argument("issues", nargs=-1, required=True)
313
+ @click.pass_context
314
+ def sprint_add(ctx: click.Context, sprint_id: int, issues: tuple[str, ...]) -> None:
315
+ """Add issues to a sprint."""
316
+ client = _client(ctx)
317
+ try:
318
+ client.sprint_add_issues(sprint_id, list(issues))
319
+ except AtlassianAPIError as e:
320
+ fail(str(e))
321
+ if ctx.obj["json"]:
322
+ emit_json({"sprint": sprint_id, "added": list(issues)})
323
+ return
324
+ emit_kv(
325
+ [("Sprint", str(sprint_id)), ("Added", ", ".join(issues))],
326
+ json_mode=False,
327
+ )
328
+
329
+
330
+ @sprint.command("close")
331
+ @click.argument("sprint_id", type=int)
332
+ @click.option("--yes", is_flag=True, help="Confirm close (required with --json)")
333
+ @click.pass_context
334
+ def sprint_close(ctx: click.Context, sprint_id: int, yes: bool) -> None:
335
+ """Close a sprint (moves incomplete issues per board config)."""
336
+ if ctx.obj["json"] and not yes:
337
+ fail("--yes is required with --json for sprint close")
338
+ if not yes and not ctx.obj["json"]:
339
+ click.confirm(f"Close sprint {sprint_id}?", abort=True)
340
+ client = _client(ctx)
341
+ try:
342
+ result = client.close_sprint(sprint_id)
343
+ except AtlassianAPIError as e:
344
+ fail(str(e))
345
+ if ctx.obj["json"]:
346
+ emit_json(result or {"id": sprint_id, "state": "closed"})
347
+ return
348
+ emit_kv([("Sprint", str(sprint_id)), ("State", "closed")], json_mode=False)
349
+
350
+
351
+ @sprint.command("create")
352
+ @click.option("--board", "board_id", type=int, required=True, help="Board ID")
353
+ @click.option("--name", required=True, help="Sprint name")
354
+ @click.option("--start", "start_date", default=None, help="Start date (ISO8601)")
355
+ @click.option("--end", "end_date", default=None, help="End date (ISO8601)")
356
+ @click.option("--goal", default=None, help="Sprint goal")
357
+ @click.pass_context
358
+ def sprint_create(
359
+ ctx: click.Context,
360
+ board_id: int,
361
+ name: str,
362
+ start_date: str | None,
363
+ end_date: str | None,
364
+ goal: str | None,
365
+ ) -> None:
366
+ """Create a new sprint on a board."""
367
+ client = _client(ctx)
368
+ try:
369
+ result = client.create_sprint(
370
+ board_id, name, start_date=start_date, end_date=end_date, goal=goal
371
+ )
372
+ except AtlassianAPIError as e:
373
+ fail(str(e))
374
+ if ctx.obj["json"]:
375
+ emit_json(result)
376
+ return
377
+ emit_kv(
378
+ [
379
+ ("Sprint ID", str(result.get("id", ""))),
380
+ ("Name", result.get("name", name)),
381
+ ("State", result.get("state", "future")),
382
+ ],
383
+ json_mode=False,
384
+ )
385
+
386
+
387
+ @sprint.command("update")
388
+ @click.argument("sprint_id", type=int)
389
+ @click.option("--name", default=None, help="New sprint name")
390
+ @click.option("--start", "start_date", default=None, help="Start date (ISO8601)")
391
+ @click.option("--end", "end_date", default=None, help="End date (ISO8601)")
392
+ @click.option("--goal", default=None, help="Sprint goal")
393
+ @click.pass_context
394
+ def sprint_update(
395
+ ctx: click.Context,
396
+ sprint_id: int,
397
+ name: str | None,
398
+ start_date: str | None,
399
+ end_date: str | None,
400
+ goal: str | None,
401
+ ) -> None:
402
+ """Update sprint name, dates, or goal."""
403
+ client = _client(ctx)
404
+ try:
405
+ result = client.update_sprint(
406
+ sprint_id, name=name, start_date=start_date, end_date=end_date, goal=goal
407
+ )
408
+ except AtlassianAPIError as e:
409
+ fail(str(e))
410
+ if ctx.obj["json"]:
411
+ emit_json(result)
412
+ return
413
+ emit_kv([("Sprint", str(sprint_id)), ("Action", "updated")], json_mode=False)
414
+
415
+
416
+ @sprint.command("start")
417
+ @click.argument("sprint_id", type=int)
418
+ @click.option("--start", "start_date", default=None, help="Start date (ISO8601, defaults to now)")
419
+ @click.option("--end", "end_date", default=None, help="End date (ISO8601)")
420
+ @click.pass_context
421
+ def sprint_start(
422
+ ctx: click.Context, sprint_id: int, start_date: str | None, end_date: str | None
423
+ ) -> None:
424
+ """Start a sprint (move from future → active)."""
425
+ client = _client(ctx)
426
+ try:
427
+ result = client.start_sprint(sprint_id, start_date=start_date, end_date=end_date)
428
+ except AtlassianAPIError as e:
429
+ fail(str(e))
430
+ if ctx.obj["json"]:
431
+ emit_json(result)
432
+ return
433
+ emit_kv([("Sprint", str(sprint_id)), ("State", "active")], json_mode=False)
434
+
435
+
436
+ @sprint.command("remove")
437
+ @click.argument("sprint_id", type=int)
438
+ @click.argument("issues", nargs=-1, required=True)
439
+ @click.pass_context
440
+ def sprint_remove(ctx: click.Context, sprint_id: int, issues: tuple[str, ...]) -> None:
441
+ """Remove issues from a sprint (move back to backlog)."""
442
+ client = _client(ctx)
443
+ try:
444
+ client.sprint_remove_issues(sprint_id, list(issues))
445
+ except AtlassianAPIError as e:
446
+ fail(str(e))
447
+ if ctx.obj["json"]:
448
+ emit_json({"sprint_id": sprint_id, "removed": list(issues)})
449
+ return
450
+ emit_kv(
451
+ [("Sprint", str(sprint_id)), ("Removed", ", ".join(issues))],
452
+ json_mode=False,
453
+ )
454
+
atli/jira/body.py ADDED
@@ -0,0 +1,36 @@
1
+ """Resolve issue description / comment body from flag, file, or stdin."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from pathlib import Path
7
+
8
+
9
+ def resolve_text(
10
+ *,
11
+ text: str | None = None,
12
+ file: str | None = None,
13
+ allow_stdin: bool = True,
14
+ ) -> str | None:
15
+ """Priority: explicit ``text`` > file contents > stdin if not a TTY.
16
+
17
+ Returns ``None`` when nothing is provided. Raises ``ValueError`` when a
18
+ file path is given but cannot be read, or when the file exceeds 10 MB.
19
+ """
20
+ if text is not None:
21
+ return text
22
+ if file is not None:
23
+ path = Path(file)
24
+ # Validate file size (10 MB limit for issue body)
25
+ try:
26
+ file_size = path.stat().st_size
27
+ if file_size > 10 * 1024 * 1024:
28
+ raise ValueError(f"body file too large: {file_size} bytes (max 10 MB)")
29
+ return path.read_text(encoding="utf-8")
30
+ except OSError as e:
31
+ raise ValueError(f"cannot read body file {file!r}: {e}") from e
32
+ if allow_stdin and not sys.stdin.isatty():
33
+ data = sys.stdin.read()
34
+ if data:
35
+ return data
36
+ return None