agl 43.7.0 → 43.9.0

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 (143) hide show
  1. package/changelog.md +33 -0
  2. package/dist_serve/bundle.js +871 -858
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_ts/00_commitinfo_data.js +1 -1
  5. package/dist_ts/aglapi/aglapisurface.document.js +824 -6
  6. package/dist_ts/aglapi/interfaces.d.ts +43 -0
  7. package/dist_ts/aglapi/interfaces.js +11 -1
  8. package/dist_ts/classes.apnsclient.d.ts +97 -0
  9. package/dist_ts/classes.apnsclient.js +363 -0
  10. package/dist_ts/classes.authmodels.js +19 -6
  11. package/dist_ts/classes.authstore.js +15 -2
  12. package/dist_ts/classes.cli.js +8 -1
  13. package/dist_ts/classes.controller.d.ts +30 -3
  14. package/dist_ts/classes.controller.js +250 -9
  15. package/dist_ts/classes.controllerdevices.d.ts +35 -7
  16. package/dist_ts/classes.controllerdevices.js +86 -13
  17. package/dist_ts/classes.controllerpush.d.ts +111 -0
  18. package/dist_ts/classes.controllerpush.js +299 -0
  19. package/dist_ts/classes.fcmclient.d.ts +78 -0
  20. package/dist_ts/classes.fcmclient.js +278 -0
  21. package/dist_ts/classes.inbox.d.ts +10 -2
  22. package/dist_ts/classes.inbox.js +9 -2
  23. package/dist_ts/classes.mcpclient.d.ts +5 -0
  24. package/dist_ts/classes.mcpclient.js +20 -8
  25. package/dist_ts/classes.mcpcontrollerhost.d.ts +3 -0
  26. package/dist_ts/classes.mcpcontrollerhost.js +21 -2
  27. package/dist_ts/classes.mcptools.d.ts +1 -1
  28. package/dist_ts/classes.mcptools.js +2 -1
  29. package/dist_ts/classes.mcpvalidation.js +4 -1
  30. package/dist_ts/classes.mcpworkercaller.d.ts +6 -0
  31. package/dist_ts/classes.mcpworkercaller.js +26 -4
  32. package/dist_ts/classes.pushdelivery.d.ts +115 -0
  33. package/dist_ts/classes.pushdelivery.js +311 -0
  34. package/dist_ts/classes.pushhandover.d.ts +46 -0
  35. package/dist_ts/classes.pushhandover.js +131 -0
  36. package/dist_ts/classes.pushregistrations.d.ts +96 -0
  37. package/dist_ts/classes.pushregistrations.js +263 -0
  38. package/dist_ts/classes.pushsettings.d.ts +125 -0
  39. package/dist_ts/classes.pushsettings.js +377 -0
  40. package/dist_ts/classes.ticketstore.d.ts +3 -3
  41. package/dist_ts/classes.ticketstore.js +23 -4
  42. package/dist_ts/classes.workercallers.d.ts +73 -2
  43. package/dist_ts/classes.workercallers.js +354 -43
  44. package/dist_ts/driver/classes.directreports.d.ts +5 -0
  45. package/dist_ts/driver/classes.directreports.js +3 -2
  46. package/dist_ts/fleet/classes.workerlaunches.d.ts +6 -4
  47. package/dist_ts/fleet/classes.workerlaunches.js +10 -9
  48. package/dist_ts/fleet/classes.workers.d.ts +12 -2
  49. package/dist_ts/fleet/classes.workers.js +82 -2
  50. package/dist_ts/functions.deviceapi.d.ts +23 -3
  51. package/dist_ts/functions.deviceapi.js +43 -3
  52. package/dist_ts/functions.mcptickettools.d.ts +60 -0
  53. package/dist_ts/functions.mcptickettools.js +4 -3
  54. package/dist_ts/functions.pushcli.d.ts +43 -0
  55. package/dist_ts/functions.pushcli.js +201 -0
  56. package/dist_ts/functions.pushcredentials.d.ts +53 -0
  57. package/dist_ts/functions.pushcredentials.js +111 -0
  58. package/dist_ts/functions.pushwire.d.ts +8 -0
  59. package/dist_ts/functions.pushwire.js +83 -0
  60. package/dist_ts/functions.remotecli.d.ts +2 -2
  61. package/dist_ts/functions.remotecli.js +4 -4
  62. package/dist_ts/functions.ticketcli.d.ts +4 -2
  63. package/dist_ts/functions.ticketcli.js +70 -4
  64. package/dist_ts/functions.ticketlisting.d.ts +38 -0
  65. package/dist_ts/functions.ticketlisting.js +211 -0
  66. package/dist_ts/functions.ticketvalidation.d.ts +62 -0
  67. package/dist_ts/functions.ticketvalidation.js +41 -3
  68. package/dist_ts/functions.workercallervalidation.js +3 -2
  69. package/dist_ts/functions.workerprocessproof.d.ts +12 -0
  70. package/dist_ts/functions.workerprocessproof.js +32 -1
  71. package/dist_ts/interfaces.auth.d.ts +27 -3
  72. package/dist_ts/interfaces.auth.js +9 -1
  73. package/dist_ts/interfaces.lifecycle.d.ts +7 -1
  74. package/dist_ts/interfaces.push.d.ts +69 -0
  75. package/dist_ts/interfaces.push.js +25 -0
  76. package/dist_ts/plugins.d.ts +3 -1
  77. package/dist_ts/plugins.js +4 -2
  78. package/dist_ts_interfaces/devices.d.ts +178 -2
  79. package/dist_ts_interfaces/devices.js +24 -2
  80. package/dist_ts_interfaces/index.d.ts +1 -0
  81. package/dist_ts_interfaces/index.js +2 -1
  82. package/dist_ts_interfaces/mcprequests.d.ts +3 -2
  83. package/dist_ts_interfaces/mcprequests.js +3 -1
  84. package/dist_ts_interfaces/push.d.ts +166 -0
  85. package/dist_ts_interfaces/push.js +24 -0
  86. package/dist_ts_interfaces/requests.tickets.d.ts +31 -3
  87. package/dist_ts_interfaces/requests.tickets.js +2 -2
  88. package/dist_ts_interfaces/tickets.d.ts +174 -2
  89. package/dist_ts_interfaces/tickets.js +20 -2
  90. package/dist_ts_interfaces/workercallers.d.ts +43 -3
  91. package/package.json +2 -2
  92. package/readme.md +95 -14
  93. package/ts/00_commitinfo_data.ts +1 -1
  94. package/ts/aglapi/aglapisurface.document.ts +823 -5
  95. package/ts/aglapi/interfaces.ts +10 -0
  96. package/ts/classes.apnsclient.ts +389 -0
  97. package/ts/classes.authmodels.ts +21 -5
  98. package/ts/classes.authstore.ts +14 -1
  99. package/ts/classes.cli.ts +7 -0
  100. package/ts/classes.controller.ts +273 -7
  101. package/ts/classes.controllerdevices.ts +94 -12
  102. package/ts/classes.controllerpush.ts +351 -0
  103. package/ts/classes.fcmclient.ts +292 -0
  104. package/ts/classes.inbox.ts +13 -2
  105. package/ts/classes.mcpclient.ts +22 -7
  106. package/ts/classes.mcpcontrollerhost.ts +22 -1
  107. package/ts/classes.mcptools.ts +1 -0
  108. package/ts/classes.mcpvalidation.ts +2 -0
  109. package/ts/classes.mcpworkercaller.ts +24 -2
  110. package/ts/classes.pushdelivery.ts +378 -0
  111. package/ts/classes.pushhandover.ts +98 -0
  112. package/ts/classes.pushregistrations.ts +244 -0
  113. package/ts/classes.pushsettings.ts +428 -0
  114. package/ts/classes.ticketstore.ts +21 -3
  115. package/ts/classes.workercallers.ts +329 -37
  116. package/ts/driver/classes.directreports.ts +7 -1
  117. package/ts/fleet/classes.workerlaunches.ts +9 -7
  118. package/ts/fleet/classes.workers.ts +65 -2
  119. package/ts/functions.deviceapi.ts +54 -2
  120. package/ts/functions.mcptickettools.ts +3 -2
  121. package/ts/functions.pushcli.ts +212 -0
  122. package/ts/functions.pushcredentials.ts +129 -0
  123. package/ts/functions.pushwire.ts +106 -0
  124. package/ts/functions.remotecli.ts +3 -2
  125. package/ts/functions.ticketcli.ts +70 -5
  126. package/ts/functions.ticketlisting.ts +214 -0
  127. package/ts/functions.ticketvalidation.ts +41 -2
  128. package/ts/functions.workercallervalidation.ts +2 -1
  129. package/ts/functions.workerprocessproof.ts +34 -0
  130. package/ts/interfaces.auth.ts +26 -3
  131. package/ts/interfaces.lifecycle.ts +7 -1
  132. package/ts/interfaces.push.ts +78 -0
  133. package/ts/plugins.ts +3 -1
  134. package/ts_interfaces/devices.schema.json +327 -0
  135. package/ts_interfaces/devices.ts +206 -1
  136. package/ts_interfaces/index.ts +1 -0
  137. package/ts_interfaces/mcprequests.ts +3 -0
  138. package/ts_interfaces/push.ts +162 -0
  139. package/ts_interfaces/requests.tickets.ts +32 -2
  140. package/ts_interfaces/tickets.ts +136 -3
  141. package/ts_interfaces/workercallers.ts +34 -2
  142. package/ts_web/00_commitinfo_data.ts +1 -1
  143. package/ts_web/elements.inbox.ts +50 -9
@@ -0,0 +1,106 @@
1
+ import {
2
+ controllerMcpPushMethods,
3
+ pushOperationOf,
4
+ pushSecretRequestFields,
5
+ type TControllerMcpPushMethod,
6
+ type TPushOperation,
7
+ } from '../ts_interfaces/push.js';
8
+
9
+ /**
10
+ * The shape of `agl push` requests and answers on the controller's private channel (AGL-1639). Only the shape: the
11
+ * controller judges the values, and neither a refusal here nor one there repeats a value, since `signingKey` and
12
+ * `serviceAccount` carry the owner's keys.
13
+ */
14
+
15
+ const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
16
+ !!valueArg && typeof valueArg === 'object' && !Array.isArray(valueArg)
17
+ );
18
+
19
+ const isText = (valueArg: unknown, maximumArg: number): valueArg is string => (
20
+ typeof valueArg === 'string' && valueArg.length > 0 && valueArg.length <= maximumArg
21
+ );
22
+
23
+ /** Each request's fields besides `ownerToken`, with the most a field may hold. */
24
+ const requestFields: Record<TPushOperation, { required: Record<string, number | 'boolean'>; optional?: Record<string, number> }> = {
25
+ status: { required: {} },
26
+ // A .p8 file is about 250 bytes; a service account key file about 2.4 KB.
27
+ 'apns.set': { required: { keyId: 64, teamId: 64, signingKey: 16 * 1024 }, optional: { topic: 255 } },
28
+ 'apns.unset': { required: {} },
29
+ 'fcm.set': { required: { serviceAccount: 32 * 1024 } },
30
+ 'fcm.unset': { required: {} },
31
+ previews: { required: { previews: 'boolean' } },
32
+ test: { required: {}, optional: { deviceId: 64 } },
33
+ };
34
+
35
+ export const isControllerMcpPushMethod = (methodArg: string): methodArg is TControllerMcpPushMethod => (
36
+ (controllerMcpPushMethods as readonly string[]).includes(methodArg)
37
+ );
38
+
39
+ /** An `agl.mcp.push.*` request in shape, with the owner capability; refused without naming a value. */
40
+ export const assertPushWireRequest = (methodArg: string, valueArg: unknown): Record<string, unknown> => {
41
+ if (!isControllerMcpPushMethod(methodArg) || !isRecord(valueArg)) throw new Error('Invalid private controller request.');
42
+ const { required, optional = {} } = requestFields[pushOperationOf(methodArg)];
43
+ const keys = Object.keys(valueArg);
44
+ if (!isText(valueArg.ownerToken, 1024)
45
+ || keys.some((keyArg) => keyArg !== 'ownerToken' && !Object.hasOwn(required, keyArg) && !Object.hasOwn(optional, keyArg))
46
+ || Object.entries(required).some(([keyArg, ruleArg]) => (ruleArg === 'boolean'
47
+ ? typeof valueArg[keyArg] !== 'boolean' : !isText(valueArg[keyArg], ruleArg)))
48
+ || Object.entries(optional).some(([keyArg, maximumArg]) => valueArg[keyArg] !== undefined && !isText(valueArg[keyArg], maximumArg))) {
49
+ throw new Error('Invalid private controller request.');
50
+ }
51
+ return valueArg;
52
+ };
53
+
54
+ /** A request as the controller's answer echoes it: the owner capability and the keys replaced. */
55
+ export const redactPushRequest = (requestArg: Record<string, unknown>): Record<string, unknown> => {
56
+ const redacted = { ...requestArg };
57
+ for (const field of ['ownerToken', ...pushSecretRequestFields]) if (Object.hasOwn(redacted, field)) redacted[field] = '[redacted]';
58
+ return redacted;
59
+ };
60
+
61
+ const credentialStates: readonly unknown[] = ['unset', 'ready', 'refused', 'unreadable'];
62
+ const failureReasons: readonly unknown[] = ['credential_refused', 'refused', 'rate_limited', 'service_failed', 'unreachable'];
63
+
64
+ const isTime = (valueArg: unknown): boolean => Number.isSafeInteger(valueArg) && (valueArg as number) > 0;
65
+
66
+ /** A clock skew within a year either way. */
67
+ const isClockSkew = (valueArg: unknown): boolean => Number.isSafeInteger(valueArg) && Math.abs(valueArg as number) <= 366 * 24 * 60 * 60_000;
68
+
69
+ const isFailure = (valueArg: unknown): boolean => isRecord(valueArg) && isTime(valueArg.at) && failureReasons.includes(valueArg.reason)
70
+ && (valueArg.vendorReason === undefined || isText(valueArg.vendorReason, 64))
71
+ && (valueArg.clockSkewMs === undefined || isClockSkew(valueArg.clockSkewMs))
72
+ && Object.keys(valueArg).every((keyArg) => ['at', 'reason', 'vendorReason', 'clockSkewMs'].includes(keyArg));
73
+
74
+ const isPlatformStatus = (valueArg: unknown, fieldsArg: readonly string[]): boolean => isRecord(valueArg)
75
+ && credentialStates.includes(valueArg.state)
76
+ && Number.isSafeInteger(valueArg.registrations) && (valueArg.registrations as number) >= 0
77
+ && (valueArg.setAt === undefined || isTime(valueArg.setAt))
78
+ && (valueArg.refused === undefined || isFailure(valueArg.refused))
79
+ && (valueArg.lastFailure === undefined || isFailure(valueArg.lastFailure))
80
+ && fieldsArg.every((keyArg) => valueArg[keyArg] === undefined || isText(valueArg[keyArg], 255))
81
+ && Object.keys(valueArg).every((keyArg) => ['state', 'registrations', 'setAt', 'refused', 'lastFailure', ...fieldsArg].includes(keyArg));
82
+
83
+ const isPushStatus = (valueArg: unknown): boolean => isRecord(valueArg)
84
+ && Object.keys(valueArg).length === 3 && typeof valueArg.previews === 'boolean'
85
+ && isPlatformStatus(valueArg.apns, ['keyId', 'teamId', 'topic'])
86
+ && isPlatformStatus(valueArg.fcm, ['projectId', 'clientEmail']);
87
+
88
+ const testOutcomes: readonly unknown[] = ['delivered', 'unregistered', 'unavailable', 'no_answer', ...failureReasons];
89
+
90
+ const isTestResult = (valueArg: unknown): boolean => isRecord(valueArg)
91
+ && isText(valueArg.deviceId, 64) && typeof valueArg.name === 'string' && valueArg.name.length <= 256
92
+ && (valueArg.platform === 'apns' || valueArg.platform === 'fcm')
93
+ && (valueArg.environment === undefined || valueArg.environment === 'sandbox' || valueArg.environment === 'production')
94
+ && testOutcomes.includes(valueArg.outcome)
95
+ && (valueArg.vendorReason === undefined || isText(valueArg.vendorReason, 64))
96
+ && Object.keys(valueArg).every((keyArg) => ['deviceId', 'name', 'platform', 'environment', 'outcome', 'vendorReason'].includes(keyArg));
97
+
98
+ /** An `agl.mcp.push.*` answer in shape, as `agl push` prints it. */
99
+ export const assertPushResponse = (methodArg: TControllerMcpPushMethod, valueArg: unknown): void => {
100
+ const operation = pushOperationOf(methodArg);
101
+ const valid = operation === 'status' ? isPushStatus(valueArg)
102
+ : operation === 'test' ? isRecord(valueArg) && Object.keys(valueArg).length === 1 && Array.isArray(valueArg.results)
103
+ && valueArg.results.length <= 1024 && valueArg.results.every(isTestResult)
104
+ : isRecord(valueArg) && Object.keys(valueArg).length === 2 && typeof valueArg.changed === 'boolean' && isPushStatus(valueArg.status);
105
+ if (!valid) throw new Error('invalid');
106
+ };
@@ -95,12 +95,13 @@ const maximumSecretInputBytes = 4_096;
95
95
 
96
96
  /**
97
97
  * Reads a secret from standard input, a pipe or a file, never a terminal (`refusalArg` names the right way), and
98
- * returns it trimmed; nothing of it is echoed or kept past the read.
98
+ * returns it trimmed; nothing of it is echoed or kept past the read. `maximumBytesArg` bounds it (4 KiB by default).
99
99
  */
100
100
  export const readStandardInputSecret = async (
101
101
  inputArg: NodeJS.ReadableStream & { isTTY?: boolean },
102
102
  refusalArg: string,
103
103
  whatArg: string,
104
+ maximumBytesArg = maximumSecretInputBytes,
104
105
  ): Promise<string> => {
105
106
  if (inputArg.isTTY) throw new Error(refusalArg);
106
107
  const chunks: Buffer[] = [];
@@ -110,7 +111,7 @@ export const readStandardInputSecret = async (
110
111
  const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk as Uint8Array);
111
112
  chunks.push(buffer);
112
113
  bytes += buffer.byteLength;
113
- if (bytes > maximumSecretInputBytes) throw new Error(`The standard input is longer than ${whatArg}.`);
114
+ if (bytes > maximumBytesArg) throw new Error(`The standard input is longer than ${whatArg}.`);
114
115
  }
115
116
  return Buffer.concat(chunks).toString('utf8').trim();
116
117
  } finally {
@@ -4,11 +4,27 @@ import { withLocalConfigurationOwner } from './functions.configurationowner.js';
4
4
  import { assertTicketRequest } from './functions.ticketvalidation.js';
5
5
  import { defaultControllerPort } from './classes.config.js';
6
6
  import type {
7
- ITicketChanges, ITicketDeployPlanInput, ITicketMaintenanceWindow, ITicketPerson, TTicketOperation, TTicketRequest, TTicketLink,
7
+ ITicketChanges, ITicketDeployPlanInput, ITicketMaintenanceWindow, ITicketOverview, ITicketPerson, ITicketSummary, TTicketOperation,
8
+ TTicketRequest, TTicketLink,
8
9
  } from '../ts_interfaces/tickets.js';
9
10
 
10
- export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|comment|link|unlink|assign|ask|answer> [AGL-<n>] [options]
11
+ export const ticketCliHelp = `Usage: agl ticket <overview|page|list|get|create|update|move|comment|link|unlink|assign|ask|answer> [AGL-<n>] [options]
12
+ overview [--project ID] [--mine] [--limit N] [--stale-days N]
13
+ The board at a glance: counts by column, priority, AutoLabel, project and assignee, each open epic's
14
+ progress, the tickets that need someone (urgent, needs input, open questions, review, ready without an
15
+ assignee, stale after N days without a change, default 3) and the tickets changed last. Lists hold at
16
+ most --limit tickets (default 5, at most 50) and name how many there are in all.
17
+ page [--mine] [--project ID] [--status COLUMN] [--statuses COLUMN,…] [--open|--done] [--kind epic|task|subtask]
18
+ [--priorities PRIORITY,…] [--parent AGL-<n>] [--assignee ID] [--unassigned] [--keys AGL-<n>,…]
19
+ [--since INSTANT] [--label LABEL] [--text TEXT] [--sort board|updated|created|priority] [--full]
20
+ [--limit N] [--cursor CURSOR]
21
+ One page of the board (default 50 tickets, at most 200, within 256 KiB) as summaries without description
22
+ and source words; --full returns whole tickets. total and columns count everything the filters match.
23
+ --open leaves out released and closed tickets, --done keeps only those; --parent lists a ticket's direct
24
+ children; --assignee is a person id or a session id; --since an ISO 8601 instant of the last change.
25
+ nextCursor names the next page: pass it as --cursor with the same filters, sort and view.
11
26
  list [--mine] [--project ID] [--status COLUMN] [--label LABEL] [--text TEXT]
27
+ Every matching ticket whole and unpaged; prefer page on a large board.
12
28
  --label also matches AutoLabels, which AGL computes: openQuestion (an unanswered question),
13
29
  planned (a release plan on a ticket not yet released)
14
30
  get AGL-<n> [--limit N] [--before HISTORY-ID] [--comment COMMENT-ID]
@@ -73,6 +89,9 @@ export interface ITicketCliArguments {
73
89
  const common = ['port', 'json'];
74
90
  const actionOptions: Record<string, string[]> = {
75
91
  list: ['mine', 'project', 'status', 'label', 'text'], get: ['limit', 'before', 'comment'],
92
+ page: ['mine', 'project', 'status', 'statuses', 'open', 'done', 'kind', 'priorities', 'parent', 'assignee', 'unassigned', 'keys',
93
+ 'since', 'label', 'text', 'sort', 'full', 'limit', 'cursor'],
94
+ overview: ['project', 'mine', 'limit', 'stale-days'],
76
95
  create: ['project', 'title', 'description', 'kind', 'parent', 'priority', 'labels', 'source', 'attachments', 'column', 'release-plan',
77
96
  'deploy-plan', 'window', 'window-targets'],
78
97
  update: ['expected-revision', 'changes', 'title', 'description', 'priority', 'project', 'labels', 'parent', 'clear-parent',
@@ -82,7 +101,7 @@ const actionOptions: Record<string, string[]> = {
82
101
  assign: ['expected-revision', 'session-id', 'assignee', 'name', 'kind', 'clear'],
83
102
  ask: ['text', 'options', 'multi', 'no-custom'], answer: ['question', 'choice', 'text'],
84
103
  };
85
- const booleanOptions = new Set(['json', 'mine', 'clear', 'clear-parent', 'clear-release-plan', 'clear-window', 'multi', 'no-custom']);
104
+ const booleanOptions = new Set(['json', 'mine', 'open', 'done', 'unassigned', 'full', 'clear', 'clear-parent', 'clear-release-plan', 'clear-window', 'multi', 'no-custom']);
86
105
 
87
106
  /** `REPO[@VERSION]`: the repository a release plan names and, after the last `@`, the version it should reach. */
88
107
  export const parseReleasePlanOption = (valueArg: string): { repo: string; version?: string } => {
@@ -112,7 +131,7 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
112
131
  const [action, ...argumentsRest] = argumentsArg;
113
132
  if (!action || !Object.hasOwn(actionOptions, action)) throw new Error(ticketCliHelp);
114
133
  const rest = [...argumentsRest];
115
- const ticketId = action === 'list' || action === 'create' ? undefined : rest.shift();
134
+ const ticketId = ['list', 'page', 'overview', 'create'].includes(action) ? undefined : rest.shift();
116
135
  const allowed = new Set([...common, ...actionOptions[action]!]);
117
136
  const options = new Map<string, string>();
118
137
  for (let index = 0; index < rest.length; index++) {
@@ -159,6 +178,19 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
159
178
  };
160
179
  if (action === 'list') request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'),
161
180
  ...optional('status'), ...optional('label'), ...optional('text') };
181
+ else if (action === 'page') {
182
+ if (options.has('open') && options.has('done')) throw new Error('--open and --done conflict.');
183
+ const list = (keyArg: string, fieldArg = keyArg) => options.has(keyArg)
184
+ ? { [fieldArg]: options.get(keyArg)!.split(',').map((valueArg) => valueArg.trim()).filter(Boolean) } : {};
185
+ request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'), ...optional('status'), ...list('statuses'),
186
+ ...(options.has('open') ? { open: true } : {}), ...(options.has('done') ? { open: false } : {}), ...optional('kind'),
187
+ ...list('priorities'), ...optional('parent'), ...optional('assignee'), ...(options.has('unassigned') ? { unassigned: true } : {}),
188
+ ...list('keys'), ...optional('since', 'updatedSince'), ...optional('label'), ...optional('text'), ...optional('sort'),
189
+ ...(options.has('full') ? { view: 'full' } : {}), ...(options.has('limit') ? { limit: Number(required('limit')) } : {}),
190
+ ...optional('cursor') };
191
+ } else if (action === 'overview') request = { ...optional('project'), ...(options.has('mine') ? { mine: true } : {}),
192
+ ...(options.has('limit') ? { limit: Number(required('limit')) } : {}),
193
+ ...(options.has('stale-days') ? { staleDays: Number(required('stale-days')) } : {}) };
162
194
  else if (action === 'get') request = { ticketId, ...optional('before'), ...optional('comment', 'commentId'),
163
195
  ...(options.has('limit') ? { limit: Number(required('limit')) } : {}) };
164
196
  else if (action === 'create') request = { project: required('project'), title: required('title'), ...optional('description'),
@@ -210,11 +242,44 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
210
242
  return { operation, request: assertTicketRequest(operation, request), port, json: options.has('json') };
211
243
  };
212
244
 
245
+ const counts = (countsArg: Record<string, number>): string => Object.entries(countsArg).filter(([, countArg]) => countArg > 0)
246
+ .map(([nameArg, countArg]) => `${nameArg} ${countArg}`).join(', ') || 'none';
247
+ const summaryLine = (ticketArg: Pick<ITicketSummary, 'key' | 'project' | 'columnId' | 'priority' | 'title' | 'assignee'>): string => (
248
+ `${ticketArg.key}\t${ticketArg.project}\t${ticketArg.columnId}\t${ticketArg.priority}\t${ticketArg.assignee?.name ?? '-'}\t${ticketArg.title}\n`);
249
+ /** The overview as text: the counts, then each list with what it stands for. */
250
+ export const formatTicketOverview = (overviewArg: ITicketOverview): string => {
251
+ const lines = [`Board revision ${overviewArg.revision}: ${overviewArg.total} tickets, ${overviewArg.open} open, ${overviewArg.unassignedOpen} open without an assignee\n`,
252
+ `Columns: ${counts(overviewArg.columns)}\n`, `Open by priority: ${counts(overviewArg.priorities)}\n`, `AutoLabels: ${counts(overviewArg.autoLabels)}\n`,
253
+ `\nProjects (${overviewArg.projects.length} of ${overviewArg.projectsTotal}):\n`,
254
+ ...overviewArg.projects.map((projectArg) => ` ${projectArg.project}\t${projectArg.open} open of ${projectArg.total}\t${counts(projectArg.columns)}\n`),
255
+ `\nAssignees (${overviewArg.assignees.length} of ${overviewArg.assigneesTotal}):\n`,
256
+ ...overviewArg.assignees.map((assigneeArg) => ` ${assigneeArg.name}\t${assigneeArg.open} open\t${counts(assigneeArg.columns)}\t${assigneeArg.sessionId ?? assigneeArg.id}\n`),
257
+ `\nOpen epics (${overviewArg.epics.length} of ${overviewArg.epicsTotal}):\n`,
258
+ ...overviewArg.epics.map((epicArg) => ` ${epicArg.key}\t${epicArg.project}\t${epicArg.done}/${epicArg.children} done\t${epicArg.title}\n`)];
259
+ const groups: [string, ITicketOverview['attention'][keyof ITicketOverview['attention']]][] = [
260
+ ['Urgent', overviewArg.attention.urgent], ['Needs input', overviewArg.attention.needsInput],
261
+ ['Open questions', overviewArg.attention.openQuestions], ['Review', overviewArg.attention.review],
262
+ ['Ready without an assignee', overviewArg.attention.unassignedReady], ['Stale', overviewArg.attention.stale]];
263
+ for (const [titleArg, groupArg] of groups) {
264
+ lines.push(`\n${titleArg} (${groupArg.tickets.length} of ${groupArg.total}):\n`, ...groupArg.tickets.map((ticketArg) => ` ${summaryLine(ticketArg)}`));
265
+ }
266
+ lines.push('\nChanged last:\n', ...overviewArg.recent.map((ticketArg) => ` ${ticketArg.updatedAt}\t${summaryLine(ticketArg)}`));
267
+ return lines.join('');
268
+ };
269
+
213
270
  export const formatTicketCliResult = (resultArg: unknown, jsonArg: boolean): string => {
214
271
  if (jsonArg) return JSON.stringify(resultArg) + '\n';
215
272
  const result = resultArg as { tickets?: { key: string; columnId: string; title: string; project: string }[];
216
- ticket?: { key: string; columnId: string; title: string; project: string } };
273
+ ticket?: { key: string; columnId: string; title: string; project: string };
274
+ view?: string; total?: number; columns?: Record<string, number>; nextCursor?: string; moved?: true; attention?: unknown };
275
+ if (result.attention !== undefined) return formatTicketOverview(resultArg as ITicketOverview);
217
276
  const tickets = result.tickets;
277
+ if (tickets && result.view !== undefined) {
278
+ return (tickets as ITicketSummary[]).map(summaryLine).join('')
279
+ + `${tickets.length} of ${result.total} (${counts(result.columns ?? {})})\n`
280
+ + (result.moved ? 'The board changed since the first page: a ticket that changed its place may be missing or shown twice.\n' : '')
281
+ + (result.nextCursor ? `Next page: --cursor ${result.nextCursor}\n` : '');
282
+ }
218
283
  return tickets ? tickets.map((ticketArg) => `${ticketArg.key}\t${ticketArg.project}\t${ticketArg.columnId}\t${ticketArg.title}\n`).join('')
219
284
  : JSON.stringify(resultArg, null, 2) + '\n';
220
285
  };
@@ -0,0 +1,214 @@
1
+ import * as plugins from './plugins.js';
2
+ import {
3
+ ticketAutoLabels, ticketColumns, ticketDoneColumns, ticketListPage, ticketOverviewDefaults, ticketPriorities,
4
+ type ITicket, type ITicketOverview, type ITicketOverviewGroup, type ITicketOverviewRequest, type ITicketPageRequest,
5
+ type ITicketSummary, type TTicketColumn, type TTicketPage, type TTicketPageSort, type TTicketPriority,
6
+ } from '../ts_interfaces/tickets.js';
7
+
8
+ /**
9
+ * Paged listings and the board overview, as pure functions over the tickets a listing shows (`TicketStore.visible`,
10
+ * already narrowed by `ticketFilter`). Nothing here reads the store: `TicketStore.perform` hands in the tickets, the
11
+ * board revision and the open-question counts one transaction read.
12
+ */
13
+
14
+ /** A cursor the store refuses: `invalid` is no `nextCursor` of a page, `mismatch` pages another filter, sort or view. */
15
+ export class TicketCursorError extends Error {
16
+ constructor(public readonly code: 'ticket_cursor_invalid' | 'ticket_cursor_mismatch') { super(code); }
17
+ }
18
+
19
+ const priorityRank: Record<TTicketPriority, number> = { urgent: 0, high: 1, normal: 2, low: 3, none: 4 };
20
+ const ticketNumber = (ticketArg: Pick<ITicket, 'key'>): number => Number(ticketArg.key.slice(4));
21
+ const isDone = (ticketArg: Pick<ITicket, 'columnId'>): boolean => ticketDoneColumns.includes(ticketArg.columnId);
22
+
23
+ /**
24
+ * Where a ticket stands in a sort, as numbers compared left to right; the ticket's number ends every key, so no two
25
+ * tickets share one. `board` is the board's own order (column, then position), `updated` and `created` newest first,
26
+ * `priority` urgent first and then the board's order.
27
+ */
28
+ export const ticketSortKey = (ticketArg: ITicket, sortArg: TTicketPageSort): number[] => {
29
+ const column = ticketColumns.indexOf(ticketArg.columnId), number = ticketNumber(ticketArg);
30
+ switch (sortArg) {
31
+ case 'board': return [column, ticketArg.order, number];
32
+ case 'updated': return [-Date.parse(ticketArg.updatedAt), number];
33
+ case 'created': return [-number];
34
+ case 'priority': return [priorityRank[ticketArg.priority], column, ticketArg.order, number];
35
+ }
36
+ };
37
+ const compareKeys = (leftArg: readonly number[], rightArg: readonly number[]): number => {
38
+ for (let index = 0; index < Math.max(leftArg.length, rightArg.length); index += 1) {
39
+ const difference = (leftArg[index] ?? 0) - (rightArg[index] ?? 0);
40
+ if (difference !== 0) return difference;
41
+ }
42
+ return 0;
43
+ };
44
+
45
+ /** What a page narrows by beyond `ticketFilter`'s own filters (mine, project, status, label, text). */
46
+ export const ticketPageNarrows = (requestArg: ITicketPageRequest): (ticketArg: ITicket) => boolean => {
47
+ const statuses = requestArg.statuses && new Set<TTicketColumn>(requestArg.statuses);
48
+ const priorities = requestArg.priorities && new Set<TTicketPriority>(requestArg.priorities);
49
+ const keys = requestArg.keys && new Set(requestArg.keys);
50
+ const since = requestArg.updatedSince === undefined ? undefined : Date.parse(requestArg.updatedSince);
51
+ return (ticketArg) => (
52
+ (!statuses || statuses.has(ticketArg.columnId))
53
+ && (requestArg.open === undefined || requestArg.open !== isDone(ticketArg))
54
+ && (!requestArg.kind || ticketArg.kind === requestArg.kind)
55
+ && (!priorities || priorities.has(ticketArg.priority))
56
+ && (!requestArg.parent || ticketArg.parentId === requestArg.parent)
57
+ && (!requestArg.assignee || ticketArg.assignee?.id === requestArg.assignee || ticketArg.assignee?.sessionId === requestArg.assignee)
58
+ && (!requestArg.unassigned || ticketArg.assignee === undefined)
59
+ && (!keys || keys.has(ticketArg.key))
60
+ && (since === undefined || Date.parse(ticketArg.updatedAt) >= since)
61
+ );
62
+ };
63
+
64
+ /** A ticket without its texts: what a listing or the overview shows of it. Empty fields are left out. */
65
+ export const ticketSummary = (ticketArg: ITicket, openQuestionsArg: number): ITicketSummary => {
66
+ const links: NonNullable<ITicketSummary['links']> = {};
67
+ for (const link of ticketArg.links) links[link.kind] = (links[link.kind] ?? 0) + 1;
68
+ return {
69
+ key: ticketArg.key, revision: ticketArg.revision, project: ticketArg.project, kind: ticketArg.kind, title: ticketArg.title,
70
+ columnId: ticketArg.columnId, priority: ticketArg.priority, updatedAt: ticketArg.updatedAt,
71
+ ...(ticketArg.assignee === undefined ? {} : { assignee: { id: ticketArg.assignee.id, name: ticketArg.assignee.name,
72
+ ...(ticketArg.assignee.sessionId === undefined ? {} : { sessionId: ticketArg.assignee.sessionId }) } }),
73
+ ...(ticketArg.parentId === undefined ? {} : { parentId: ticketArg.parentId }),
74
+ ...(ticketArg.labels.length ? { labels: [...ticketArg.labels] } : {}),
75
+ ...(ticketArg.autoLabels?.length ? { autoLabels: [...ticketArg.autoLabels] } : {}),
76
+ ...(ticketArg.links.length ? { links } : {}),
77
+ ...(ticketArg.releasePlan === undefined ? {} : { releasePlan: { ...ticketArg.releasePlan } }),
78
+ ...(ticketArg.deployPlan === undefined ? {} : { deployPlan: { target: ticketArg.deployPlan.target, version: ticketArg.deployPlan.version } }),
79
+ ...(ticketArg.maintenanceWindow === undefined ? {} : { maintenanceWindow: { from: ticketArg.maintenanceWindow.from,
80
+ to: ticketArg.maintenanceWindow.to, targets: [...ticketArg.maintenanceWindow.targets] } }),
81
+ ...(openQuestionsArg > 0 ? { openQuestions: openQuestionsArg } : {}),
82
+ };
83
+ };
84
+
85
+ interface ITicketPageCursor { filter: string; key: number[]; revision: number }
86
+ const cursorSchema = plugins.z.object({ filter: plugins.z.string().regex(/^[A-Za-z0-9_-]{22}$/u),
87
+ key: plugins.z.array(plugins.z.number().finite()).min(1).max(4), revision: plugins.z.number().int().nonnegative() }).strict();
88
+ /** The digest a cursor carries of what it pages: every filter, the sort and the view, never `limit`. */
89
+ const pageDigest = (requestArg: ITicketPageRequest, viewerArg: string | undefined): string => plugins.crypto.createHash('sha256')
90
+ .update(JSON.stringify([requestArg.mine === true ? viewerArg ?? '' : null, requestArg.project ?? null, requestArg.status ?? null,
91
+ requestArg.label ?? null, requestArg.text ?? null, requestArg.statuses ? [...requestArg.statuses].sort() : null, requestArg.open ?? null,
92
+ requestArg.kind ?? null, requestArg.priorities ? [...requestArg.priorities].sort() : null, requestArg.parent ?? null,
93
+ requestArg.assignee ?? null, requestArg.unassigned === true, requestArg.keys ? [...requestArg.keys].sort() : null,
94
+ requestArg.updatedSince ?? null, requestArg.sort ?? 'board', requestArg.view ?? 'summary'])).digest('base64url').slice(0, 22);
95
+ const encodeCursor = (cursorArg: ITicketPageCursor): string => Buffer.from(JSON.stringify(cursorArg)).toString('base64url');
96
+ const decodeCursor = (cursorArg: string): ITicketPageCursor => {
97
+ try { return cursorSchema.parse(JSON.parse(Buffer.from(cursorArg, 'base64url').toString('utf8'))); }
98
+ catch { throw new TicketCursorError('ticket_cursor_invalid'); }
99
+ };
100
+
101
+ /**
102
+ * One page of the tickets `ticketsArg` holds (those `ticketFilter` kept), narrowed by the request's further filters
103
+ * and sorted: at most `limit` tickets (`ticketListPage`) and no more than `ticketListPage.bytes` of them serialized,
104
+ * which wins over `limit`; a page holds at least one ticket. `total` and `columns` count the whole filtered set, so a
105
+ * page never hides how much there is. A cursor is a position in the sort, not a snapshot: the next page holds the
106
+ * tickets that sort after the last one shown, as the board stands now, and `moved` tells that the board changed since
107
+ * the first page, so a ticket that changed its place meanwhile may be missing or shown twice.
108
+ */
109
+ export const ticketPage = (ticketsArg: ITicket[], requestArg: ITicketPageRequest, revisionArg: number,
110
+ openQuestionsArg: (ticketIdArg: string) => number, viewerArg?: string): TTicketPage => {
111
+ const sort = requestArg.sort ?? 'board', view = requestArg.view ?? 'summary';
112
+ const filter = pageDigest(requestArg, viewerArg);
113
+ const keyed = ticketsArg.filter(ticketPageNarrows(requestArg)).map((ticketArg) => ({ ticket: ticketArg, key: ticketSortKey(ticketArg, sort) }))
114
+ .sort((leftArg, rightArg) => compareKeys(leftArg.key, rightArg.key));
115
+ const columns: TTicketPage['columns'] = {};
116
+ for (const { ticket } of keyed) columns[ticket.columnId] = (columns[ticket.columnId] ?? 0) + 1;
117
+ let start = 0, firstRevision = revisionArg;
118
+ if (requestArg.cursor !== undefined) {
119
+ const cursor = decodeCursor(requestArg.cursor);
120
+ if (cursor.filter !== filter) throw new TicketCursorError('ticket_cursor_mismatch');
121
+ firstRevision = cursor.revision;
122
+ start = keyed.findIndex((entryArg) => compareKeys(entryArg.key, cursor.key) > 0);
123
+ if (start < 0) start = keyed.length;
124
+ }
125
+ const limit = requestArg.limit ?? ticketListPage.default;
126
+ const rows: (ITicket | ITicketSummary)[] = [];
127
+ let bytes = 0, end = start;
128
+ while (end < keyed.length && rows.length < limit) {
129
+ const { ticket } = keyed[end]!;
130
+ const row = view === 'full' ? ticket : ticketSummary(ticket, openQuestionsArg(ticket.id));
131
+ const size = Buffer.byteLength(JSON.stringify(row));
132
+ if (rows.length && bytes + size > ticketListPage.bytes) break;
133
+ rows.push(row); bytes += size; end += 1;
134
+ }
135
+ return {
136
+ view, tickets: rows, total: keyed.length, columns, revision: revisionArg,
137
+ ...(end < keyed.length ? { nextCursor: encodeCursor({ filter, key: keyed[end - 1]!.key, revision: firstRevision }) } : {}),
138
+ ...(firstRevision !== revisionArg ? { moved: true } : {}),
139
+ } as TTicketPage;
140
+ };
141
+
142
+ const group = (ticketsArg: ITicket[], limitArg: number, openQuestionsArg: (ticketIdArg: string) => number): ITicketOverviewGroup => ({
143
+ total: ticketsArg.length, tickets: ticketsArg.slice(0, limitArg).map((ticketArg) => ticketSummary(ticketArg, openQuestionsArg(ticketArg.id))),
144
+ });
145
+ const byBoard = (leftArg: ITicket, rightArg: ITicket): number => compareKeys(ticketSortKey(leftArg, 'board'), ticketSortKey(rightArg, 'board'));
146
+ const byPriority = (leftArg: ITicket, rightArg: ITicket): number => compareKeys(ticketSortKey(leftArg, 'priority'), ticketSortKey(rightArg, 'priority'));
147
+ const columnCounts = (ticketsArg: ITicket[]): Partial<Record<TTicketColumn, number>> => {
148
+ const counts: Partial<Record<TTicketColumn, number>> = {};
149
+ for (const column of ticketColumns) {
150
+ const count = ticketsArg.filter((ticketArg) => ticketArg.columnId === column).length;
151
+ if (count) counts[column] = count;
152
+ }
153
+ return counts;
154
+ };
155
+
156
+ /**
157
+ * The board in one bounded answer, without any ticket's texts: counts by column, priority, AutoLabel, project and
158
+ * assignee, each open epic's progress over its direct children, the tickets that need someone (urgent, needs input,
159
+ * open questions, review, ready without an assignee, stale work) and the newest changes. Every list is cut to
160
+ * `limit` tickets (projects, assignees and epics to `ticketOverviewDefaults.groups`) and carries the count of all it
161
+ * stands for. Stale is in_progress, needs_input or review work nobody changed for `staleDays`, oldest first.
162
+ */
163
+ export const ticketOverview = (ticketsArg: ITicket[], requestArg: ITicketOverviewRequest, revisionArg: number, nowArg: string,
164
+ openQuestionsArg: (ticketIdArg: string) => number): ITicketOverview => {
165
+ const limit = requestArg.limit ?? ticketOverviewDefaults.limit;
166
+ const staleBefore = Date.parse(nowArg) - (requestArg.staleDays ?? ticketOverviewDefaults.staleDays) * 86_400_000;
167
+ const open = ticketsArg.filter((ticketArg) => !isDone(ticketArg));
168
+ const count = <TKey extends string>(keysArg: readonly TKey[], ofArg: (keyArg: TKey) => number): Record<TKey, number> => (
169
+ Object.fromEntries(keysArg.map((keyArg) => [keyArg, ofArg(keyArg)])) as Record<TKey, number>);
170
+ const projects = [...new Set(ticketsArg.map((ticketArg) => ticketArg.project))].map((projectArg) => {
171
+ const own = ticketsArg.filter((ticketArg) => ticketArg.project === projectArg);
172
+ return { project: projectArg, total: own.length, open: own.filter((ticketArg) => !isDone(ticketArg)).length, columns: columnCounts(own) };
173
+ }).sort((leftArg, rightArg) => rightArg.open - leftArg.open || rightArg.total - leftArg.total || leftArg.project.localeCompare(rightArg.project));
174
+ const assigned = new Map<string, ITicket[]>();
175
+ for (const ticket of open) {
176
+ if (!ticket.assignee) continue;
177
+ const id = ticket.assignee.sessionId ?? ticket.assignee.id;
178
+ assigned.set(id, [...(assigned.get(id) ?? []), ticket]);
179
+ }
180
+ const assignees = [...assigned.values()].map((ownArg) => {
181
+ const { id, name, sessionId } = ownArg[0]!.assignee!;
182
+ return { id, name, ...(sessionId === undefined ? {} : { sessionId }), open: ownArg.length, columns: columnCounts(ownArg) };
183
+ }).sort((leftArg, rightArg) => rightArg.open - leftArg.open || leftArg.name.localeCompare(rightArg.name));
184
+ const epics = open.filter((ticketArg) => ticketArg.kind === 'epic').sort(byBoard).map((epicArg) => {
185
+ const children = ticketsArg.filter((ticketArg) => ticketArg.parentId === epicArg.key);
186
+ return { key: epicArg.key, title: epicArg.title, project: epicArg.project, columnId: epicArg.columnId, children: children.length,
187
+ done: children.filter(isDone).length, columns: columnCounts(children) };
188
+ });
189
+ const active = new Set<TTicketColumn>(['in_progress', 'needs_input', 'review']);
190
+ const groups = ticketOverviewDefaults.groups;
191
+ return {
192
+ revision: revisionArg, total: ticketsArg.length, open: open.length,
193
+ columns: count(ticketColumns, (columnArg) => ticketsArg.filter((ticketArg) => ticketArg.columnId === columnArg).length),
194
+ priorities: count(ticketPriorities, (priorityArg) => open.filter((ticketArg) => ticketArg.priority === priorityArg).length),
195
+ autoLabels: count(ticketAutoLabels, (labelArg) => ticketsArg.filter((ticketArg) => ticketArg.autoLabels?.includes(labelArg)).length),
196
+ projects: projects.slice(0, groups), projectsTotal: projects.length,
197
+ assignees: assignees.slice(0, groups), assigneesTotal: assignees.length,
198
+ unassignedOpen: open.filter((ticketArg) => ticketArg.assignee === undefined).length,
199
+ epics: epics.slice(0, groups), epicsTotal: epics.length,
200
+ attention: {
201
+ urgent: group(open.filter((ticketArg) => ticketArg.priority === 'urgent').sort(byBoard), limit, openQuestionsArg),
202
+ needsInput: group(open.filter((ticketArg) => ticketArg.columnId === 'needs_input').sort(byPriority), limit, openQuestionsArg),
203
+ openQuestions: group(open.filter((ticketArg) => openQuestionsArg(ticketArg.id) > 0).sort(byPriority), limit, openQuestionsArg),
204
+ review: group(open.filter((ticketArg) => ticketArg.columnId === 'review').sort(byPriority), limit, openQuestionsArg),
205
+ unassignedReady: group(open.filter((ticketArg) => ticketArg.columnId === 'ready' && ticketArg.assignee === undefined).sort(byPriority),
206
+ limit, openQuestionsArg),
207
+ stale: group(open.filter((ticketArg) => active.has(ticketArg.columnId) && Date.parse(ticketArg.updatedAt) < staleBefore)
208
+ .sort((leftArg, rightArg) => Date.parse(leftArg.updatedAt) - Date.parse(rightArg.updatedAt) || ticketNumber(leftArg) - ticketNumber(rightArg)),
209
+ limit, openQuestionsArg),
210
+ },
211
+ recent: [...ticketsArg].sort((leftArg, rightArg) => compareKeys(ticketSortKey(leftArg, 'updated'), ticketSortKey(rightArg, 'updated')))
212
+ .slice(0, limit).map((ticketArg) => ticketSummary(ticketArg, openQuestionsArg(ticketArg.id))),
213
+ };
214
+ };
@@ -1,6 +1,7 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import {
3
- ticketAutoLabels, ticketColumns, ticketHistoryPage, type TTicketFleetEvent, type TTicketLink, type TTicketOperation, type TTicketRequest,
3
+ ticketAutoLabels, ticketColumns, ticketHistoryPage, ticketListPage, ticketOverviewDefaults, ticketPageSorts, ticketPriorities,
4
+ type TTicketFleetEvent, type TTicketLink, type TTicketOperation, type TTicketRequest,
4
5
  } from '../ts_interfaces/tickets.js';
5
6
  import { fleetDeployTargetIdPattern } from '../ts_interfaces/deployments.js';
6
7
 
@@ -82,6 +83,15 @@ const optionId = plugins.z.string().regex(/^[1-9][0-9]*$/u);
82
83
  const questionOption = plugins.z.object({ label: text(200).trim().min(1), description: text(1000).optional() }).strict();
83
84
  const filters = plugins.z.object({ mine: plugins.z.boolean().optional(), project: identifier.optional(),
84
85
  status: plugins.z.enum(ticketColumns).optional(), label: text(100).min(1).optional(), text: text(1024).optional() }).strict();
86
+ const pageRequest = plugins.z.object({ ...filters.shape,
87
+ statuses: plugins.z.array(plugins.z.enum(ticketColumns)).min(1).max(ticketColumns.length).optional(), open: plugins.z.boolean().optional(),
88
+ kind: kind.optional(), priorities: plugins.z.array(priority).min(1).max(ticketPriorities.length).optional(), parent: ticketId.optional(),
89
+ assignee: identifier.optional(), unassigned: plugins.z.boolean().optional(), keys: plugins.z.array(ticketId).min(1).max(200).optional(),
90
+ updatedSince: instantInput.optional(), sort: plugins.z.enum(ticketPageSorts).optional(), view: plugins.z.enum(['summary', 'full']).optional(),
91
+ limit: plugins.z.number().int().min(1).max(ticketListPage.maximum).optional(), cursor: text(2048).min(1).optional() }).strict();
92
+ const overviewRequest = plugins.z.object({ project: identifier.optional(), mine: plugins.z.boolean().optional(),
93
+ limit: plugins.z.number().int().min(1).max(ticketOverviewDefaults.maximumLimit).optional(),
94
+ staleDays: plugins.z.number().int().min(1).max(365).optional() }).strict();
85
95
  const changes = plugins.z.object({
86
96
  title: text(200).trim().min(1).optional(), description: text(64 * 1024).optional(),
87
97
  priority: priority.optional(), assignee: person.nullable().optional(), parentId: ticketId.nullable().optional(),
@@ -89,7 +99,7 @@ const changes = plugins.z.object({
89
99
  maintenanceWindow: maintenanceWindowInput.nullable().optional(), deployPlan: deployPlanInput.optional(),
90
100
  }).strict().refine((valueArg) => Object.keys(valueArg).length > 0, 'At least one change is required.');
91
101
  export const ticketInputSchemas = {
92
- list: filters, board: filters,
102
+ list: filters, board: filters, page: pageRequest, overview: overviewRequest,
93
103
  search: plugins.z.object({ query: text(1024), label: text(100).min(1).optional() }).strict(),
94
104
  get: plugins.z.object({ ticketId, before: identifier.optional(),
95
105
  limit: plugins.z.number().int().min(1).max(ticketHistoryPage.maximum).optional(), commentId: identifier.optional() }).strict()
@@ -177,8 +187,37 @@ export const assertTicketResponse = (methodArg: string, valueArg: unknown): void
177
187
  permissions: plugins.z.object({ edit: plugins.z.boolean(), move: plugins.z.boolean(),
178
188
  comment: plugins.z.boolean(), createChild: plugins.z.boolean(), ask: plugins.z.boolean(), answer: plugins.z.boolean() }).strict(),
179
189
  autoLabels: plugins.z.array(plugins.z.enum(ticketAutoLabels)) });
190
+ const count = plugins.z.number().int().nonnegative();
191
+ const columnCounts = plugins.z.partialRecord(storedColumn, count);
192
+ const summaryPerson = plugins.z.object({ id: identifier, name: text(200).min(1), sessionId: identifier.optional() }).strict();
193
+ const summary = plugins.z.object({ key: ticketId, revision: count, project: identifier, kind, title: text(200).min(1),
194
+ columnId: storedColumn, priority, updatedAt: plugins.z.iso.datetime(), assignee: summaryPerson.optional(), parentId: ticketId.optional(),
195
+ labels: labels.optional(), autoLabels: plugins.z.array(plugins.z.enum(ticketAutoLabels)).optional(),
196
+ links: plugins.z.partialRecord(plugins.z.enum(['branch', 'commit', 'release', 'affects']), count).optional(),
197
+ releasePlan: releasePlan.optional(), deployPlan: plugins.z.object({ target: deployTargetId, version: identifier }).strict().optional(),
198
+ maintenanceWindow: plugins.z.object({ from: plugins.z.iso.datetime(), to: plugins.z.iso.datetime(),
199
+ targets: plugins.z.array(deployTargetId) }).strict().optional(), openQuestions: count.optional() }).strict();
200
+ const pageBase = { total: count, columns: columnCounts, revision: count, nextCursor: text(2048).min(1).optional(),
201
+ moved: plugins.z.literal(true).optional() };
202
+ const group = plugins.z.object({ total: count, tickets: plugins.z.array(summary) }).strict();
180
203
  const schemas = {
181
204
  list: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),
205
+ page: plugins.z.discriminatedUnion('view', [
206
+ plugins.z.object({ view: plugins.z.literal('summary'), tickets: plugins.z.array(summary), ...pageBase }).strict(),
207
+ plugins.z.object({ view: plugins.z.literal('full'), tickets: plugins.z.array(ticket), ...pageBase }).strict(),
208
+ ]),
209
+ overview: plugins.z.object({ revision: count, total: count, open: count,
210
+ columns: plugins.z.record(storedColumn, count), priorities: plugins.z.record(priority, count),
211
+ autoLabels: plugins.z.record(plugins.z.enum(ticketAutoLabels), count),
212
+ projects: plugins.z.array(plugins.z.object({ project: identifier, total: count, open: count, columns: columnCounts }).strict()),
213
+ projectsTotal: count,
214
+ assignees: plugins.z.array(summaryPerson.extend({ open: count, columns: columnCounts }).strict()), assigneesTotal: count,
215
+ unassignedOpen: count,
216
+ epics: plugins.z.array(plugins.z.object({ key: ticketId, title: text(200).min(1), project: identifier, columnId: storedColumn,
217
+ children: count, done: count, columns: columnCounts }).strict()), epicsTotal: count,
218
+ attention: plugins.z.object({ urgent: group, needsInput: group, openQuestions: group, review: group, unassignedReady: group,
219
+ stale: group }).strict(),
220
+ recent: plugins.z.array(summary) }).strict(),
182
221
  search: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),
183
222
  board: plugins.z.object({ revision: plugins.z.number().int().nonnegative(), columns: plugins.z.array(plugins.z.object({
184
223
  id: storedColumn, title: plugins.z.string(), done: plugins.z.boolean().optional() }).strict()), tickets: plugins.z.array(ticket),
@@ -9,7 +9,8 @@ export const assertWorkerCallerEnrollment = (valueArg: unknown): TWorkerCallerEn
9
9
  throw new Error('Invalid worker enrollment request.');
10
10
  }
11
11
  const keys = Object.hasOwn(valueArg, 'launchId') ? ['bridgePid', 'launchId', 'launchGeneration']
12
- : Object.hasOwn(valueArg, 'challenge') ? ['bridgePid', 'challenge', 'nativeThreadId'] : ['bridgePid', 'nativeThreadId'];
12
+ : Object.hasOwn(valueArg, 'challenge') ? ['bridgePid', 'challenge', 'nativeThreadId']
13
+ : Object.hasOwn(valueArg, 'nativeThreadId') ? ['bridgePid', 'nativeThreadId'] : ['bridgePid'];
13
14
  if (Object.keys(valueArg).length !== keys.length || keys.some(key => !Object.hasOwn(valueArg, key))) {
14
15
  throw new Error('Invalid worker enrollment request.');
15
16
  }
@@ -3,6 +3,8 @@ import type { IConfigurationMcpStdioServer, IFleetClaudeProcess } from '../ts_in
3
3
  import { resolveControllerTerminalAgentExecutable } from './functions.terminalagents.js';
4
4
 
5
5
  export class WorkerCallerProofError extends Error {}
6
+ /** A proof refused because the process changed while it was read: unlike the other refusals, it may pass at the next read. */
7
+ export class WorkerProcessChangedError extends WorkerCallerProofError {}
6
8
 
7
9
  export const isWorkerCallerProofRefusal = (errorArg: unknown): boolean => (
8
10
  errorArg instanceof WorkerCallerProofError
@@ -213,6 +215,38 @@ export const verifyClaudeWorkerProcess = async (
213
215
  return snapshot;
214
216
  };
215
217
 
218
+ /**
219
+ * The process `processArg` (PID and start), proved to run an installed Claude Code release: its executable is a
220
+ * regular file of the controller's user in the directory of `releaseArg`, the release `claude` resolves to now, and is
221
+ * the very file the process runs. Claude Code installs every release as a file of its own there (`versions/<release>`)
222
+ * and moves its launcher to the newest, while a running job keeps the release it started on; a release file that was
223
+ * removed or replaced since the process started is refused. A local read of the process and two file stats: the
224
+ * controller proves it before it asks the fleet's inventory which job the process runs.
225
+ */
226
+ export const verifyClaudeReleaseProcess = async (
227
+ processArg: Pick<IFleetClaudeProcess, 'pid' | 'startTicks'>,
228
+ releaseArg: string,
229
+ ): Promise<IWorkerProcessSnapshot> => {
230
+ if (!/^\d+$/u.test(processArg.startTicks) || !plugins.path.isAbsolute(releaseArg)) {
231
+ throw new WorkerCallerProofError('Invalid Claude launch observation.');
232
+ }
233
+ const snapshot = await readWorkerProcessSnapshot(processArg.pid);
234
+ if (snapshot.startTicks !== processArg.startTicks || !plugins.path.isAbsolute(snapshot.executable)
235
+ || plugins.path.dirname(snapshot.executable) !== plugins.path.dirname(releaseArg)) {
236
+ throw new WorkerCallerProofError('The Claude process does not run an installed Claude Code release.');
237
+ }
238
+ const [installed, running] = await Promise.all([plugins.fs.promises.lstat(snapshot.executable, { bigint: true }),
239
+ plugins.fs.promises.stat(`/proc/${processArg.pid}/exe`, { bigint: true })]);
240
+ if (!installed.isFile() || installed.uid !== BigInt(process.getuid?.() ?? -1)
241
+ || installed.dev !== running.dev || installed.ino !== running.ino) {
242
+ throw new WorkerCallerProofError('The Claude process does not run an installed Claude Code release.');
243
+ }
244
+ if (!workerSnapshotsEqual(snapshot, await readWorkerProcessSnapshot(processArg.pid))) {
245
+ throw new WorkerProcessChangedError('The Claude launch observation no longer matches its process.');
246
+ }
247
+ return snapshot;
248
+ };
249
+
216
250
  export const readWorkerUnixSocketOwner = async (socketPathArg: string): Promise<IWorkerProcessSnapshot> => {
217
251
  const table = await plugins.fs.promises.readFile('/proc/net/unix', 'utf8');
218
252
  const rows = table.split('\n').slice(1).map(line => line.trim().split(/\s+/u))