kaiten-cli 0.3.3__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 (99) hide show
  1. kaiten_cli/__init__.py +5 -0
  2. kaiten_cli/__main__.py +9 -0
  3. kaiten_cli/agent_gateway.py +577 -0
  4. kaiten_cli/app.py +1636 -0
  5. kaiten_cli/completion.py +570 -0
  6. kaiten_cli/discovery.py +39 -0
  7. kaiten_cli/errors.py +79 -0
  8. kaiten_cli/i18n.py +92 -0
  9. kaiten_cli/locales/ru.json +2967 -0
  10. kaiten_cli/localized_click.py +160 -0
  11. kaiten_cli/models.py +202 -0
  12. kaiten_cli/profiles.py +316 -0
  13. kaiten_cli/registry/__init__.py +260 -0
  14. kaiten_cli/registry/addons.py +392 -0
  15. kaiten_cli/registry/audit_and_analytics.py +451 -0
  16. kaiten_cli/registry/automation_schema.py +44 -0
  17. kaiten_cli/registry/automation_schemas.json +7417 -0
  18. kaiten_cli/registry/automations.py +342 -0
  19. kaiten_cli/registry/base.py +62 -0
  20. kaiten_cli/registry/blockers.py +320 -0
  21. kaiten_cli/registry/boards.py +520 -0
  22. kaiten_cli/registry/card_relations.py +376 -0
  23. kaiten_cli/registry/card_types.py +363 -0
  24. kaiten_cli/registry/cards.py +1329 -0
  25. kaiten_cli/registry/charts.py +539 -0
  26. kaiten_cli/registry/checklists.py +600 -0
  27. kaiten_cli/registry/columns.py +558 -0
  28. kaiten_cli/registry/comments.py +224 -0
  29. kaiten_cli/registry/custom_directories.py +980 -0
  30. kaiten_cli/registry/custom_properties.py +1460 -0
  31. kaiten_cli/registry/dashboards.py +564 -0
  32. kaiten_cli/registry/documents.py +761 -0
  33. kaiten_cli/registry/external_links.py +128 -0
  34. kaiten_cli/registry/files.py +738 -0
  35. kaiten_cli/registry/github_addon.py +613 -0
  36. kaiten_cli/registry/iterations.py +397 -0
  37. kaiten_cli/registry/lanes.py +205 -0
  38. kaiten_cli/registry/live_contracts.py +361 -0
  39. kaiten_cli/registry/members.py +336 -0
  40. kaiten_cli/registry/module_docs.py +108 -0
  41. kaiten_cli/registry/projects.py +369 -0
  42. kaiten_cli/registry/query.py +129 -0
  43. kaiten_cli/registry/restrictions.py +249 -0
  44. kaiten_cli/registry/roles_and_groups.py +1102 -0
  45. kaiten_cli/registry/scim.py +263 -0
  46. kaiten_cli/registry/service_desk.py +1270 -0
  47. kaiten_cli/registry/snapshot.py +187 -0
  48. kaiten_cli/registry/spaces.py +272 -0
  49. kaiten_cli/registry/subscribers.py +168 -0
  50. kaiten_cli/registry/tags.py +193 -0
  51. kaiten_cli/registry/time_logs.py +353 -0
  52. kaiten_cli/registry/tree.py +352 -0
  53. kaiten_cli/registry/utilities.py +287 -0
  54. kaiten_cli/registry/webhooks.py +265 -0
  55. kaiten_cli/runtime/__init__.py +1 -0
  56. kaiten_cli/runtime/automation_validation.py +115 -0
  57. kaiten_cli/runtime/behaviors.py +787 -0
  58. kaiten_cli/runtime/cache.py +733 -0
  59. kaiten_cli/runtime/client.py +387 -0
  60. kaiten_cli/runtime/endpoints.py +59 -0
  61. kaiten_cli/runtime/executor.py +269 -0
  62. kaiten_cli/runtime/fs_security.py +168 -0
  63. kaiten_cli/runtime/input.py +310 -0
  64. kaiten_cli/runtime/output.py +59 -0
  65. kaiten_cli/runtime/public_validation.py +35 -0
  66. kaiten_cli/runtime/snapshot_build.py +527 -0
  67. kaiten_cli/runtime/snapshot_common.py +363 -0
  68. kaiten_cli/runtime/snapshot_query.py +306 -0
  69. kaiten_cli/runtime/snapshot_store.py +1192 -0
  70. kaiten_cli/runtime/snapshots.py +62 -0
  71. kaiten_cli/runtime/sqlite_errors.py +23 -0
  72. kaiten_cli/runtime/support/__init__.py +1 -0
  73. kaiten_cli/runtime/support/addons.py +953 -0
  74. kaiten_cli/runtime/support/audit.py +70 -0
  75. kaiten_cli/runtime/support/batch.py +234 -0
  76. kaiten_cli/runtime/support/card_move_url.py +213 -0
  77. kaiten_cli/runtime/support/cards.py +174 -0
  78. kaiten_cli/runtime/support/checklists.py +21 -0
  79. kaiten_cli/runtime/support/company_users.py +117 -0
  80. kaiten_cli/runtime/support/dashboards.py +35 -0
  81. kaiten_cli/runtime/support/documents.py +175 -0
  82. kaiten_cli/runtime/support/files.py +561 -0
  83. kaiten_cli/runtime/support/markdown_export.py +525 -0
  84. kaiten_cli/runtime/support/pagination.py +167 -0
  85. kaiten_cli/runtime/support/projects.py +66 -0
  86. kaiten_cli/runtime/support/relations.py +86 -0
  87. kaiten_cli/runtime/support/restrictions.py +62 -0
  88. kaiten_cli/runtime/support/spaces.py +20 -0
  89. kaiten_cli/runtime/support/time_logs.py +61 -0
  90. kaiten_cli/runtime/support/tree.py +140 -0
  91. kaiten_cli/runtime/support/tree_sharing.py +447 -0
  92. kaiten_cli/runtime/trace.py +500 -0
  93. kaiten_cli/runtime/transforms.py +128 -0
  94. kaiten_cli/schema_docs.py +22 -0
  95. kaiten_cli/update_check.py +519 -0
  96. kaiten_cli-0.3.3.dist-info/METADATA +1110 -0
  97. kaiten_cli-0.3.3.dist-info/RECORD +99 -0
  98. kaiten_cli-0.3.3.dist-info/WHEEL +4 -0
  99. kaiten_cli-0.3.3.dist-info/entry_points.txt +3 -0
@@ -0,0 +1,369 @@
1
+ """Project tool specs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from kaiten_cli.models import ExampleSpec, OperationSpec, ResponsePolicy, RuntimeBehavior
6
+ from kaiten_cli.registry.base import make_tool
7
+ from kaiten_cli.runtime.behaviors import execute_project_cards_list, project_title_to_name_request
8
+ from kaiten_cli.runtime.transforms import DEFAULT_LIMIT
9
+
10
+
11
+ TOOLS = (
12
+ make_tool(
13
+ canonical_name="projects.list",
14
+ mcp_alias="kaiten_list_projects",
15
+ description="List all Kaiten projects in the company.",
16
+ input_schema={"type": "object", "properties": {}},
17
+ operation=OperationSpec(method="GET", path_template="/projects"),
18
+ examples=(
19
+ ExampleSpec(
20
+ command="kaiten --json projects list", description="List company projects."
21
+ ),
22
+ ),
23
+ ),
24
+ make_tool(
25
+ canonical_name="projects.create",
26
+ mcp_alias="kaiten_create_project",
27
+ description="Create a new Kaiten project.",
28
+ input_schema={
29
+ "type": "object",
30
+ "properties": {
31
+ "title": {"type": "string", "description": "Project title (stored as 'name')"},
32
+ "description": {"type": "string", "description": "Project description"},
33
+ "work_calendar_id": {
34
+ "type": "string",
35
+ "description": "Work calendar UUID to attach to the project",
36
+ },
37
+ "settings": {"type": "object", "description": "Project settings"},
38
+ "properties": {
39
+ "type": "object",
40
+ "description": "Custom property values as {id_<N>: value} pairs",
41
+ },
42
+ },
43
+ "required": ["title"],
44
+ },
45
+ operation=OperationSpec(
46
+ method="POST",
47
+ path_template="/projects",
48
+ body_fields=("title", "description", "work_calendar_id", "settings", "properties"),
49
+ ),
50
+ runtime_behavior=RuntimeBehavior(request_shaper=project_title_to_name_request),
51
+ examples=(
52
+ ExampleSpec(
53
+ command='kaiten --json projects create --title "Platform"',
54
+ description="Create a project.",
55
+ ),
56
+ ),
57
+ ),
58
+ make_tool(
59
+ canonical_name="projects.get",
60
+ mcp_alias="kaiten_get_project",
61
+ description="Get a Kaiten project by ID.",
62
+ input_schema={
63
+ "type": "object",
64
+ "properties": {
65
+ "project_id": {"type": "string", "description": "Project ID (UUID)"},
66
+ "with_cards_data": {
67
+ "type": "boolean",
68
+ "description": "Include full card data with path info and custom properties",
69
+ },
70
+ },
71
+ "required": ["project_id"],
72
+ },
73
+ operation=OperationSpec(
74
+ method="GET",
75
+ path_template="/projects/{project_id}",
76
+ path_fields=("project_id",),
77
+ query_fields=("with_cards_data",),
78
+ ),
79
+ examples=(
80
+ ExampleSpec(
81
+ command="kaiten --json projects get --project-id p1",
82
+ description="Get a project by ID.",
83
+ ),
84
+ ),
85
+ ),
86
+ make_tool(
87
+ canonical_name="projects.update",
88
+ mcp_alias="kaiten_update_project",
89
+ description="Update a Kaiten project.",
90
+ input_schema={
91
+ "type": "object",
92
+ "properties": {
93
+ "project_id": {"type": "string", "description": "Project ID (UUID)"},
94
+ "title": {"type": "string", "description": "Project title (stored as 'name')"},
95
+ "description": {"type": "string", "description": "Project description"},
96
+ "condition": {
97
+ "type": "string",
98
+ "enum": ["active", "inactive"],
99
+ "description": "Project condition (active or inactive)",
100
+ },
101
+ "work_calendar_id": {
102
+ "type": "string",
103
+ "description": "Work calendar UUID to attach to the project",
104
+ },
105
+ "settings": {"type": "object", "description": "Project settings"},
106
+ "properties": {
107
+ "type": "object",
108
+ "description": "Custom property values as {id_<N>: value} pairs; set a key to null to clear it",
109
+ },
110
+ },
111
+ "required": ["project_id"],
112
+ },
113
+ operation=OperationSpec(
114
+ method="PATCH",
115
+ path_template="/projects/{project_id}",
116
+ path_fields=("project_id",),
117
+ body_fields=(
118
+ "title",
119
+ "description",
120
+ "condition",
121
+ "work_calendar_id",
122
+ "settings",
123
+ "properties",
124
+ ),
125
+ ),
126
+ runtime_behavior=RuntimeBehavior(request_shaper=project_title_to_name_request),
127
+ examples=(
128
+ ExampleSpec(
129
+ command='kaiten --json projects update --project-id p1 --title "Platform"',
130
+ description="Update a project.",
131
+ ),
132
+ ),
133
+ ),
134
+ make_tool(
135
+ canonical_name="projects.delete",
136
+ mcp_alias="kaiten_delete_project",
137
+ description="Delete a Kaiten project.",
138
+ input_schema={
139
+ "type": "object",
140
+ "properties": {
141
+ "project_id": {"type": "string", "description": "Project ID (UUID)"},
142
+ },
143
+ "required": ["project_id"],
144
+ },
145
+ operation=OperationSpec(
146
+ method="DELETE", path_template="/projects/{project_id}", path_fields=("project_id",)
147
+ ),
148
+ examples=(
149
+ ExampleSpec(
150
+ command="kaiten --json projects delete --project-id p1",
151
+ description="Delete a project.",
152
+ ),
153
+ ),
154
+ ),
155
+ make_tool(
156
+ canonical_name="projects.cards.list",
157
+ mcp_alias="kaiten_list_project_cards",
158
+ description="List cards in a Kaiten project.",
159
+ input_schema={
160
+ "type": "object",
161
+ "properties": {
162
+ "project_id": {"type": "string", "description": "Project ID (UUID)"},
163
+ "compact": {
164
+ "type": "boolean",
165
+ "description": "Return compact response without heavy fields (avatars, nested user objects).",
166
+ "default": False,
167
+ },
168
+ },
169
+ "required": ["project_id"],
170
+ },
171
+ operation=OperationSpec(
172
+ method="GET", path_template="/projects/{project_id}/cards", path_fields=("project_id",)
173
+ ),
174
+ response_policy=ResponsePolicy(compact_supported=True, result_kind="list"),
175
+ runtime_behavior=RuntimeBehavior(
176
+ execution_mode="synthetic", custom_executor=execute_project_cards_list
177
+ ),
178
+ examples=(
179
+ ExampleSpec(
180
+ command="kaiten --json projects cards list --project-id p1 --compact",
181
+ description="List project cards.",
182
+ ),
183
+ ),
184
+ ),
185
+ make_tool(
186
+ canonical_name="projects.cards.add",
187
+ mcp_alias="kaiten_add_project_card",
188
+ description="Add a card to a Kaiten project.",
189
+ input_schema={
190
+ "type": "object",
191
+ "properties": {
192
+ "project_id": {"type": "string", "description": "Project ID (UUID)"},
193
+ "card_id": {"type": "integer", "description": "Card ID to add"},
194
+ },
195
+ "required": ["project_id", "card_id"],
196
+ },
197
+ operation=OperationSpec(
198
+ method="POST",
199
+ path_template="/projects/{project_id}/cards",
200
+ path_fields=("project_id",),
201
+ body_fields=("card_id",),
202
+ ),
203
+ examples=(
204
+ ExampleSpec(
205
+ command="kaiten --json projects cards add --project-id p1 --card-id 10",
206
+ description="Add a card to a project.",
207
+ ),
208
+ ),
209
+ ),
210
+ make_tool(
211
+ canonical_name="projects.cards.remove",
212
+ mcp_alias="kaiten_remove_project_card",
213
+ description="Remove a card from a Kaiten project.",
214
+ input_schema={
215
+ "type": "object",
216
+ "properties": {
217
+ "project_id": {"type": "string", "description": "Project ID (UUID)"},
218
+ "card_id": {"type": "integer", "description": "Card ID to remove"},
219
+ },
220
+ "required": ["project_id", "card_id"],
221
+ },
222
+ operation=OperationSpec(
223
+ method="DELETE",
224
+ path_template="/projects/{project_id}/cards/{card_id}",
225
+ path_fields=("project_id", "card_id"),
226
+ ),
227
+ examples=(
228
+ ExampleSpec(
229
+ command="kaiten --json projects cards remove --project-id p1 --card-id 10",
230
+ description="Remove a card from a project.",
231
+ ),
232
+ ),
233
+ ),
234
+ make_tool(
235
+ canonical_name="sprints.list",
236
+ mcp_alias="kaiten_list_sprints",
237
+ description="List Kaiten sprints.",
238
+ input_schema={
239
+ "type": "object",
240
+ "properties": {
241
+ "active": {"type": "boolean", "description": "Filter by active/inactive"},
242
+ "limit": {"type": "integer", "description": "Max results (max 100)"},
243
+ "offset": {"type": "integer", "description": "Pagination offset"},
244
+ },
245
+ },
246
+ operation=OperationSpec(
247
+ method="GET", path_template="/sprints", query_fields=("active", "limit", "offset")
248
+ ),
249
+ response_policy=ResponsePolicy(default_limit=DEFAULT_LIMIT, result_kind="list"),
250
+ examples=(ExampleSpec(command="kaiten --json sprints list", description="List sprints."),),
251
+ ),
252
+ make_tool(
253
+ canonical_name="sprints.create",
254
+ mcp_alias="kaiten_create_sprint",
255
+ description="Create a new Kaiten sprint.",
256
+ input_schema={
257
+ "type": "object",
258
+ "properties": {
259
+ "title": {"type": "string", "description": "Sprint title"},
260
+ "board_id": {"type": "integer", "description": "Board ID for the sprint"},
261
+ "goal": {"type": "string", "description": "Sprint goal"},
262
+ "start_date": {"type": "string", "description": "Start date (ISO 8601)"},
263
+ "finish_date": {"type": "string", "description": "Finish date (ISO 8601)"},
264
+ },
265
+ "required": ["title", "board_id"],
266
+ },
267
+ operation=OperationSpec(
268
+ method="POST",
269
+ path_template="/sprints",
270
+ body_fields=("title", "board_id", "goal", "start_date", "finish_date"),
271
+ ),
272
+ examples=(
273
+ ExampleSpec(
274
+ command='kaiten --json sprints create --title "Sprint 1" --board-id 10',
275
+ description="Create a sprint.",
276
+ ),
277
+ ),
278
+ ),
279
+ make_tool(
280
+ canonical_name="sprints.get",
281
+ mcp_alias="kaiten_get_sprint",
282
+ description="Get a Kaiten sprint by ID.",
283
+ input_schema={
284
+ "type": "object",
285
+ "properties": {
286
+ "sprint_id": {"type": "integer", "description": "Sprint ID"},
287
+ "exclude_deleted_cards": {
288
+ "type": "boolean",
289
+ "description": "Exclude deleted cards from the sprint summary",
290
+ },
291
+ },
292
+ "required": ["sprint_id"],
293
+ },
294
+ operation=OperationSpec(
295
+ method="GET",
296
+ path_template="/sprints/{sprint_id}",
297
+ path_fields=("sprint_id",),
298
+ query_fields=("exclude_deleted_cards",),
299
+ ),
300
+ examples=(
301
+ ExampleSpec(
302
+ command="kaiten --json sprints get --sprint-id 1", description="Get a sprint."
303
+ ),
304
+ ),
305
+ ),
306
+ make_tool(
307
+ canonical_name="sprints.update",
308
+ mcp_alias="kaiten_update_sprint",
309
+ description="Update a Kaiten sprint.",
310
+ input_schema={
311
+ "type": "object",
312
+ "properties": {
313
+ "sprint_id": {"type": "integer", "description": "Sprint ID"},
314
+ "title": {"type": "string", "description": "Sprint title"},
315
+ "goal": {"type": "string", "description": "Sprint goal"},
316
+ "start_date": {"type": "string", "description": "Start date (ISO 8601)"},
317
+ "finish_date": {"type": "string", "description": "Finish date (ISO 8601)"},
318
+ "active": {
319
+ "type": "boolean",
320
+ "description": "Set to false to finish/complete the sprint",
321
+ },
322
+ "archive_done_cards": {
323
+ "type": "boolean",
324
+ "description": "Archive completed cards when finishing a sprint",
325
+ },
326
+ },
327
+ "required": ["sprint_id"],
328
+ },
329
+ operation=OperationSpec(
330
+ method="PATCH",
331
+ path_template="/sprints/{sprint_id}",
332
+ path_fields=("sprint_id",),
333
+ body_fields=(
334
+ "title",
335
+ "goal",
336
+ "start_date",
337
+ "finish_date",
338
+ "active",
339
+ "archive_done_cards",
340
+ ),
341
+ ),
342
+ examples=(
343
+ ExampleSpec(
344
+ command="kaiten --json sprints update --sprint-id 1 --active false",
345
+ description="Update a sprint.",
346
+ ),
347
+ ),
348
+ ),
349
+ make_tool(
350
+ canonical_name="sprints.delete",
351
+ mcp_alias="kaiten_delete_sprint",
352
+ description="Delete a Kaiten sprint.",
353
+ input_schema={
354
+ "type": "object",
355
+ "properties": {
356
+ "sprint_id": {"type": "integer", "description": "Sprint ID"},
357
+ },
358
+ "required": ["sprint_id"],
359
+ },
360
+ operation=OperationSpec(
361
+ method="DELETE", path_template="/sprints/{sprint_id}", path_fields=("sprint_id",)
362
+ ),
363
+ examples=(
364
+ ExampleSpec(
365
+ command="kaiten --json sprints delete --sprint-id 1", description="Delete a sprint."
366
+ ),
367
+ ),
368
+ ),
369
+ )
@@ -0,0 +1,129 @@
1
+ """Local query tool specs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from kaiten_cli.models import ExampleSpec, OperationSpec, ResponsePolicy, RuntimeBehavior
6
+ from kaiten_cli.registry.base import make_tool
7
+ from kaiten_cli.runtime.snapshots import (
8
+ execute_query_cards,
9
+ execute_query_metrics,
10
+ validate_query_filter,
11
+ )
12
+
13
+
14
+ TOOLS = (
15
+ make_tool(
16
+ canonical_name="query.cards",
17
+ mcp_alias="kaiten_query_cards",
18
+ description="Run local card filtering against a stored snapshot without calling the Kaiten API.",
19
+ input_schema={
20
+ "type": "object",
21
+ "properties": {
22
+ "snapshot": {"type": "string", "description": "Snapshot name."},
23
+ "filter": {
24
+ "type": "object",
25
+ "description": "Local filter object for card selection.",
26
+ },
27
+ "view": {
28
+ "type": "string",
29
+ "enum": ["summary", "detail", "evidence"],
30
+ "description": "Local output view. summary is the default and keeps payloads narrow for repeated analytics and LLM workflows.",
31
+ },
32
+ "fields": {
33
+ "type": "string",
34
+ "description": "Comma-separated card or derived field names to keep.",
35
+ },
36
+ "limit": {"type": "integer", "description": "Max returned rows. Default 100."},
37
+ "offset": {"type": "integer", "description": "Pagination offset."},
38
+ "compact": {"type": "boolean", "description": "Return a compact card response."},
39
+ },
40
+ "required": ["snapshot"],
41
+ },
42
+ operation=OperationSpec(method="GET", path_template="/local/query/cards"),
43
+ response_policy=ResponsePolicy(
44
+ compact_supported=True, fields_supported=True, result_kind="list"
45
+ ),
46
+ runtime_behavior=RuntimeBehavior(
47
+ execution_mode="custom",
48
+ custom_executor=execute_query_cards,
49
+ payload_validator=validate_query_filter,
50
+ cache_policy="none",
51
+ requires_profile=False,
52
+ apply_common_transforms=False,
53
+ ),
54
+ examples=(
55
+ ExampleSpec(
56
+ command='kaiten --json query cards --snapshot team-basic --filter \'{"board_ids":[10],"has_children":true}\' --fields id,title,has_children',
57
+ description="Filter cards locally by board and derived flags in summary view.",
58
+ ),
59
+ ExampleSpec(
60
+ command='kaiten --json query cards --snapshot team-basic --view evidence --filter \'{"comment_text_query":"blocked"}\' --compact --fields id,title,comment_text',
61
+ description="Search local evidence text without extra API calls.",
62
+ ),
63
+ ),
64
+ usage_notes=(
65
+ "query cards never calls the Kaiten API; build or refresh the snapshot first.",
66
+ "summary is the default view and keeps local card payloads narrow for LLM and report workflows.",
67
+ "Use text_query, child_text_query, and comment_text_query to reduce candidate sets locally before involving an LLM.",
68
+ ),
69
+ ),
70
+ make_tool(
71
+ canonical_name="query.metrics",
72
+ mcp_alias="kaiten_query_metrics",
73
+ description="Compute local metrics over a stored snapshot without calling the Kaiten API.",
74
+ input_schema={
75
+ "type": "object",
76
+ "properties": {
77
+ "snapshot": {"type": "string", "description": "Snapshot name."},
78
+ "metric": {
79
+ "type": "string",
80
+ "enum": ["count", "wip", "throughput", "lead_time", "cycle_time", "aging"],
81
+ "description": "Metric to compute locally.",
82
+ },
83
+ "filter": {
84
+ "type": "object",
85
+ "description": "Optional local filter object applied before metrics.",
86
+ },
87
+ "group_by": {
88
+ "type": ["string", "null"],
89
+ "enum": [
90
+ "board_id",
91
+ "column_id",
92
+ "lane_id",
93
+ "type_id",
94
+ "owner_id",
95
+ "responsible_id",
96
+ "state",
97
+ "condition",
98
+ None,
99
+ ],
100
+ "description": "Optional grouping field.",
101
+ },
102
+ },
103
+ "required": ["snapshot", "metric"],
104
+ },
105
+ operation=OperationSpec(method="GET", path_template="/local/query/metrics"),
106
+ response_policy=ResponsePolicy(result_kind="entity"),
107
+ runtime_behavior=RuntimeBehavior(
108
+ execution_mode="custom",
109
+ custom_executor=execute_query_metrics,
110
+ payload_validator=validate_query_filter,
111
+ cache_policy="none",
112
+ requires_profile=False,
113
+ ),
114
+ examples=(
115
+ ExampleSpec(
116
+ command="kaiten --json query metrics --snapshot team-q1 --metric throughput --group-by board_id",
117
+ description="Compute throughput locally over the snapshot window.",
118
+ ),
119
+ ExampleSpec(
120
+ command='kaiten --json query metrics --snapshot team-basic --metric aging --filter \'{"board_ids":[10],"has_comments":true}\' --group-by column_id',
121
+ description="Compute local WIP aging for a reduced candidate set.",
122
+ ),
123
+ ),
124
+ usage_notes=(
125
+ "throughput, lead_time, and cycle_time use the snapshot window when it exists; basic snapshots fall back to all locally known done transitions.",
126
+ "For repeated report generation, query metrics after snapshot build instead of re-fetching topology, cards, and history on every run.",
127
+ ),
128
+ ),
129
+ )