hoja-cli 0.21.4__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.
Files changed (107) hide show
  1. VERSION +1 -0
  2. google_workspace/__init__.py +19 -0
  3. google_workspace/client.py +253 -0
  4. google_workspace/config.py +39 -0
  5. google_workspace/errors.py +19 -0
  6. google_workspace/mcp_server.py +100 -0
  7. google_workspace/oauth.py +131 -0
  8. google_workspace/principal.py +83 -0
  9. google_workspace/py.typed +0 -0
  10. google_workspace/tools.py +64 -0
  11. google_workspace/writes.py +44 -0
  12. hoja/__init__.py +29 -0
  13. hoja/__main__.py +6 -0
  14. hoja/auth.py +42 -0
  15. hoja/cli.py +161 -0
  16. hoja/cli_state.py +55 -0
  17. hoja/client.py +268 -0
  18. hoja/commands/__init__.py +4 -0
  19. hoja/commands/auth_cmd.py +271 -0
  20. hoja/commands/comment.py +149 -0
  21. hoja/commands/cycle.py +75 -0
  22. hoja/commands/init.py +108 -0
  23. hoja/commands/issue.py +398 -0
  24. hoja/commands/label.py +163 -0
  25. hoja/commands/memory.py +240 -0
  26. hoja/commands/project.py +56 -0
  27. hoja/commands/raw.py +50 -0
  28. hoja/commands/team.py +102 -0
  29. hoja/commands/update.py +162 -0
  30. hoja/config.py +362 -0
  31. hoja/errors.py +107 -0
  32. hoja/filters.py +150 -0
  33. hoja/graphql/__init__.py +5 -0
  34. hoja/graphql/fragments.py +138 -0
  35. hoja/graphql/mutations.py +160 -0
  36. hoja/graphql/queries.py +245 -0
  37. hoja/mcp/__init__.py +27 -0
  38. hoja/mcp/content.py +151 -0
  39. hoja/mcp/prompts.py +298 -0
  40. hoja/mcp/resources.py +213 -0
  41. hoja/mcp/server.py +189 -0
  42. hoja/memory_board.py +370 -0
  43. hoja/models/__init__.py +37 -0
  44. hoja/models/base.py +64 -0
  45. hoja/models/cycle.py +32 -0
  46. hoja/models/enums.py +62 -0
  47. hoja/models/issue.py +99 -0
  48. hoja/models/label.py +17 -0
  49. hoja/models/project.py +60 -0
  50. hoja/models/team.py +31 -0
  51. hoja/models/user.py +32 -0
  52. hoja/models/workflow.py +65 -0
  53. hoja/output.py +410 -0
  54. hoja/skill_content/commands.md +222 -0
  55. hoja/skill_content/examples.md +193 -0
  56. hoja/skill_content/filters.md +101 -0
  57. hoja/skill_content/output-formats.md +92 -0
  58. hoja/skill_content/overview.md +123 -0
  59. hoja/skill_content/workflows.md +174 -0
  60. hoja_cli-0.21.4.dist-info/METADATA +279 -0
  61. hoja_cli-0.21.4.dist-info/RECORD +107 -0
  62. hoja_cli-0.21.4.dist-info/WHEEL +4 -0
  63. hoja_cli-0.21.4.dist-info/entry_points.txt +4 -0
  64. hoja_cli-0.21.4.dist-info/licenses/LICENSE +21 -0
  65. hoja_server/README.md +135 -0
  66. hoja_server/__init__.py +11 -0
  67. hoja_server/abac.py +116 -0
  68. hoja_server/agent_chat.py +280 -0
  69. hoja_server/agent_conversations.py +91 -0
  70. hoja_server/agent_durable.py +332 -0
  71. hoja_server/agent_prompt.py +117 -0
  72. hoja_server/agent_threads.py +96 -0
  73. hoja_server/agent_uploads.py +60 -0
  74. hoja_server/app.py +2189 -0
  75. hoja_server/cadence.py +231 -0
  76. hoja_server/cli.py +191 -0
  77. hoja_server/cloudflare_realtime.py +110 -0
  78. hoja_server/comment_policy.py +70 -0
  79. hoja_server/connector_actions.py +119 -0
  80. hoja_server/connectors_api.py +375 -0
  81. hoja_server/db.py +1816 -0
  82. hoja_server/denials.py +18 -0
  83. hoja_server/deployment.py +28 -0
  84. hoja_server/email_adapter.py +94 -0
  85. hoja_server/google_login.py +217 -0
  86. hoja_server/google_oidc.py +342 -0
  87. hoja_server/identity_transfer.py +210 -0
  88. hoja_server/mcp_oauth.py +623 -0
  89. hoja_server/mcp_tools.py +579 -0
  90. hoja_server/meeting_policy.py +179 -0
  91. hoja_server/meetings.py +1332 -0
  92. hoja_server/meetings_api.py +909 -0
  93. hoja_server/model_providers.py +205 -0
  94. hoja_server/realtime.py +690 -0
  95. hoja_server/resolvers.py +1281 -0
  96. hoja_server/schema.graphql +477 -0
  97. hoja_server/schema_sdl.py +8 -0
  98. hoja_server/secrets_box.py +39 -0
  99. hoja_server/signup_config.py +292 -0
  100. hoja_server/signup_gate.py +393 -0
  101. hoja_server/signup_policy.py +97 -0
  102. hoja_server/signup_store.py +577 -0
  103. hoja_server/store.py +2179 -0
  104. hoja_server/sync.py +249 -0
  105. hoja_server/tenant_context.py +131 -0
  106. hoja_server/turnstile.py +81 -0
  107. hoja_server/writer.py +1262 -0
hoja/models/project.py ADDED
@@ -0,0 +1,60 @@
1
+ """Project model.
2
+
3
+ A Linear project groups related issues across one or more teams toward a goal
4
+ (e.g. "Q2 Roadmap", "Auth Refactor"). Has lead, members, target date, and progress.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from datetime import date
10
+ from enum import Enum
11
+
12
+ from pydantic import Field
13
+
14
+ from hoja.models.base import Timestamped
15
+ from hoja.models.user import User
16
+
17
+
18
+ class ProjectState(str, Enum):
19
+ """Linear project lifecycle states."""
20
+
21
+ BACKLOG = "backlog"
22
+ PLANNED = "planned"
23
+ STARTED = "started"
24
+ PAUSED = "paused"
25
+ COMPLETED = "completed"
26
+ CANCELED = "canceled"
27
+
28
+
29
+ class Project(Timestamped):
30
+ """A Linear project."""
31
+
32
+ id: str
33
+ name: str
34
+ description: str | None = None
35
+ slug_id: str | None = Field(alias="slugId", default=None)
36
+ icon: str | None = None
37
+ color: str | None = None
38
+ state: ProjectState | str | None = None
39
+ progress: float | None = None # 0.0 - 1.0
40
+
41
+ # Relations
42
+ lead: User | None = None
43
+ creator: User | None = None
44
+ members: list[User] = Field(default_factory=list)
45
+
46
+ # Dates
47
+ start_date: date | None = Field(alias="startDate", default=None)
48
+ target_date: date | None = Field(alias="targetDate", default=None)
49
+ started_at: str | None = Field(alias="startedAt", default=None)
50
+ completed_at: str | None = Field(alias="completedAt", default=None)
51
+ canceled_at: str | None = Field(alias="canceledAt", default=None)
52
+
53
+ # Metadata
54
+ url: str | None = None
55
+ issue_count_history: list[int] | None = Field(
56
+ alias="issueCountHistory", default=None
57
+ )
58
+ completed_issue_count_history: list[int] | None = Field(
59
+ alias="completedIssueCountHistory", default=None
60
+ )
hoja/models/team.py ADDED
@@ -0,0 +1,31 @@
1
+ """Team model (Linear's Team entity)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pydantic import Field
6
+
7
+ from hoja.models.base import Timestamped
8
+
9
+
10
+ class Team(Timestamped):
11
+ """A Linear team.
12
+
13
+ GraphQL: type Team implements Node
14
+ Notes:
15
+ - `key` is the short identifier (e.g. "ENG") used in issue IDs like ENG-123.
16
+ - Teams own issues, workflows, cycles, and labels.
17
+ """
18
+
19
+ id: str
20
+ name: str
21
+ key: str
22
+ description: str | None = None
23
+ color: str | None = None
24
+ icon: str | None = None
25
+ visibility: str = "public"
26
+ parent_team_id: str | None = Field(alias="parentTeamId", default=None)
27
+ timezone: str | None = None
28
+
29
+ # Counts (often included for at-a-glance views)
30
+ issue_count: int | None = Field(alias="issueCount", default=None)
31
+ member_count: int | None = Field(alias="memberCount", default=None)
hoja/models/user.py ADDED
@@ -0,0 +1,32 @@
1
+ """User model (Linear's User entity)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pydantic import Field
6
+
7
+ from hoja.models.base import Timestamped
8
+
9
+
10
+ class User(Timestamped):
11
+ """A Linear user (member of the workspace).
12
+
13
+ GraphQL: type User implements Node
14
+ """
15
+
16
+ id: str
17
+ name: str
18
+ display_name: str | None = Field(alias="displayName", default=None)
19
+ email: str | None = None
20
+ active: bool = True
21
+ admin: bool = False
22
+ is_me: bool = Field(alias="isMe", default=False)
23
+ avatar_url: str | None = Field(alias="avatarUrl", default=None)
24
+ url: str | None = None
25
+ timezone: str | None = None
26
+ status_emoji: str | None = Field(alias="statusEmoji", default=None)
27
+ status_label: str | None = Field(alias="statusLabel", default=None)
28
+
29
+ @property
30
+ def short(self) -> str:
31
+ """Best one-line identifier for display."""
32
+ return self.display_name or self.name or self.email or self.id
@@ -0,0 +1,65 @@
1
+ """Workflow state model.
2
+
3
+ A workflow state is a team-defined column like "Todo", "In Progress", "Done".
4
+ Each maps to a broader StateType (backlog / started / completed / etc.).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from enum import Enum
10
+
11
+ from pydantic import Field, field_validator
12
+
13
+ from hoja.models.base import Timestamped
14
+
15
+
16
+ class WorkflowStateType(str, Enum):
17
+ """Linear's documented workflow state categories.
18
+
19
+ Linear can return additional, undocumented state types (e.g. ``"duplicate"``)
20
+ for teams that enable extra workflow behaviors. Those values must NOT crash
21
+ the CLI — see ``WorkflowState.type`` for how unknown types are preserved.
22
+ """
23
+
24
+ TRIAGE = "triage"
25
+ BACKLOG = "backlog"
26
+ UNSTARTED = "unstarted"
27
+ STARTED = "started"
28
+ COMPLETED = "completed"
29
+ CANCELED = "canceled"
30
+
31
+ @classmethod
32
+ def coerce(cls, value: object) -> "WorkflowStateType | str":
33
+ """Return the enum member for known types, else the raw string.
34
+
35
+ Both branches are ``str`` subclasses, so downstream formatting,
36
+ equality checks and JSON/YAML serialization behave identically.
37
+ """
38
+ if isinstance(value, cls):
39
+ return value
40
+ if isinstance(value, str):
41
+ try:
42
+ return cls(value)
43
+ except ValueError:
44
+ return value
45
+ return str(value)
46
+
47
+
48
+ class WorkflowState(Timestamped):
49
+ """A team's workflow state (e.g. 'Todo', 'In Progress', 'Done')."""
50
+
51
+ id: str
52
+ name: str
53
+ color: str | None = None
54
+ description: str | None = None
55
+ position: float | None = None
56
+ # Smart union: Linear may emit state types outside the documented enum
57
+ # (e.g. "duplicate"). Keep those as a plain string instead of raising a
58
+ # pydantic ValidationError that would break `team states` / `issue state`.
59
+ type: WorkflowStateType | str
60
+ team_id: str | None = Field(alias="teamId", default=None)
61
+
62
+ @field_validator("type", mode="before")
63
+ @classmethod
64
+ def _coerce_type(cls, v: object) -> "WorkflowStateType | str":
65
+ return WorkflowStateType.coerce(v)
hoja/output.py ADDED
@@ -0,0 +1,410 @@
1
+ """Output formatters.
2
+
3
+ One canonical render() entry point dispatches on OutputFormat.
4
+ Each formatter takes a Pydantic model (or list thereof) and returns a string.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ from typing import Any, Iterable
11
+
12
+ from pydantic import BaseModel
13
+ from rich.console import Console
14
+ from rich.table import Table
15
+
16
+ from hoja.models.enums import OutputFormat
17
+ from hoja.models.issue import Issue
18
+ from hoja.models.project import Project
19
+ from hoja.models.team import Team
20
+ from hoja.models.user import User
21
+ from hoja.models.workflow import WorkflowState
22
+
23
+ console = Console()
24
+ err_console = Console(stderr=True)
25
+
26
+
27
+ def render(
28
+ payload: Any,
29
+ *,
30
+ fmt: OutputFormat = OutputFormat.HUMAN,
31
+ title: str | None = None,
32
+ ) -> None:
33
+ """Top-level dispatcher. Writes to stdout."""
34
+ if fmt is OutputFormat.JSON:
35
+ print(_to_json(payload))
36
+ elif fmt is OutputFormat.IDS:
37
+ print(_to_ids(payload))
38
+ elif fmt is OutputFormat.PLAIN:
39
+ print(_to_plain(payload))
40
+ elif fmt is OutputFormat.YAML:
41
+ print(_to_yaml(payload))
42
+ elif fmt is OutputFormat.MARKDOWN:
43
+ print(_to_markdown(payload, title=title))
44
+ else:
45
+ _to_human(payload, title=title)
46
+
47
+
48
+ # ---------------------------------------------------------------------------
49
+ # JSON
50
+ # ---------------------------------------------------------------------------
51
+
52
+ def _to_json(payload: Any) -> str:
53
+ return json.dumps(_jsonify(payload), indent=2, default=str)
54
+
55
+
56
+ def _jsonify(payload: Any) -> Any:
57
+ if isinstance(payload, BaseModel):
58
+ # Drop null/empty fields to keep JSON tight and LLM-friendly
59
+ return _prune(payload.model_dump(mode="json", by_alias=False))
60
+ if isinstance(payload, list):
61
+ return [_jsonify(item) for item in payload]
62
+ if isinstance(payload, dict):
63
+ return {k: _jsonify(v) for k, v in payload.items()}
64
+ return payload
65
+
66
+
67
+ def _prune(d: Any) -> Any:
68
+ """Recursively drop null, empty-string, empty-list, empty-dict fields."""
69
+ if isinstance(d, dict):
70
+ out = {}
71
+ for k, v in d.items():
72
+ pv = _prune(v)
73
+ if pv is None or pv == "" or pv == [] or pv == {}:
74
+ continue
75
+ out[k] = pv
76
+ return out
77
+ if isinstance(d, list):
78
+ return [_prune(item) for item in d]
79
+ return d
80
+
81
+
82
+ # ---------------------------------------------------------------------------
83
+ # IDs (one per line)
84
+ # ---------------------------------------------------------------------------
85
+
86
+ def _to_ids(payload: Any) -> str:
87
+ items = _to_list(payload)
88
+ ids: list[str] = []
89
+ for item in items:
90
+ if hasattr(item, "identifier") and item.identifier:
91
+ ids.append(item.identifier)
92
+ elif hasattr(item, "id"):
93
+ ids.append(item.id)
94
+ elif isinstance(item, dict):
95
+ ids.append(item.get("identifier") or item.get("id", ""))
96
+ return "\n".join(i for i in ids if i)
97
+
98
+
99
+ # ---------------------------------------------------------------------------
100
+ # Plain (TSV)
101
+ # ---------------------------------------------------------------------------
102
+
103
+ def _to_plain(payload: Any) -> str:
104
+ items = _to_list(payload)
105
+ if not items:
106
+ return ""
107
+ rows: list[str] = []
108
+ first = items[0]
109
+ if isinstance(first, Issue):
110
+ for it in items:
111
+ rows.append(
112
+ "\t".join(
113
+ [
114
+ it.identifier,
115
+ it.state_name,
116
+ it.assignee_name,
117
+ _safe_priority_label(it),
118
+ it.title,
119
+ ]
120
+ )
121
+ )
122
+ elif isinstance(first, Team):
123
+ for it in items:
124
+ rows.append(f"{it.key}\t{it.name}\t{it.id}")
125
+ elif isinstance(first, Project):
126
+ for it in items:
127
+ rows.append(f"{it.id}\t{it.name}\t{it.state or '-'}\t{int((it.progress or 0)*100)}%")
128
+ elif isinstance(first, User):
129
+ for it in items:
130
+ rows.append(f"{it.id}\t{it.name}\t{it.email or '-'}")
131
+ else:
132
+ for it in items:
133
+ rows.append(str(it))
134
+ return "\n".join(rows)
135
+
136
+
137
+ # ---------------------------------------------------------------------------
138
+ # YAML (minimal, no external dep — we hand-roll a safe subset)
139
+ # ---------------------------------------------------------------------------
140
+
141
+ def _to_yaml(payload: Any) -> str:
142
+ """Minimal YAML emitter. Good enough for inspecting Linear objects."""
143
+ obj = _jsonify(payload)
144
+ return _yaml_dump(obj, 0).rstrip()
145
+
146
+
147
+ def _yaml_dump(obj: Any, indent: int) -> str:
148
+ pad = " " * indent
149
+ if isinstance(obj, dict):
150
+ if not obj:
151
+ return f"{pad}{{}}\n"
152
+ out = ""
153
+ for k, v in obj.items():
154
+ if isinstance(v, dict) and v:
155
+ out += f"{pad}{k}:\n{_yaml_dump(v, indent + 1)}"
156
+ elif isinstance(v, list) and v:
157
+ out += f"{pad}{k}:\n{_yaml_dump(v, indent + 1)}"
158
+ else:
159
+ out += f"{pad}{k}: {_yaml_scalar(v)}\n"
160
+ return out
161
+ if isinstance(obj, list):
162
+ if not obj:
163
+ return f"{pad}[]\n"
164
+ out = ""
165
+ for item in obj:
166
+ if isinstance(item, dict):
167
+ inner = _yaml_dump(item, indent + 1).splitlines()
168
+ if not inner:
169
+ out += f"{pad}- {{}}\n"
170
+ continue
171
+ first = inner[0].lstrip()
172
+ out += f"{pad}- {first}\n"
173
+ for line in inner[1:]:
174
+ # add 2 spaces (for the '- ' lead-in) plus existing indent
175
+ out += f"{pad} {line[(indent + 1) * 2:]}\n"
176
+ elif isinstance(item, list):
177
+ inner = _yaml_dump(item, indent + 1).splitlines()
178
+ out += f"{pad}-\n"
179
+ for line in inner:
180
+ out += f"{line}\n"
181
+ else:
182
+ out += f"{pad}- {_yaml_scalar(item)}\n"
183
+ return out
184
+ return f"{pad}{_yaml_scalar(obj)}\n"
185
+
186
+
187
+ def _yaml_scalar(v: Any) -> str:
188
+ if v is None:
189
+ return "null"
190
+ if isinstance(v, bool):
191
+ return "true" if v else "false"
192
+ if isinstance(v, (int, float)):
193
+ return str(v)
194
+ s = str(v)
195
+ if any(c in s for c in ":#\n\"'") or s.strip() != s:
196
+ # Quote-and-escape
197
+ return json.dumps(s)
198
+ return s
199
+
200
+
201
+ # ---------------------------------------------------------------------------
202
+ # Markdown
203
+ # ---------------------------------------------------------------------------
204
+
205
+ def _to_markdown(payload: Any, *, title: str | None = None) -> str:
206
+ items = _to_list(payload)
207
+ out: list[str] = []
208
+ if title:
209
+ out.append(f"# {title}")
210
+ out.append("")
211
+ if not items:
212
+ out.append("_No results._")
213
+ return "\n".join(out)
214
+
215
+ first = items[0]
216
+ if isinstance(first, Issue):
217
+ out.append("| ID | State | Priority | Assignee | Title |")
218
+ out.append("|---|---|---|---|---|")
219
+ for it in items:
220
+ out.append(
221
+ f"| {it.identifier} | {it.state_name} | "
222
+ f"{_safe_priority_label(it)} | {it.assignee_name} | "
223
+ f"{_md_escape(it.title)} |"
224
+ )
225
+ elif isinstance(first, Team):
226
+ out.append("| Key | Name | ID |")
227
+ out.append("|---|---|---|")
228
+ for it in items:
229
+ out.append(f"| {it.key} | {_md_escape(it.name)} | `{it.id}` |")
230
+ elif isinstance(first, Project):
231
+ out.append("| Name | State | Progress | Target Date |")
232
+ out.append("|---|---|---|---|")
233
+ for it in items:
234
+ out.append(
235
+ f"| {_md_escape(it.name)} | {it.state or '—'} | "
236
+ f"{int((it.progress or 0) * 100)}% | "
237
+ f"{it.target_date or '—'} |"
238
+ )
239
+ else:
240
+ for it in items:
241
+ out.append(f"- {it}")
242
+ return "\n".join(out)
243
+
244
+
245
+ def _md_escape(s: str | None) -> str:
246
+ if not s:
247
+ return ""
248
+ return s.replace("|", "\\|").replace("\n", " ")
249
+
250
+
251
+ # ---------------------------------------------------------------------------
252
+ # Human (Rich tables)
253
+ # ---------------------------------------------------------------------------
254
+
255
+ def _to_human(payload: Any, *, title: str | None = None) -> None:
256
+ # Single object: render as key-value table
257
+ if isinstance(payload, BaseModel):
258
+ _render_object(payload, title=title)
259
+ return
260
+ items = _to_list(payload)
261
+ if not items:
262
+ console.print("[dim]No results.[/]")
263
+ return
264
+ first = items[0]
265
+ if isinstance(first, Issue):
266
+ _render_issues(items, title=title)
267
+ elif isinstance(first, Team):
268
+ _render_teams(items, title=title)
269
+ elif isinstance(first, Project):
270
+ _render_projects(items, title=title)
271
+ elif isinstance(first, User):
272
+ _render_users(items, title=title)
273
+ elif isinstance(first, WorkflowState):
274
+ _render_states(items, title=title)
275
+ else:
276
+ # Generic Pydantic list — show as a compact name/id table
277
+ if isinstance(first, BaseModel):
278
+ _render_generic(items, title=title)
279
+ else:
280
+ for item in items:
281
+ console.print(item)
282
+
283
+
284
+ def _render_object(obj: BaseModel, *, title: str | None = None) -> None:
285
+ table = Table(title=title or obj.__class__.__name__, show_header=False)
286
+ table.add_column("Field", style="bold cyan")
287
+ table.add_column("Value")
288
+ for k, v in obj.model_dump(mode="json", by_alias=False).items():
289
+ if v is None or v == "" or v == [] or v == {}:
290
+ continue
291
+ if isinstance(v, (dict, list)):
292
+ v = json.dumps(v, indent=2, default=str)
293
+ table.add_row(str(k), str(v))
294
+ console.print(table)
295
+
296
+
297
+ def _render_issues(items: list[Issue], *, title: str | None = None) -> None:
298
+ table = Table(title=title or f"Issues ({len(items)})")
299
+ table.add_column("ID", style="bold cyan")
300
+ table.add_column("State")
301
+ table.add_column("Pri")
302
+ table.add_column("Assignee")
303
+ table.add_column("Title")
304
+ for it in items:
305
+ table.add_row(
306
+ it.identifier,
307
+ it.state_name,
308
+ _safe_priority_label(it),
309
+ it.assignee_name,
310
+ it.title,
311
+ )
312
+ console.print(table)
313
+
314
+
315
+ def _render_teams(items: list[Team], *, title: str | None = None) -> None:
316
+ table = Table(title=title or f"Teams ({len(items)})")
317
+ table.add_column("Key", style="bold cyan")
318
+ table.add_column("Name")
319
+ table.add_column("ID", style="dim")
320
+ for it in items:
321
+ table.add_row(it.key, it.name, it.id)
322
+ console.print(table)
323
+
324
+
325
+ def _render_projects(items: list[Project], *, title: str | None = None) -> None:
326
+ table = Table(title=title or f"Projects ({len(items)})")
327
+ table.add_column("Name", style="bold cyan")
328
+ table.add_column("State")
329
+ table.add_column("Progress")
330
+ table.add_column("Target")
331
+ for it in items:
332
+ table.add_row(
333
+ it.name,
334
+ str(it.state or "—"),
335
+ f"{int((it.progress or 0) * 100)}%",
336
+ str(it.target_date or "—"),
337
+ )
338
+ console.print(table)
339
+
340
+
341
+ def _render_users(items: list[User], *, title: str | None = None) -> None:
342
+ table = Table(title=title or f"Users ({len(items)})")
343
+ table.add_column("Name", style="bold cyan")
344
+ table.add_column("Email")
345
+ table.add_column("ID", style="dim")
346
+ for it in items:
347
+ table.add_row(it.short, it.email or "—", it.id)
348
+ console.print(table)
349
+
350
+
351
+ def _render_states(items: list[WorkflowState], *, title: str | None = None) -> None:
352
+ table = Table(title=title or f"Workflow States ({len(items)})")
353
+ table.add_column("Name", style="bold cyan")
354
+ table.add_column("Type")
355
+ table.add_column("Position", justify="right")
356
+ table.add_column("Color")
357
+ table.add_column("ID", style="dim")
358
+ for it in items:
359
+ table.add_row(
360
+ it.name,
361
+ it.type.value if hasattr(it.type, "value") else str(it.type),
362
+ f"{it.position:.0f}" if it.position is not None else "—",
363
+ it.color or "—",
364
+ it.id,
365
+ )
366
+ console.print(table)
367
+
368
+
369
+ def _render_generic(items: list, *, title: str | None = None) -> None:
370
+ """Fallback table for any Pydantic model list — show id/name/key if present."""
371
+ table = Table(title=title or f"Results ({len(items)})")
372
+ sample = items[0].model_dump(mode="json", by_alias=False)
373
+ # Pick the most useful 3-4 fields
374
+ preferred = ["identifier", "key", "name", "title", "state", "id"]
375
+ cols = [k for k in preferred if k in sample][:4]
376
+ if not cols:
377
+ cols = list(sample.keys())[:4]
378
+ for c in cols:
379
+ table.add_column(c, style="bold cyan" if c == cols[0] else "")
380
+ for it in items:
381
+ d = it.model_dump(mode="json", by_alias=False)
382
+ table.add_row(*[str(d.get(c, "—") or "—") for c in cols])
383
+ console.print(table)
384
+
385
+
386
+ # ---------------------------------------------------------------------------
387
+ # Helpers
388
+ # ---------------------------------------------------------------------------
389
+
390
+ def _to_list(payload: Any) -> list:
391
+ if payload is None:
392
+ return []
393
+ if isinstance(payload, list):
394
+ return payload
395
+ if isinstance(payload, Iterable) and not isinstance(payload, (str, bytes, dict, BaseModel)):
396
+ return list(payload)
397
+ return [payload]
398
+
399
+
400
+ def _safe_priority_label(issue: Issue) -> str:
401
+ if issue.priority_label:
402
+ return issue.priority_label
403
+ return issue.priority.name.replace("_", " ").title() if issue.priority else "—"
404
+
405
+
406
+ def emit_error(message: str, *, hint: str | None = None) -> None:
407
+ """Print an error to stderr in human mode."""
408
+ err_console.print(f"[bold red]error:[/] {message}")
409
+ if hint:
410
+ err_console.print(f"[dim]hint:[/] {hint}")