@giantswarm-io/pro 1.7.3 → 1.7.5

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.7.3",
3
+ "version": "1.7.5",
4
4
  "description": "Core library and MCP server for managing Giant Swarm's roadmap and customer project boards",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/index.js CHANGED
@@ -19,10 +19,12 @@ export {
19
19
  resolveBoardId
20
20
  } from './lib/project.js';
21
21
 
22
- // Project items: list/filter, detail, field mutation
22
+ // Project items: list/filter, detail, batched item -> issue resolution,
23
+ // field mutation
23
24
  export {
24
25
  listItems,
25
26
  getItemByID,
27
+ resolveItemIssues,
26
28
  updateItemField
27
29
  } from './lib/items.js';
28
30
 
@@ -47,10 +49,16 @@ export {
47
49
  // Bulk issue comment fetching (board items -> underlying issue comments)
48
50
  export {
49
51
  listIssueCommentsForItems,
50
- resolveItemIssueRefs,
51
52
  fetchIssueComments
52
53
  } from './lib/comments.js';
53
54
 
55
+ // Issue timeline (REST): compact activity events for an issue
56
+ export {
57
+ getIssueTimeline,
58
+ compactTimelineEvent,
59
+ MAX_TIMELINE_EVENTS
60
+ } from './lib/timeline.js';
61
+
54
62
  // Low-level GitHub clients for anything not covered above
55
63
  export { graphQLWithAuth, fetchPaginated } from './lib/api.js';
56
64
  export { getOctokit, parseIssueRef, resolveIssueId } from './lib/rest-api.js';
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Bulk Issue Comments Module
3
3
  *
4
- * Resolves GitHub Projects V2 items to their underlying issues (via a single
5
- * batched GraphQL `nodes(ids:)` lookup) and fetches each issue's comments via
4
+ * Resolves GitHub Projects V2 items to their underlying issues (via the
5
+ * batched resolveItemIssues helper in items.js) and fetches each issue's comments via
6
6
  * the REST API, which supports `since` filtering natively. Bounds response
7
7
  * size by capping the number of items per call, the number of REST pages
8
8
  * fetched per issue (when `since` is absent), the number of comments kept
@@ -20,9 +20,8 @@
20
20
  * common (unedited) case.
21
21
  */
22
22
 
23
- import { graphQLWithAuth } from './api.js';
24
23
  import { getOctokit } from './rest-api.js';
25
- import { ITEM_ISSUE_REFS_QUERY } from './project.js';
24
+ import { resolveItemIssues } from './items.js';
26
25
  import { logger } from './logger.js';
27
26
 
28
27
  /** Maximum number of itemIds accepted in a single list_issue_comments call. */
@@ -55,35 +54,6 @@ function truncateBody(body) {
55
54
  return `${body.slice(0, MAX_COMMENT_BODY_LENGTH)}\n\n[... truncated ${cut} characters ...]`;
56
55
  }
57
56
 
58
- /**
59
- * Resolve a batch of project item IDs to their underlying issue's
60
- * owner/repo/number in a single batched GraphQL request.
61
- * @param {string[]} itemIds - Project item (PVTI) IDs
62
- * @param {string} [token] - Optional per-request GitHub token
63
- * @returns {Promise<Map<string, {owner: string, repo: string, number: number}|null>>}
64
- * Map from itemId to its issue ref, or null when the item doesn't resolve
65
- * to an accessible Issue.
66
- */
67
- export async function resolveItemIssueRefs(itemIds, token) {
68
- const result = await graphQLWithAuth(ITEM_ISSUE_REFS_QUERY, { ids: itemIds }, token);
69
- const nodes = result?.nodes || [];
70
- const refs = new Map();
71
-
72
- itemIds.forEach((itemId, i) => {
73
- const node = nodes[i];
74
- const nameWithOwner = node?.content?.repository?.nameWithOwner;
75
- const number = node?.content?.number;
76
- if (!node || !nameWithOwner || !number) {
77
- refs.set(itemId, null);
78
- return;
79
- }
80
- const [owner, repo] = nameWithOwner.split('/');
81
- refs.set(itemId, { owner, repo, number });
82
- });
83
-
84
- return refs;
85
- }
86
-
87
57
  /**
88
58
  * Fetch comments for a single issue via REST. `since` is applied server-side
89
59
  * (native GitHub support). The per-issue comments endpoint only returns
@@ -183,7 +153,7 @@ export async function listIssueCommentsForItems({ itemIds, since, maxPerIssue, t
183
153
  ? Math.floor(maxPerIssue)
184
154
  : DEFAULT_MAX_PER_ISSUE;
185
155
 
186
- const refs = await resolveItemIssueRefs(itemIds, token);
156
+ const refs = await resolveItemIssues(itemIds, token);
187
157
 
188
158
  const results = [];
189
159
  for (const itemId of itemIds) {
package/src/lib/items.js CHANGED
@@ -2,7 +2,8 @@
2
2
  * Items Management Module
3
3
  *
4
4
  * Provides functions to list, filter, and update GitHub Project V2 items
5
- * on a given project board. All functions return data directly
5
+ * on a given project board, and to resolve items to their underlying issues
6
+ * (see resolveItemIssues). All functions return data directly
6
7
  * without console output.
7
8
  */
8
9
 
@@ -10,7 +11,9 @@ import { fetchPaginated, graphQLWithAuth } from './api.js';
10
11
  import {
11
12
  LIST_ITEMS_QUERY,
12
13
  ISSUE_DETAIL_QUERY,
13
- UPDATE_ITEM_FIELD_MUTATION
14
+ ITEM_ISSUE_REFS_QUERY,
15
+ UPDATE_ITEM_FIELD_MUTATION,
16
+ CLEAR_ITEM_FIELD_MUTATION
14
17
  } from './project.js';
15
18
  import { listFields, findMatchingOption } from './fields.js';
16
19
  import { logger } from './logger.js';
@@ -107,6 +110,44 @@ export async function getItemByID(itemId, token) {
107
110
  return item;
108
111
  }
109
112
 
113
+ /**
114
+ * Resolve a batch of project item IDs to their underlying issues in a single
115
+ * batched GraphQL `nodes(ids:)` request (single item = array of one). This is
116
+ * THE item -> issue resolution mechanism: consumers that only need the issue
117
+ * ref (node ID, repo, number, visibility) should use this rather than the
118
+ * full-payload getItemByID detail fetch.
119
+ * @param {string[]} itemIds - Project item (PVTI) IDs
120
+ * @param {string} [token] - Optional per-request GitHub token
121
+ * @returns {Promise<Map<string, {issueId: string, owner: string, repo: string, number: number, isPrivate: boolean, nameWithOwner: string}|null>>}
122
+ * Map from itemId to its issue ref, or null when the item doesn't resolve
123
+ * to an accessible Issue (e.g. draft, deleted, or inaccessible content).
124
+ */
125
+ export async function resolveItemIssues(itemIds, token) {
126
+ const result = await graphQLWithAuth(ITEM_ISSUE_REFS_QUERY, { ids: itemIds }, token);
127
+ const nodes = result?.nodes || [];
128
+ const refs = new Map();
129
+
130
+ itemIds.forEach((itemId, i) => {
131
+ const content = nodes[i]?.content;
132
+ const nameWithOwner = content?.repository?.nameWithOwner;
133
+ if (!content?.id || !nameWithOwner || !content.number) {
134
+ refs.set(itemId, null);
135
+ return;
136
+ }
137
+ const [owner, repo] = nameWithOwner.split('/');
138
+ refs.set(itemId, {
139
+ issueId: content.id,
140
+ owner,
141
+ repo,
142
+ number: content.number,
143
+ isPrivate: content.repository.isPrivate,
144
+ nameWithOwner
145
+ });
146
+ });
147
+
148
+ return refs;
149
+ }
150
+
110
151
  /**
111
152
  * Derive a GitHub Projects query key from a field name.
112
153
  * E.g. "Working Group" -> "working-group", "SIG" -> "sig", "Team" -> "team"
@@ -448,3 +489,20 @@ export async function updateItemField(itemId, fieldId, value, boardId, token) {
448
489
  value
449
490
  }, token);
450
491
  }
492
+
493
+ /**
494
+ * Clear (unset) a field value directly via GraphQL mutation.
495
+ * Works uniformly for single-select, iteration, and date fields.
496
+ * @param {string} itemId - ID of the item to update
497
+ * @param {string} fieldId - ID of the field to clear
498
+ * @param {string} boardId - The GitHub project node ID
499
+ * @param {string} [token] - Optional per-request GitHub token
500
+ * @returns {Promise<Object>} - Clear result
501
+ */
502
+ export async function clearItemField(itemId, fieldId, boardId, token) {
503
+ return await graphQLWithAuth(CLEAR_ITEM_FIELD_MUTATION, {
504
+ projectId: boardId,
505
+ itemId: itemId,
506
+ fieldId: fieldId
507
+ }, token);
508
+ }
@@ -6,7 +6,7 @@
6
6
  * events for the issue underlying a project board item.
7
7
  */
8
8
 
9
- import { getItemByID } from '../items.js';
9
+ import { resolveItemIssues } from '../items.js';
10
10
  import { getIssueTimeline, MAX_TIMELINE_EVENTS } from '../timeline.js';
11
11
  import { logger } from '../logger.js';
12
12
 
@@ -58,17 +58,16 @@ export async function handleGetIssueTimeline(args, extra) {
58
58
  itemId: args.itemId, since: args.since, until: args.until, eventTypes: args.eventTypes
59
59
  });
60
60
 
61
- const item = await getItemByID(args.itemId, token);
62
- if (!item.repository?.nameWithOwner || !item.number) {
61
+ const issue = (await resolveItemIssues([args.itemId], token)).get(args.itemId);
62
+ if (!issue) {
63
63
  return { error: `Could not resolve item '${args.itemId}' to an underlying issue.` };
64
64
  }
65
- const [owner, repo] = item.repository.nameWithOwner.split('/');
66
65
 
67
66
  const result = await getIssueTimeline(
68
67
  {
69
- owner,
70
- repo,
71
- issue_number: item.number,
68
+ owner: issue.owner,
69
+ repo: issue.repo,
70
+ issue_number: issue.number,
72
71
  since: args.since || null,
73
72
  until: args.until || null,
74
73
  eventTypes: args.eventTypes || null
@@ -14,10 +14,10 @@
14
14
  * - list_issue_comments: Fetch comments across multiple board items in one call
15
15
  */
16
16
 
17
- import { listItems, getItemByID, updateItemField } from '../items.js';
17
+ import { listItems, getItemByID, resolveItemIssues, updateItemField, clearItemField } from '../items.js';
18
18
  import { findFieldByName, findMatchingOption, findMatchingIteration } from '../fields.js';
19
19
  import { graphQLWithAuth } from '../api.js';
20
- import { findMissingLabels, addLabelsToIssue, removeLabelFromIssue } from '../rest-api.js';
20
+ import { findMissingLabels, listIssueLabels, addLabelsToIssue, removeLabelFromIssue } from '../rest-api.js';
21
21
  import {
22
22
  resolveBoardId,
23
23
  DEFAULT_BOARD,
@@ -29,7 +29,6 @@ import {
29
29
  ISSUE_NODE_ID_QUERY,
30
30
  UPDATE_ITEM_FIELD_MUTATION,
31
31
  USER_ID_QUERY,
32
- ITEM_ISSUE_ID_QUERY,
33
32
  CLOSE_ISSUE_MUTATION,
34
33
  REOPEN_ISSUE_MUTATION,
35
34
  ADD_COMMENT_MUTATION
@@ -56,16 +55,16 @@ function extractToken(extra) {
56
55
  }
57
56
 
58
57
  /**
59
- * Resolve a project item ID to its underlying GitHub issue (id, number, state, url,
60
- * and repository visibility).
58
+ * Resolve a single project item ID to its underlying issue ref via the
59
+ * batched resolveItemIssues helper, throwing when the item doesn't resolve.
61
60
  * @param {string} itemId - The project item ID
62
61
  * @param {string} [token] - Optional per-request GitHub token
63
- * @returns {Promise<{id: string, number: number, state: string, url: string, repository: {isPrivate: boolean, nameWithOwner: string}}>}
62
+ * @returns {Promise<{issueId: string, owner: string, repo: string, number: number, isPrivate: boolean, nameWithOwner: string}>}
64
63
  */
65
- async function resolveItemIssueId(itemId, token) {
66
- const result = await graphQLWithAuth(ITEM_ISSUE_ID_QUERY, { itemId }, token);
67
- const issue = result?.node?.content;
68
- if (!issue?.id) {
64
+ async function resolveSingleItemIssue(itemId, token) {
65
+ const refs = await resolveItemIssues([itemId], token);
66
+ const issue = refs.get(itemId);
67
+ if (!issue) {
69
68
  throw new Error(`Could not resolve an underlying issue for item '${itemId}'`);
70
69
  }
71
70
  return issue;
@@ -249,7 +248,7 @@ export async function handleGetIssueDetails(args, extra) {
249
248
 
250
249
  export const updateIssueFieldTool = {
251
250
  name: 'update_issue_field',
252
- description: 'Update a field value for an issue on a project board. Supports single-select fields (Status, Kind, Team, etc.) and iteration fields (Quarter). Also supports date fields (Start Date, Target Date) when a specific date is known. The server resolves field and option names to internal IDs automatically.',
251
+ description: 'Update a field value for an issue on a project board. Supports single-select fields (Status, Kind, Team, etc.) and iteration fields (Quarter). Also supports date fields (Start Date, Target Date) when a specific date is known. The server resolves field and option names to internal IDs automatically. To clear/unset a field instead of setting it, pass `clear: true` (and omit `value`) -- this works for single-select, iteration, and date fields.',
253
252
  inputSchema: {
254
253
  type: 'object',
255
254
  properties: {
@@ -263,7 +262,11 @@ export const updateIssueFieldTool = {
263
262
  },
264
263
  value: {
265
264
  type: 'string',
266
- description: 'The value to set. For single-select/iteration fields: option name with case-insensitive matching (e.g. "Q2 2026"). For date fields: "YYYY-MM-DD" format.'
265
+ description: 'The value to set. For single-select/iteration fields: option name with case-insensitive matching (e.g. "Q2 2026"). For date fields: "YYYY-MM-DD" format. Required unless `clear` is true.'
266
+ },
267
+ clear: {
268
+ type: 'boolean',
269
+ description: 'Set to true to clear/unset the field value instead of setting it (e.g. remove an item\'s Quarter). When true, `value` is ignored. Works for single-select, iteration, and date fields.'
267
270
  },
268
271
  board: {
269
272
  type: 'string',
@@ -271,7 +274,7 @@ export const updateIssueFieldTool = {
271
274
  description: 'Which board the item belongs to. Defaults to "roadmap".'
272
275
  }
273
276
  },
274
- required: ['itemId', 'fieldName', 'value']
277
+ required: ['itemId', 'fieldName']
275
278
  }
276
279
  };
277
280
 
@@ -289,6 +292,30 @@ export async function handleUpdateIssueField(args, extra) {
289
292
  };
290
293
  }
291
294
 
295
+ // Clear path -- clearProjectV2ItemFieldValue takes only the field ID and
296
+ // works uniformly across single-select, iteration, and date fields, so it
297
+ // short-circuits before the per-type value resolution below.
298
+ if (args.clear === true) {
299
+ await clearItemField(args.itemId, field.id, boardId, token);
300
+ return {
301
+ content: [{
302
+ type: 'text',
303
+ text: JSON.stringify({
304
+ success: true,
305
+ itemId: args.itemId,
306
+ field: args.fieldName,
307
+ cleared: true
308
+ })
309
+ }]
310
+ };
311
+ }
312
+
313
+ if (typeof args.value !== 'string' || args.value.trim() === '') {
314
+ return {
315
+ error: `A value is required to update field '${args.fieldName}'. Pass a value, or set clear: true to unset the field.`
316
+ };
317
+ }
318
+
292
319
  let value;
293
320
  let resolvedName;
294
321
 
@@ -711,18 +738,18 @@ export async function handleCloseIssue(args, extra) {
711
738
  return { error: `Invalid stateReason '${args.stateReason}'. Must be "completed" or "not_planned".` };
712
739
  }
713
740
 
714
- const issue = await resolveItemIssueId(args.itemId, token);
741
+ const issue = await resolveSingleItemIssue(args.itemId, token);
715
742
 
716
743
  if (args.comment) {
717
- if (issue.repository?.isPrivate === false && args.confirmPublicSafe !== true) {
744
+ if (issue.isPrivate === false && args.confirmPublicSafe !== true) {
718
745
  return {
719
- error: `Posting a comment to ${issue.repository.nameWithOwner} (public) requires confirmPublicSafe=true to reduce accidental disclosure of internal or customer-specific information.`
746
+ error: `Posting a comment to ${issue.nameWithOwner} (public) requires confirmPublicSafe=true to reduce accidental disclosure of internal or customer-specific information.`
720
747
  };
721
748
  }
722
- await graphQLWithAuth(ADD_COMMENT_MUTATION, { subjectId: issue.id, body: args.comment }, token);
749
+ await graphQLWithAuth(ADD_COMMENT_MUTATION, { subjectId: issue.issueId, body: args.comment }, token);
723
750
  }
724
751
 
725
- const result = await graphQLWithAuth(CLOSE_ISSUE_MUTATION, { issueId: issue.id, stateReason }, token);
752
+ const result = await graphQLWithAuth(CLOSE_ISSUE_MUTATION, { issueId: issue.issueId, stateReason }, token);
726
753
  const closed = result.closeIssue.issue;
727
754
 
728
755
  return {
@@ -776,18 +803,18 @@ export async function handleReopenIssue(args, extra) {
776
803
  const token = extractToken(extra);
777
804
  logger.info('MCP: Reopening issue', { itemId: args.itemId });
778
805
 
779
- const issue = await resolveItemIssueId(args.itemId, token);
806
+ const issue = await resolveSingleItemIssue(args.itemId, token);
780
807
 
781
808
  if (args.comment) {
782
- if (issue.repository?.isPrivate === false && args.confirmPublicSafe !== true) {
809
+ if (issue.isPrivate === false && args.confirmPublicSafe !== true) {
783
810
  return {
784
- error: `Posting a comment to ${issue.repository.nameWithOwner} (public) requires confirmPublicSafe=true to reduce accidental disclosure of internal or customer-specific information.`
811
+ error: `Posting a comment to ${issue.nameWithOwner} (public) requires confirmPublicSafe=true to reduce accidental disclosure of internal or customer-specific information.`
785
812
  };
786
813
  }
787
- await graphQLWithAuth(ADD_COMMENT_MUTATION, { subjectId: issue.id, body: args.comment }, token);
814
+ await graphQLWithAuth(ADD_COMMENT_MUTATION, { subjectId: issue.issueId, body: args.comment }, token);
788
815
  }
789
816
 
790
- const result = await graphQLWithAuth(REOPEN_ISSUE_MUTATION, { issueId: issue.id }, token);
817
+ const result = await graphQLWithAuth(REOPEN_ISSUE_MUTATION, { issueId: issue.issueId }, token);
791
818
  const reopened = result.reopenIssue.issue;
792
819
 
793
820
  return {
@@ -853,19 +880,19 @@ export async function handleUpdateIssueLabels(args, extra) {
853
880
  const token = extractToken(extra);
854
881
  logger.info('MCP: Updating issue labels', { itemId: args.itemId, addLabels, removeLabels });
855
882
 
856
- const item = await getItemByID(args.itemId, token);
857
- if (!item.repository?.nameWithOwner || !item.number) {
883
+ const issue = (await resolveItemIssues([args.itemId], token)).get(args.itemId);
884
+ if (!issue) {
858
885
  return { error: `Could not resolve the underlying issue for item '${args.itemId}'.` };
859
886
  }
860
- const [owner, repo] = item.repository.nameWithOwner.split('/');
861
- const issueNumber = item.number;
887
+ const { owner, repo, number: issueNumber } = issue;
862
888
 
863
889
  // Snapshot of labels currently on the issue, used below to report which
864
890
  // requested removals actually changed anything (removeLabelFromIssue
865
891
  // swallows a 404 whether the label was never applied or never existed,
866
892
  // so this is the only way to distinguish an effective removal from a
867
893
  // no-op).
868
- const currentLabels = new Set((item.labels || []).map(l => l.toLowerCase()));
894
+ const issueLabels = await listIssueLabels(owner, repo, issueNumber, token);
895
+ const currentLabels = new Set(issueLabels.map(l => l.toLowerCase()));
869
896
 
870
897
  // Validate additions exist in the repo BEFORE mutating anything -- GitHub's
871
898
  // add-labels endpoint would otherwise silently create missing labels.
@@ -237,6 +237,22 @@ mutation UpdateProjectV2ItemField($projectId: ID!, $itemId: ID!, $fieldId: ID!,
237
237
  }
238
238
  `;
239
239
 
240
+ const CLEAR_ITEM_FIELD_MUTATION = `
241
+ mutation ClearProjectV2ItemField($projectId: ID!, $itemId: ID!, $fieldId: ID!) {
242
+ clearProjectV2ItemFieldValue(
243
+ input: {
244
+ projectId: $projectId,
245
+ itemId: $itemId,
246
+ fieldId: $fieldId
247
+ }
248
+ ) {
249
+ projectV2Item {
250
+ id
251
+ }
252
+ }
253
+ }
254
+ `;
255
+
240
256
  const ISSUE_DETAIL_QUERY = `
241
257
  query($id: ID!) {
242
258
  node(id: $id) {
@@ -396,41 +412,21 @@ const USER_ID_QUERY = `
396
412
  `;
397
413
 
398
414
  // Batched lookup: resolve a list of ProjectV2Item IDs to their underlying
399
- // issue's repository + number in a single round trip, using GitHub's
415
+ // issue's node ID, repository + number in a single round trip, using GitHub's
400
416
  // root-level `nodes(ids:)` query. The response array is in the same order
401
417
  // as the requested `ids` (entries are null for items that don't resolve to
402
- // an Issue, e.g. deleted or inaccessible content).
418
+ // an Issue, e.g. deleted or inaccessible content). Includes the repository's
419
+ // visibility so callers can gate free-text writes (e.g. comments) to public
420
+ // repos behind an explicit confirmation.
403
421
  const ITEM_ISSUE_REFS_QUERY = `
404
422
  query GetItemIssueRefs($ids: [ID!]!) {
405
423
  nodes(ids: $ids) {
406
424
  ... on ProjectV2Item {
407
425
  id
408
- content {
409
- ... on Issue {
410
- number
411
- repository {
412
- nameWithOwner
413
- }
414
- }
415
- }
416
- }
417
- }
418
- }
419
- `;
420
-
421
- // Query to resolve the underlying issue node ID for a project item, including
422
- // the repository's visibility so callers can gate free-text writes (e.g. comments)
423
- // to public repos behind an explicit confirmation.
424
- const ITEM_ISSUE_ID_QUERY = `
425
- query GetItemIssueId($itemId: ID!) {
426
- node(id: $itemId) {
427
- ... on ProjectV2Item {
428
426
  content {
429
427
  ... on Issue {
430
428
  id
431
429
  number
432
- state
433
- url
434
430
  repository {
435
431
  isPrivate
436
432
  nameWithOwner
@@ -492,6 +488,7 @@ export {
492
488
  LIST_ITEMS_OVERVIEW_QUERY,
493
489
  LIST_FIELDS_QUERY,
494
490
  UPDATE_ITEM_FIELD_MUTATION,
491
+ CLEAR_ITEM_FIELD_MUTATION,
495
492
  ISSUE_DETAIL_QUERY,
496
493
  CREATE_ISSUE_MUTATION,
497
494
  ADD_ITEM_TO_PROJECT_MUTATION,
@@ -499,7 +496,6 @@ export {
499
496
  ISSUE_NODE_ID_QUERY,
500
497
  USER_ID_QUERY,
501
498
  ITEM_ISSUE_REFS_QUERY,
502
- ITEM_ISSUE_ID_QUERY,
503
499
  CLOSE_ISSUE_MUTATION,
504
500
  REOPEN_ISSUE_MUTATION,
505
501
  ADD_COMMENT_MUTATION
@@ -172,6 +172,23 @@ export async function findMissingLabels(owner, repo, labels, token) {
172
172
  return missing;
173
173
  }
174
174
 
175
+ /**
176
+ * List the label names currently applied to an issue via REST.
177
+ * Used to snapshot an issue's labels before mutating them, so callers can
178
+ * report which add/remove requests actually changed anything.
179
+ *
180
+ * @param {string} owner - Repository owner
181
+ * @param {string} repo - Repository name
182
+ * @param {number} issue_number - Issue number
183
+ * @param {string} [token] - Optional per-request GitHub token
184
+ * @returns {Promise<string[]>} - Names of labels currently on the issue
185
+ */
186
+ export async function listIssueLabels(owner, repo, issue_number, token) {
187
+ const client = getOctokit(token);
188
+ const { data } = await client.rest.issues.listLabelsOnIssue({ owner, repo, issue_number, per_page: 100 });
189
+ return data.map(l => l.name);
190
+ }
191
+
175
192
  /**
176
193
  * Add labels to an issue via REST.
177
194
  * Callers should validate labels with findMissingLabels first to avoid
package/src/lib/utils.js CHANGED
@@ -6,7 +6,15 @@
6
6
 
7
7
  /**
8
8
  * Normalize a field value for consistent comparison.
9
- * Converts to lowercase, removes emojis and special characters, trims whitespace.
9
+ * Converts to lowercase, treats separators as equivalent, strips punctuation
10
+ * and emojis while preserving letters (including accented/Unicode letters) and
11
+ * numbers, and trims whitespace.
12
+ *
13
+ * Separators (`/`, `-`, `_`, and whitespace runs) all collapse to a single
14
+ * space so that values naming the same option/iteration but using different
15
+ * separator styles compare equal, e.g. "Q4/2026", "Q4-2026", "Q4_2026", and
16
+ * "Q4 2026" all normalize to "q4 2026". This is applied symmetrically to both
17
+ * the caller value and the board's option/iteration titles.
10
18
  *
11
19
  * @param {string} value - Field value to normalize
12
20
  * @returns {string} - Normalized field value for comparison
@@ -14,10 +22,12 @@
14
22
  export function normalizeFieldValue(value) {
15
23
  if (!value) return '';
16
24
  return value.toLowerCase()
17
- // Remove emojis and special unicode characters
18
- .replace(/[\u{1F600}-\u{1F64F}|\u{1F300}-\u{1F5FF}|\u{1F680}-\u{1F6FF}|\u{2600}-\u{26FF}|\u{2700}-\u{27BF}|\u{1F900}-\u{1F9FF}|\u{1F1E0}-\u{1F1FF}|\u{1F100}-\u{1F1FF}|\u{E000}-\u{F8FF}]/gu, '')
19
- // Remove other special characters but keep alphanumeric and spaces
20
- .replace(/[^\w\s]/g, '')
21
- // Trim extra whitespace
25
+ // Treat slash, hyphen, underscore, and whitespace as interchangeable separators
26
+ .replace(/[/\-\s_]+/g, ' ')
27
+ // Keep letters (incl. accented/Unicode), numbers, and spaces;
28
+ // strip everything else -- punctuation, emojis, and other symbols.
29
+ .replace(/[^\p{L}\p{N}\s]/gu, '')
30
+ // Collapse any whitespace introduced above and trim
31
+ .replace(/\s+/g, ' ')
22
32
  .trim();
23
33
  }