@giantswarm-io/pro 1.3.1

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.
@@ -0,0 +1,406 @@
1
+ /**
2
+ * Project Configuration and GraphQL Queries Module
3
+ *
4
+ * WHY:
5
+ * - GitHub Projects API requires specific GraphQL queries and mutations
6
+ * - Centralizing these queries improves maintainability and consistency
7
+ * - Specific project IDs and field IDs need to be accessible throughout the application
8
+ *
9
+ * HOW:
10
+ * - Defines GraphQL queries and mutations as string constants
11
+ * - Exports these queries for use by other modules
12
+ * - Provides project-specific constants (board ID, field IDs)
13
+ *
14
+ * WHAT:
15
+ * - Contains all GraphQL queries needed for GitHub Projects operations
16
+ * - Defines constants for project board ID and field IDs
17
+ * - Includes queries for fetching items, fields, and metadata
18
+ * - Provides mutations for updating item fields and other operations
19
+ */
20
+
21
+ // Export GraphQL queries and mutations for project operations
22
+ const ROADMAP_BOARD_ID = 'PVT_kwDOAHNM9M4ABvWx';
23
+ const CUSTOMER_BOARD_ID = 'PVT_kwDOAHNM9M4AHBOF';
24
+
25
+ /**
26
+ * Default board key used when no board is specified.
27
+ */
28
+ export const DEFAULT_BOARD = 'roadmap';
29
+
30
+ /**
31
+ * Board registry mapping human-readable keys to project IDs and metadata.
32
+ */
33
+ export const BOARDS = {
34
+ roadmap: { id: ROADMAP_BOARD_ID, name: 'Roadmap Board' },
35
+ customer: { id: CUSTOMER_BOARD_ID, name: 'Customer Board' }
36
+ };
37
+
38
+ /**
39
+ * Resolve a board key (e.g. "roadmap", "customer") to its GitHub project node ID.
40
+ * Defaults to DEFAULT_BOARD when boardKey is null/undefined/empty.
41
+ * @param {string} [boardKey] - Board key to resolve
42
+ * @returns {string} - GitHub project node ID
43
+ * @throws {Error} - If the board key is unknown
44
+ */
45
+ export function resolveBoardId(boardKey) {
46
+ const key = (boardKey || DEFAULT_BOARD).toLowerCase();
47
+ const entry = BOARDS[key];
48
+ if (!entry) {
49
+ throw new Error(`Unknown board '${boardKey}'. Valid boards: ${Object.keys(BOARDS).join(', ')}`);
50
+ }
51
+ return entry.id;
52
+ }
53
+
54
+ // Fetch repository id
55
+ const REPO_ID_QUERY = `
56
+ query ($owner: String!, $repo: String!) {
57
+ repository(owner: $owner, name: $repo) {
58
+ id
59
+ }
60
+ }
61
+ `;
62
+
63
+ // Lightweight query for overview statistics (Status + repository only).
64
+ // Skips text, date, iteration, milestone fields, assignees, and labels
65
+ // to stay well within MCP resource timeouts on large boards.
66
+ const LIST_ITEMS_OVERVIEW_QUERY = `
67
+ query GetProjectItemsOverview($projectId: ID!, $first: Int!, $after: String) {
68
+ node(id: $projectId) {
69
+ ... on ProjectV2 {
70
+ items(first: $first, after: $after) {
71
+ totalCount
72
+ pageInfo {
73
+ endCursor
74
+ hasNextPage
75
+ }
76
+ nodes {
77
+ fieldValues(first: 8) {
78
+ nodes {
79
+ ... on ProjectV2ItemFieldSingleSelectValue {
80
+ name
81
+ field {
82
+ ... on ProjectV2FieldCommon {
83
+ name
84
+ }
85
+ }
86
+ }
87
+ }
88
+ }
89
+ content {
90
+ ... on Issue {
91
+ title
92
+ repository {
93
+ nameWithOwner
94
+ }
95
+ }
96
+ }
97
+ }
98
+ }
99
+ }
100
+ }
101
+ }
102
+ `;
103
+
104
+ // List items in a project
105
+ const LIST_ITEMS_QUERY = `
106
+ query GetProjectItems($projectId: ID!, $first: Int!, $after: String, $filterQuery: String) {
107
+ node(id: $projectId) {
108
+ ... on ProjectV2 {
109
+ items(first: $first, after: $after, query: $filterQuery) {
110
+ totalCount
111
+ pageInfo {
112
+ endCursor
113
+ hasNextPage
114
+ startCursor
115
+ }
116
+ nodes {
117
+ id
118
+ fieldValues(first: 100) {
119
+ nodes {
120
+ ... on ProjectV2ItemFieldTextValue {
121
+ text
122
+ field {
123
+ ... on ProjectV2FieldCommon {
124
+ name
125
+ }
126
+ }
127
+ }
128
+ ... on ProjectV2ItemFieldDateValue {
129
+ date
130
+ field {
131
+ ... on ProjectV2FieldCommon {
132
+ name
133
+ }
134
+ }
135
+ }
136
+ ... on ProjectV2ItemFieldSingleSelectValue {
137
+ name
138
+ field {
139
+ ... on ProjectV2FieldCommon {
140
+ name
141
+ }
142
+ }
143
+ }
144
+ ... on ProjectV2ItemFieldIterationValue {
145
+ duration
146
+ iterationId
147
+ startDate
148
+ title
149
+ field {
150
+ ... on ProjectV2FieldCommon {
151
+ name
152
+ }
153
+ }
154
+ }
155
+ ... on ProjectV2ItemFieldMilestoneValue {
156
+ milestone {
157
+ title
158
+ description
159
+ dueOn
160
+ }
161
+ field {
162
+ ... on ProjectV2FieldCommon {
163
+ name
164
+ }
165
+ }
166
+ }
167
+ }
168
+ }
169
+ content {
170
+ ... on Issue {
171
+ title
172
+ number
173
+ url
174
+ repository {
175
+ nameWithOwner
176
+ isPrivate
177
+ url
178
+ }
179
+ assignees(first: 100) {
180
+ nodes {
181
+ login
182
+ }
183
+ }
184
+ labels(first: 100) {
185
+ nodes {
186
+ id
187
+ name
188
+ }
189
+ }
190
+ }
191
+ }
192
+ }
193
+ }
194
+ }
195
+ }
196
+ }
197
+ `;
198
+
199
+ // List fields in a project
200
+ const LIST_FIELDS_QUERY = `
201
+ query ($projectId: ID!, $first: Int!, $after: String) {
202
+ node(id: $projectId) {
203
+ ... on ProjectV2 {
204
+ fields(first: $first, after: $after) {
205
+ nodes {
206
+ __typename
207
+ ... on ProjectV2Field { id name dataType }
208
+ ... on ProjectV2SingleSelectField { id name dataType options { id name color description } }
209
+ ... on ProjectV2IterationField { id name dataType configuration { duration startDay iterations { id title duration startDate } } }
210
+ }
211
+ pageInfo { endCursor hasNextPage }
212
+ }
213
+ }
214
+ }
215
+ }
216
+ `;
217
+
218
+ // Mutation to update a field value for a project item
219
+ const UPDATE_ITEM_FIELD_MUTATION = `
220
+ mutation UpdateProjectV2ItemField($projectId: ID!, $itemId: ID!, $fieldId: ID!, $value: ProjectV2FieldValue!) {
221
+ updateProjectV2ItemFieldValue(
222
+ input: {
223
+ projectId: $projectId,
224
+ itemId: $itemId,
225
+ fieldId: $fieldId,
226
+ value: $value
227
+ }
228
+ ) {
229
+ projectV2Item {
230
+ id
231
+ }
232
+ }
233
+ }
234
+ `;
235
+
236
+ const ISSUE_DETAIL_QUERY = `
237
+ query($id: ID!) {
238
+ node(id: $id) {
239
+ ... on ProjectV2Item {
240
+ id
241
+ fieldValues(first: 100) {
242
+ nodes {
243
+ ... on ProjectV2ItemFieldTextValue {
244
+ text
245
+ field {
246
+ ... on ProjectV2FieldCommon {
247
+ name
248
+ }
249
+ }
250
+ }
251
+ ... on ProjectV2ItemFieldDateValue {
252
+ date
253
+ field {
254
+ ... on ProjectV2FieldCommon {
255
+ name
256
+ }
257
+ }
258
+ }
259
+ ... on ProjectV2ItemFieldSingleSelectValue {
260
+ name
261
+ field {
262
+ ... on ProjectV2FieldCommon {
263
+ name
264
+ }
265
+ }
266
+ }
267
+ ... on ProjectV2ItemFieldIterationValue {
268
+ title
269
+ field {
270
+ ... on ProjectV2FieldCommon {
271
+ name
272
+ }
273
+ }
274
+ }
275
+ ... on ProjectV2ItemFieldMilestoneValue {
276
+ milestone {
277
+ title
278
+ }
279
+ field {
280
+ ... on ProjectV2FieldCommon {
281
+ name
282
+ }
283
+ }
284
+ }
285
+ }
286
+ }
287
+ content {
288
+ ... on Issue {
289
+ id
290
+ title
291
+ number
292
+ url
293
+ repository {
294
+ nameWithOwner
295
+ isPrivate
296
+ url
297
+ }
298
+ body
299
+ createdAt
300
+ updatedAt
301
+ closedAt
302
+ author { login }
303
+ assignees (first: 10) {
304
+ nodes { login }
305
+ }
306
+ comments (first: 100) {
307
+ nodes {
308
+ body
309
+ createdAt
310
+ author { login }
311
+ }
312
+ }
313
+ projectsV2 (first: 10) {
314
+ nodes { title }
315
+ }
316
+ labels(first: 100) {
317
+ nodes {
318
+ name
319
+ }
320
+ }
321
+ }
322
+ }
323
+ }
324
+ }
325
+ }
326
+ `;
327
+
328
+ // Mutation to create a new issue in a repository
329
+ const CREATE_ISSUE_MUTATION = `
330
+ mutation CreateIssue($repositoryId: ID!, $title: String!, $body: String, $assigneeIds: [ID!]) {
331
+ createIssue(input: {
332
+ repositoryId: $repositoryId,
333
+ title: $title,
334
+ body: $body,
335
+ assigneeIds: $assigneeIds
336
+ }) {
337
+ issue {
338
+ id
339
+ number
340
+ url
341
+ title
342
+ }
343
+ }
344
+ }
345
+ `;
346
+
347
+ // Mutation to add an existing issue/PR to a project board
348
+ const ADD_ITEM_TO_PROJECT_MUTATION = `
349
+ mutation AddProjectV2ItemById($projectId: ID!, $contentId: ID!) {
350
+ addProjectV2ItemById(input: {
351
+ projectId: $projectId,
352
+ contentId: $contentId
353
+ }) {
354
+ item {
355
+ id
356
+ }
357
+ }
358
+ }
359
+ `;
360
+
361
+ // Mutation to archive a project item
362
+ const ARCHIVE_ITEM_MUTATION = `
363
+ mutation ArchiveProjectV2Item($projectId: ID!, $itemId: ID!) {
364
+ archiveProjectV2Item(input: {
365
+ projectId: $projectId,
366
+ itemId: $itemId
367
+ }) {
368
+ item {
369
+ id
370
+ }
371
+ }
372
+ }
373
+ `;
374
+
375
+ // Query to look up an issue node ID from its URL components
376
+ const ISSUE_NODE_ID_QUERY = `
377
+ query GetIssueNodeId($owner: String!, $repo: String!, $number: Int!) {
378
+ repository(owner: $owner, name: $repo) {
379
+ issue(number: $number) {
380
+ id
381
+ }
382
+ }
383
+ }
384
+ `;
385
+
386
+ const USER_ID_QUERY = `
387
+ query GetUserNodeId($login: String!) {
388
+ user(login: $login) {
389
+ id
390
+ }
391
+ }
392
+ `;
393
+
394
+ export {
395
+ REPO_ID_QUERY,
396
+ LIST_ITEMS_QUERY,
397
+ LIST_ITEMS_OVERVIEW_QUERY,
398
+ LIST_FIELDS_QUERY,
399
+ UPDATE_ITEM_FIELD_MUTATION,
400
+ ISSUE_DETAIL_QUERY,
401
+ CREATE_ISSUE_MUTATION,
402
+ ADD_ITEM_TO_PROJECT_MUTATION,
403
+ ARCHIVE_ITEM_MUTATION,
404
+ ISSUE_NODE_ID_QUERY,
405
+ USER_ID_QUERY
406
+ };
@@ -0,0 +1,141 @@
1
+ /**
2
+ * GitHub REST API Client
3
+ *
4
+ * Provides an authenticated Octokit REST client for the GitHub sub-issues API
5
+ * (REST-only, not available via GraphQL). Includes utilities for parsing issue
6
+ * references and resolving them to integer IDs required by the sub-issues endpoints.
7
+ *
8
+ * Supports per-request tokens (for OAuth/HTTP transport) with fallback
9
+ * to the GITHUB_API_TOKEN environment variable (for stdio transport).
10
+ */
11
+
12
+ import { Octokit } from '@octokit/rest';
13
+ import { logger } from './logger.js';
14
+
15
+ /**
16
+ * Default Octokit instance (uses GITHUB_API_TOKEN env var).
17
+ * Initialized eagerly when the env var is present, otherwise deferred
18
+ * to per-request token usage via getOctokit(token).
19
+ *
20
+ * Exported as `octokit` for backward compatibility and test mocking.
21
+ */
22
+ const envToken = process.env.GITHUB_API_TOKEN;
23
+ export const octokit = envToken
24
+ ? new Octokit({ auth: envToken, headers: { 'X-GitHub-Api-Version': '2026-03-10' } })
25
+ : null;
26
+
27
+ /**
28
+ * Get an Octokit REST client. When a per-request token is provided, creates
29
+ * a new instance. Otherwise returns the default singleton (env var based).
30
+ * @param {string} [token] - Optional per-request GitHub API token
31
+ * @returns {Octokit} - Authenticated Octokit instance
32
+ */
33
+ export function getOctokit(token) {
34
+ if (token) {
35
+ return new Octokit({
36
+ auth: token,
37
+ headers: {
38
+ 'X-GitHub-Api-Version': '2026-03-10'
39
+ }
40
+ });
41
+ }
42
+ if (!octokit) {
43
+ throw new Error(
44
+ 'No GitHub token available. Set GITHUB_API_TOKEN or authenticate via OAuth.'
45
+ );
46
+ }
47
+ return octokit;
48
+ }
49
+
50
+ const ISSUE_URL_RE = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)\/?$/;
51
+ const SHORT_REF_RE = /^([^/]+)\/([^#]+)#(\d+)$/;
52
+
53
+ /**
54
+ * Parse a GitHub issue reference into its component parts.
55
+ * Accepts full URLs or short refs (owner/repo#123).
56
+ * @param {string} input - Issue URL or short reference
57
+ * @returns {{ owner: string, repo: string, issue_number: number }}
58
+ */
59
+ export function parseIssueRef(input) {
60
+ if (!input || typeof input !== 'string') {
61
+ throw new Error('Issue reference must be a non-empty string');
62
+ }
63
+
64
+ const trimmed = input.trim();
65
+
66
+ const urlMatch = trimmed.match(ISSUE_URL_RE);
67
+ if (urlMatch) {
68
+ return {
69
+ owner: urlMatch[1],
70
+ repo: urlMatch[2],
71
+ issue_number: parseInt(urlMatch[3], 10)
72
+ };
73
+ }
74
+
75
+ const shortMatch = trimmed.match(SHORT_REF_RE);
76
+ if (shortMatch) {
77
+ return {
78
+ owner: shortMatch[1],
79
+ repo: shortMatch[2],
80
+ issue_number: parseInt(shortMatch[3], 10)
81
+ };
82
+ }
83
+
84
+ throw new Error(
85
+ `Invalid issue reference: "${input}". ` +
86
+ 'Expected a GitHub URL (https://github.com/owner/repo/issues/123) ' +
87
+ 'or short ref (owner/repo#123).'
88
+ );
89
+ }
90
+
91
+ /**
92
+ * Resolve an issue reference to its integer ID (required by the sub-issues API).
93
+ *
94
+ * Can be called with:
95
+ * - A URL or short ref string: resolveIssueId("https://github.com/o/r/issues/1")
96
+ * - Explicit parts: resolveIssueId("owner", "repo", 123)
97
+ *
98
+ * The last argument may be an options object with a `token` property for per-request auth.
99
+ *
100
+ * @param {string} ownerOrRef - Owner string, issue URL, or short ref
101
+ * @param {string} [repo] - Repository name (when passing explicit parts)
102
+ * @param {number} [issue_number] - Issue number (when passing explicit parts)
103
+ * @param {{ token?: string }} [options] - Options including optional per-request token
104
+ * @returns {Promise<{ id: number, number: number, title: string, html_url: string, state: string, repository: string }>}
105
+ */
106
+ export async function resolveIssueId(ownerOrRef, repo, issue_number, options) {
107
+ let owner;
108
+
109
+ if (repo !== undefined && issue_number !== undefined) {
110
+ owner = ownerOrRef;
111
+ } else {
112
+ // When called with a single ref string, the second arg may be the options object
113
+ if (typeof repo === 'object' && repo !== null) {
114
+ options = repo;
115
+ }
116
+ const parsed = parseIssueRef(ownerOrRef);
117
+ owner = parsed.owner;
118
+ repo = parsed.repo;
119
+ issue_number = parsed.issue_number;
120
+ }
121
+
122
+ const token = options?.token;
123
+ const client = getOctokit(token);
124
+
125
+ logger.debug('Resolving issue ID', { owner, repo, issue_number });
126
+
127
+ const { data } = await client.rest.issues.get({
128
+ owner,
129
+ repo,
130
+ issue_number
131
+ });
132
+
133
+ return {
134
+ id: data.id,
135
+ number: data.number,
136
+ title: data.title,
137
+ state: data.state,
138
+ html_url: data.html_url,
139
+ repository: `${owner}/${repo}`
140
+ };
141
+ }
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Self-update functionality
3
+ *
4
+ * Checks for the latest release of pro on GitHub and updates the
5
+ * current installation if a newer version is found.
6
+ *
7
+ * Modeled after the Go self-update pattern in mcp-kubernetes,
8
+ * adapted for Node.js.
9
+ */
10
+
11
+ import { execFileSync } from 'node:child_process';
12
+ import { version } from './version.js';
13
+ import { logger } from './logger.js';
14
+
15
+ const GITHUB_REPO = 'giantswarm/pro';
16
+ const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
17
+
18
+ /**
19
+ * Compare two semver strings.
20
+ * Returns true if remote is greater than local.
21
+ */
22
+ function isNewer(localVersion, remoteVersion) {
23
+ const local = localVersion.replace(/^v/, '').split('.').map(Number);
24
+ const remote = remoteVersion.replace(/^v/, '').split('.').map(Number);
25
+
26
+ for (let i = 0; i < 3; i++) {
27
+ if ((remote[i] || 0) > (local[i] || 0)) return true;
28
+ if ((remote[i] || 0) < (local[i] || 0)) return false;
29
+ }
30
+ return false;
31
+ }
32
+
33
+ /**
34
+ * Perform the self-update.
35
+ * Checks GitHub releases for a newer version, downloads the npm tarball,
36
+ * and installs it globally.
37
+ */
38
+ export async function selfUpdate() {
39
+ const currentVersion = version;
40
+
41
+ if (!currentVersion || currentVersion === 'dev' || currentVersion === '0.0.0') {
42
+ throw new Error('Cannot self-update a development version');
43
+ }
44
+
45
+ logger.info(`Current version: ${currentVersion}`);
46
+ logger.info('Checking for updates...');
47
+
48
+ // Fetch latest release from GitHub (use token if available for private repos)
49
+ const headers = {
50
+ 'Accept': 'application/vnd.github.v3+json',
51
+ 'User-Agent': `pro/${currentVersion}`,
52
+ };
53
+ const token = process.env.GITHUB_API_TOKEN || process.env.GITHUB_TOKEN;
54
+ if (token) {
55
+ headers['Authorization'] = `token ${token}`;
56
+ }
57
+
58
+ const response = await fetch(GITHUB_API_URL, { headers });
59
+
60
+ if (!response.ok) {
61
+ throw new Error(`Failed to check for updates: ${response.status} ${response.statusText}`);
62
+ }
63
+
64
+ const release = await response.json();
65
+ const latestVersion = release.tag_name;
66
+
67
+ if (!latestVersion) {
68
+ throw new Error(`Could not determine latest version from ${GITHUB_REPO}`);
69
+ }
70
+
71
+ if (!isNewer(currentVersion, latestVersion)) {
72
+ logger.info('Current version is the latest.');
73
+ return;
74
+ }
75
+
76
+ logger.info(`Found newer version: ${latestVersion} (published at ${release.published_at})`);
77
+
78
+ // Look for the npm tarball in release assets
79
+ const tarballAsset = release.assets?.find(a => a.name.endsWith('.tgz'));
80
+
81
+ if (tarballAsset) {
82
+ // Download and install from the release tarball
83
+ logger.info(`Downloading ${tarballAsset.name}...`);
84
+ const downloadUrl = tarballAsset.browser_download_url;
85
+
86
+ try {
87
+ execFileSync('npm', ['install', '-g', downloadUrl], { stdio: 'inherit' });
88
+ logger.info(`Successfully updated to version ${latestVersion}`);
89
+ } catch (error) {
90
+ throw new Error(`Update failed: ${error.message}`);
91
+ }
92
+ } else {
93
+ // Fallback: install directly from the GitHub repo tag
94
+ logger.info(`Installing from GitHub tag ${latestVersion}...`);
95
+
96
+ try {
97
+ execFileSync(
98
+ 'npm',
99
+ ['install', '-g', `github:${GITHUB_REPO}#${latestVersion}`],
100
+ { stdio: 'inherit' }
101
+ );
102
+ logger.info(`Successfully updated to version ${latestVersion}`);
103
+ } catch (error) {
104
+ throw new Error(`Update failed: ${error.message}`);
105
+ }
106
+ }
107
+ }