@giantswarm-io/pro 1.7.4 → 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.4",
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,6 +11,7 @@ import { fetchPaginated, graphQLWithAuth } from './api.js';
10
11
  import {
11
12
  LIST_ITEMS_QUERY,
12
13
  ISSUE_DETAIL_QUERY,
14
+ ITEM_ISSUE_REFS_QUERY,
13
15
  UPDATE_ITEM_FIELD_MUTATION,
14
16
  CLEAR_ITEM_FIELD_MUTATION
15
17
  } from './project.js';
@@ -108,6 +110,44 @@ export async function getItemByID(itemId, token) {
108
110
  return item;
109
111
  }
110
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
+
111
151
  /**
112
152
  * Derive a GitHub Projects query key from a field name.
113
153
  * E.g. "Working Group" -> "working-group", "SIG" -> "sig", "Team" -> "team"
@@ -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, clearItemField } 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;
@@ -739,18 +738,18 @@ export async function handleCloseIssue(args, extra) {
739
738
  return { error: `Invalid stateReason '${args.stateReason}'. Must be "completed" or "not_planned".` };
740
739
  }
741
740
 
742
- const issue = await resolveItemIssueId(args.itemId, token);
741
+ const issue = await resolveSingleItemIssue(args.itemId, token);
743
742
 
744
743
  if (args.comment) {
745
- if (issue.repository?.isPrivate === false && args.confirmPublicSafe !== true) {
744
+ if (issue.isPrivate === false && args.confirmPublicSafe !== true) {
746
745
  return {
747
- 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.`
748
747
  };
749
748
  }
750
- 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);
751
750
  }
752
751
 
753
- 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);
754
753
  const closed = result.closeIssue.issue;
755
754
 
756
755
  return {
@@ -804,18 +803,18 @@ export async function handleReopenIssue(args, extra) {
804
803
  const token = extractToken(extra);
805
804
  logger.info('MCP: Reopening issue', { itemId: args.itemId });
806
805
 
807
- const issue = await resolveItemIssueId(args.itemId, token);
806
+ const issue = await resolveSingleItemIssue(args.itemId, token);
808
807
 
809
808
  if (args.comment) {
810
- if (issue.repository?.isPrivate === false && args.confirmPublicSafe !== true) {
809
+ if (issue.isPrivate === false && args.confirmPublicSafe !== true) {
811
810
  return {
812
- 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.`
813
812
  };
814
813
  }
815
- 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);
816
815
  }
817
816
 
818
- const result = await graphQLWithAuth(REOPEN_ISSUE_MUTATION, { issueId: issue.id }, token);
817
+ const result = await graphQLWithAuth(REOPEN_ISSUE_MUTATION, { issueId: issue.issueId }, token);
819
818
  const reopened = result.reopenIssue.issue;
820
819
 
821
820
  return {
@@ -881,19 +880,19 @@ export async function handleUpdateIssueLabels(args, extra) {
881
880
  const token = extractToken(extra);
882
881
  logger.info('MCP: Updating issue labels', { itemId: args.itemId, addLabels, removeLabels });
883
882
 
884
- const item = await getItemByID(args.itemId, token);
885
- if (!item.repository?.nameWithOwner || !item.number) {
883
+ const issue = (await resolveItemIssues([args.itemId], token)).get(args.itemId);
884
+ if (!issue) {
886
885
  return { error: `Could not resolve the underlying issue for item '${args.itemId}'.` };
887
886
  }
888
- const [owner, repo] = item.repository.nameWithOwner.split('/');
889
- const issueNumber = item.number;
887
+ const { owner, repo, number: issueNumber } = issue;
890
888
 
891
889
  // Snapshot of labels currently on the issue, used below to report which
892
890
  // requested removals actually changed anything (removeLabelFromIssue
893
891
  // swallows a 404 whether the label was never applied or never existed,
894
892
  // so this is the only way to distinguish an effective removal from a
895
893
  // no-op).
896
- 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()));
897
896
 
898
897
  // Validate additions exist in the repo BEFORE mutating anything -- GitHub's
899
898
  // add-labels endpoint would otherwise silently create missing labels.
@@ -412,41 +412,21 @@ const USER_ID_QUERY = `
412
412
  `;
413
413
 
414
414
  // Batched lookup: resolve a list of ProjectV2Item IDs to their underlying
415
- // 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
416
416
  // root-level `nodes(ids:)` query. The response array is in the same order
417
417
  // as the requested `ids` (entries are null for items that don't resolve to
418
- // 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.
419
421
  const ITEM_ISSUE_REFS_QUERY = `
420
422
  query GetItemIssueRefs($ids: [ID!]!) {
421
423
  nodes(ids: $ids) {
422
424
  ... on ProjectV2Item {
423
425
  id
424
- content {
425
- ... on Issue {
426
- number
427
- repository {
428
- nameWithOwner
429
- }
430
- }
431
- }
432
- }
433
- }
434
- }
435
- `;
436
-
437
- // Query to resolve the underlying issue node ID for a project item, including
438
- // the repository's visibility so callers can gate free-text writes (e.g. comments)
439
- // to public repos behind an explicit confirmation.
440
- const ITEM_ISSUE_ID_QUERY = `
441
- query GetItemIssueId($itemId: ID!) {
442
- node(id: $itemId) {
443
- ... on ProjectV2Item {
444
426
  content {
445
427
  ... on Issue {
446
428
  id
447
429
  number
448
- state
449
- url
450
430
  repository {
451
431
  isPrivate
452
432
  nameWithOwner
@@ -516,7 +496,6 @@ export {
516
496
  ISSUE_NODE_ID_QUERY,
517
497
  USER_ID_QUERY,
518
498
  ITEM_ISSUE_REFS_QUERY,
519
- ITEM_ISSUE_ID_QUERY,
520
499
  CLOSE_ISSUE_MUTATION,
521
500
  REOPEN_ISSUE_MUTATION,
522
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