@giantswarm-io/pro 1.16.0-rc.1 → 1.16.0-rc.3
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/README.md +3 -0
- package/bin/index.js +1 -0
- package/package.json +1 -1
- package/src/lib/items.js +20 -12
- package/src/lib/mcp/board.js +4 -4
- package/src/lib/mcp/resources.js +9 -5
- package/src/lib/mcp/tools.js +7 -7
- package/src/lib/project.js +101 -5
package/README.md
CHANGED
|
@@ -100,6 +100,7 @@ each call.
|
|
|
100
100
|
- `OAUTH_BEARER_ONLY` (optional, HTTP transport): `true` selects the bearer-only mode described above.
|
|
101
101
|
- `GITHUB_APP_SLUG` (optional, bearer-only mode): the slug of the GitHub App whose user access tokens alone are accepted (`giantswarm-pro`, pro's own App, installed on every repository of the organization). Every write is then the person's own, capped by that App's permissions on the repository at hand; a token of another App, an OAuth App or a PAT is answered 401.
|
|
102
102
|
- `HTTP_PORT` (optional): Port for HTTP transport (default: 8080).
|
|
103
|
+
- `PRO_EXTRA_BOARDS` (optional): JSON object of further boards to serve next to the built-in ones; see [Extra boards](docs/extra-boards.md).
|
|
103
104
|
- `PRO_VERSION` (set by the Helm chart): the version the server reports in its startup log and MCP `serverInfo`, the image tag the chart deploys. Unset, the server reports the `package.json` version, which the npm package carries from its release tag; a checkout reports `0.0.0-dev`.
|
|
104
105
|
|
|
105
106
|
## Transport Modes
|
|
@@ -215,6 +216,8 @@ The container defaults to `--transport=streamable-http`.
|
|
|
215
216
|
| `roadmap` | [#273](https://github.com/orgs/giantswarm/projects/273) | Company quarterly goals, team/SIG/WG issues |
|
|
216
217
|
| `customer` | [#345](https://github.com/orgs/giantswarm/projects/345) | Customer activities and requests from private repos |
|
|
217
218
|
|
|
219
|
+
An installation can add boards of its own, such as a team's or a person's board, with `PRO_EXTRA_BOARDS`: see [Extra boards](docs/extra-boards.md).
|
|
220
|
+
|
|
218
221
|
The `board` parameter defaults to `"roadmap"` on every board-scoped tool for backward compatibility. Tools that resolve purely by item ID (e.g. `get_issue_details`, `update_issue_labels`) don't take a `board` parameter at all.
|
|
219
222
|
|
|
220
223
|
## MCP Tools
|
package/bin/index.js
CHANGED
package/package.json
CHANGED
package/src/lib/items.js
CHANGED
|
@@ -17,7 +17,9 @@ import {
|
|
|
17
17
|
ITEM_ISSUE_REFS_QUERY,
|
|
18
18
|
BOARD_ITEM_QUERY,
|
|
19
19
|
BOARDS,
|
|
20
|
+
BOARD_NAMES,
|
|
20
21
|
DEFAULT_BOARD,
|
|
22
|
+
resolveBoardOwner,
|
|
21
23
|
UPDATE_ITEM_FIELD_MUTATION,
|
|
22
24
|
CLEAR_ITEM_FIELD_MUTATION
|
|
23
25
|
} from './project.js';
|
|
@@ -185,7 +187,7 @@ export async function resolveBoardItem(itemId, boardKey, token) {
|
|
|
185
187
|
const key = (boardKey || DEFAULT_BOARD).toLowerCase();
|
|
186
188
|
const board = BOARDS[key];
|
|
187
189
|
if (!board) {
|
|
188
|
-
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${
|
|
190
|
+
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
|
|
189
191
|
}
|
|
190
192
|
const boardName = `the ${key} board (#${board.number})`;
|
|
191
193
|
|
|
@@ -233,17 +235,18 @@ function fieldNameToQueryKey(fieldName) {
|
|
|
233
235
|
|
|
234
236
|
/**
|
|
235
237
|
* Resolve a short or full repository name to "owner/name" format.
|
|
236
|
-
* Accepts "myrepo" -> "
|
|
238
|
+
* Accepts "myrepo" -> "<owner>/myrepo"; a full "owner/name" stays as given.
|
|
237
239
|
*
|
|
238
240
|
* @param {string} repository - Short name or full "owner/name" format
|
|
241
|
+
* @param {string} owner - The board's owner, which a short name resolves to
|
|
239
242
|
* @returns {string} - Full "owner/name" format
|
|
240
243
|
*/
|
|
241
|
-
function resolveRepositoryName(repository) {
|
|
244
|
+
function resolveRepositoryName(repository, owner) {
|
|
242
245
|
const trimmed = repository.trim();
|
|
243
246
|
if (trimmed.includes('/')) {
|
|
244
247
|
return trimmed;
|
|
245
248
|
}
|
|
246
|
-
return
|
|
249
|
+
return `${owner}/${trimmed}`;
|
|
247
250
|
}
|
|
248
251
|
|
|
249
252
|
/**
|
|
@@ -310,10 +313,13 @@ function comparisonValue(value) {
|
|
|
310
313
|
/**
|
|
311
314
|
* The query term for an issue-level qualifier.
|
|
312
315
|
* Dates (created, updated, closed) keep GitHub's comparison and range syntax.
|
|
316
|
+
* @param {string} qualifier - The query qualifier
|
|
317
|
+
* @param {string} value - Requested value, trimmed
|
|
318
|
+
* @param {string} owner - The board's owner, for short repository names
|
|
313
319
|
* @returns {string|null} - The term, or null for a list without values
|
|
314
320
|
* @throws {Error} When a parent issue is not a URL or owner/repo#number
|
|
315
321
|
*/
|
|
316
|
-
function qualifierTerm(qualifier, value) {
|
|
322
|
+
function qualifierTerm(qualifier, value, owner) {
|
|
317
323
|
switch (qualifier) {
|
|
318
324
|
case 'created':
|
|
319
325
|
case 'updated':
|
|
@@ -322,7 +328,7 @@ function qualifierTerm(qualifier, value) {
|
|
|
322
328
|
case 'reason':
|
|
323
329
|
return `reason:${queryValue(value)}`;
|
|
324
330
|
case 'repo': {
|
|
325
|
-
const list = queryValueList(value, resolveRepositoryName);
|
|
331
|
+
const list = queryValueList(value, part => resolveRepositoryName(part, owner));
|
|
326
332
|
return list ? `repo:${list}` : null;
|
|
327
333
|
}
|
|
328
334
|
case 'parent-issue': {
|
|
@@ -358,16 +364,17 @@ function qualifierTerm(qualifier, value) {
|
|
|
358
364
|
* @param {string} value - Requested value, trimmed
|
|
359
365
|
* @param {Object[]} allFields - The board's fields
|
|
360
366
|
* @param {boolean} issueFilters - Whether issue filter names are accepted
|
|
367
|
+
* @param {string} owner - The board's owner, for short repository names
|
|
361
368
|
* @returns {string|null} - The query term, or null for a list without values
|
|
362
369
|
* @throws {Error} Naming the unknown field or value and what is available
|
|
363
370
|
*/
|
|
364
|
-
function fieldTerm(param, name, value, allFields, issueFilters) {
|
|
371
|
+
function fieldTerm(param, name, value, allFields, issueFilters, owner) {
|
|
365
372
|
const field = allFields.find(f => f?.name?.toLowerCase() === name.toLowerCase());
|
|
366
373
|
if (!field) {
|
|
367
374
|
const filterName = issueFilters &&
|
|
368
375
|
Object.keys(ISSUE_FILTER_QUALIFIERS).find(key => key.toLowerCase() === name.toLowerCase());
|
|
369
376
|
if (filterName) {
|
|
370
|
-
return qualifierTerm(ISSUE_FILTER_QUALIFIERS[filterName], value);
|
|
377
|
+
return qualifierTerm(ISSUE_FILTER_QUALIFIERS[filterName], value, owner);
|
|
371
378
|
}
|
|
372
379
|
const available = allFields.map(f => f?.name).filter(Boolean);
|
|
373
380
|
const extra = issueFilters ? `; or one of ${Object.keys(ISSUE_FILTER_QUALIFIERS).join(', ')}` : '';
|
|
@@ -413,7 +420,7 @@ function fieldTerm(param, name, value, allFields, issueFilters) {
|
|
|
413
420
|
|
|
414
421
|
const qualifier = QUALIFIER_BY_DATA_TYPE[field.dataType];
|
|
415
422
|
if (qualifier) {
|
|
416
|
-
return qualifierTerm(qualifier, value);
|
|
423
|
+
return qualifierTerm(qualifier, value, owner);
|
|
417
424
|
}
|
|
418
425
|
|
|
419
426
|
if (field.dataType === 'TEXT') {
|
|
@@ -546,6 +553,7 @@ export async function listItems(options) {
|
|
|
546
553
|
|
|
547
554
|
// Build server-side filter query
|
|
548
555
|
const queryTerms = [];
|
|
556
|
+
const owner = resolveBoardOwner(boardId);
|
|
549
557
|
|
|
550
558
|
// Issue filters, each in GitHub Projects query syntax. List values are
|
|
551
559
|
// comma-separated for OR matching; a value with spaces is quoted on its
|
|
@@ -575,7 +583,7 @@ export async function listItems(options) {
|
|
|
575
583
|
queryTerms.push(`is:${lower}`);
|
|
576
584
|
}
|
|
577
585
|
} else {
|
|
578
|
-
const term = qualifierTerm(qualifier, trimmed);
|
|
586
|
+
const term = qualifierTerm(qualifier, trimmed, owner);
|
|
579
587
|
if (term) queryTerms.push(term);
|
|
580
588
|
}
|
|
581
589
|
}
|
|
@@ -622,11 +630,11 @@ export async function listItems(options) {
|
|
|
622
630
|
|
|
623
631
|
try {
|
|
624
632
|
for (const [fieldName, value] of filterEntries) {
|
|
625
|
-
const term = fieldTerm('filters', fieldName, value, allFields, false);
|
|
633
|
+
const term = fieldTerm('filters', fieldName, value, allFields, false, owner);
|
|
626
634
|
if (term) queryTerms.push(term);
|
|
627
635
|
}
|
|
628
636
|
for (const [fieldName, value] of excludeEntries) {
|
|
629
|
-
const term = fieldTerm('exclude', fieldName, value, allFields, true);
|
|
637
|
+
const term = fieldTerm('exclude', fieldName, value, allFields, true, owner);
|
|
630
638
|
if (term) queryTerms.push(`-${term}`);
|
|
631
639
|
}
|
|
632
640
|
} catch (error) {
|
package/src/lib/mcp/board.js
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
import { listFields } from '../fields.js';
|
|
9
9
|
import { graphQLWithAuth, withPartialData } from '../api.js';
|
|
10
|
-
import { resolveBoardId, BOARDS, DEFAULT_BOARD } from '../project.js';
|
|
10
|
+
import { resolveBoardId, BOARDS, BOARD_NAMES, BOARD_NAMES_TEXT, DEFAULT_BOARD } from '../project.js';
|
|
11
11
|
import { parseIssueRef } from '../rest-api.js';
|
|
12
12
|
import { logger } from '../logger.js';
|
|
13
13
|
import { READ_ONLY } from './annotations.js';
|
|
@@ -42,13 +42,13 @@ export function describeField(field) {
|
|
|
42
42
|
export const getBoardSchemaTool = {
|
|
43
43
|
name: 'get_board_schema',
|
|
44
44
|
annotations: READ_ONLY,
|
|
45
|
-
description:
|
|
45
|
+
description: `Describe the fields of a project board (${BOARD_NAMES_TEXT}) the way a UI needs them: name, type (singleSelect, iteration, date, text, other), the options a single-select field accepts and the iterations of an iteration field. The same information as the {board}://schema resource, as a tool result.`,
|
|
46
46
|
inputSchema: {
|
|
47
47
|
type: 'object',
|
|
48
48
|
properties: {
|
|
49
49
|
board: {
|
|
50
50
|
type: 'string',
|
|
51
|
-
enum:
|
|
51
|
+
enum: BOARD_NAMES,
|
|
52
52
|
description: 'Which board to describe. Defaults to "roadmap".'
|
|
53
53
|
}
|
|
54
54
|
}
|
|
@@ -162,7 +162,7 @@ export const getItemByIssueTool = {
|
|
|
162
162
|
issue_number: { type: 'number', description: 'Issue number' },
|
|
163
163
|
board: {
|
|
164
164
|
type: 'string',
|
|
165
|
-
enum:
|
|
165
|
+
enum: BOARD_NAMES,
|
|
166
166
|
description: 'Which board to look on. Defaults to "roadmap".'
|
|
167
167
|
}
|
|
168
168
|
}
|
package/src/lib/mcp/resources.js
CHANGED
|
@@ -5,12 +5,13 @@
|
|
|
5
5
|
* - {board}://schema: Compact field schema with valid option values, repository guidance, and content policy
|
|
6
6
|
* - {board}://overview: Board-level stats (issue counts, status and repository distribution)
|
|
7
7
|
*
|
|
8
|
-
*
|
|
8
|
+
* One pair per board of the registry: the built-in roadmap and customer
|
|
9
|
+
* boards and the ones PRO_EXTRA_BOARDS adds.
|
|
9
10
|
*/
|
|
10
11
|
|
|
11
12
|
import { listFields } from '../fields.js';
|
|
12
13
|
import { fetchPaginated } from '../api.js';
|
|
13
|
-
import { BOARDS, LIST_ITEMS_OVERVIEW_QUERY } from '../project.js';
|
|
14
|
+
import { BOARDS, BOARD_NAMES, LIST_ITEMS_OVERVIEW_QUERY } from '../project.js';
|
|
14
15
|
import { logger } from '../logger.js';
|
|
15
16
|
|
|
16
17
|
/**
|
|
@@ -68,7 +69,7 @@ const SKIP_DATA_TYPES = new Set([
|
|
|
68
69
|
async function getSchemaResource(boardKey, token) {
|
|
69
70
|
const board = BOARDS[boardKey];
|
|
70
71
|
if (!board) {
|
|
71
|
-
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${
|
|
72
|
+
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
|
|
72
73
|
}
|
|
73
74
|
try {
|
|
74
75
|
logger.info(`MCP: Generating schema resource for ${boardKey} board`);
|
|
@@ -164,6 +165,9 @@ async function getSchemaResource(boardKey, token) {
|
|
|
164
165
|
if (repoInfo.policy?.length) {
|
|
165
166
|
schema.policy = repoInfo.policy.join(' ');
|
|
166
167
|
}
|
|
168
|
+
} else {
|
|
169
|
+
// A board added by PRO_EXTRA_BOARDS: only its owner is known
|
|
170
|
+
schema.repoPattern = `${board.owner}/<repository>`;
|
|
167
171
|
}
|
|
168
172
|
|
|
169
173
|
return {
|
|
@@ -194,7 +198,7 @@ async function getSchemaResource(boardKey, token) {
|
|
|
194
198
|
async function getOverviewResource(boardKey, token) {
|
|
195
199
|
const board = BOARDS[boardKey];
|
|
196
200
|
if (!board) {
|
|
197
|
-
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${
|
|
201
|
+
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
|
|
198
202
|
}
|
|
199
203
|
try {
|
|
200
204
|
logger.info(`MCP: Generating overview resource for ${boardKey} board`);
|
|
@@ -308,7 +312,7 @@ export async function readResource(uri, extra) {
|
|
|
308
312
|
const [, boardKey, resourceType] = match;
|
|
309
313
|
|
|
310
314
|
if (!BOARDS[boardKey]) {
|
|
311
|
-
throw new Error(`Unknown board '${boardKey}' in resource URI: ${uri}. Valid boards: ${
|
|
315
|
+
throw new Error(`Unknown board '${boardKey}' in resource URI: ${uri}. Valid boards: ${BOARD_NAMES.join(', ')}`);
|
|
312
316
|
}
|
|
313
317
|
|
|
314
318
|
if (resourceType === 'schema') {
|
package/src/lib/mcp/tools.js
CHANGED
|
@@ -22,6 +22,8 @@ import {
|
|
|
22
22
|
resolveBoardId,
|
|
23
23
|
DEFAULT_BOARD,
|
|
24
24
|
BOARDS,
|
|
25
|
+
BOARD_NAMES,
|
|
26
|
+
BOARD_NAMES_TEXT,
|
|
25
27
|
REPO_ID_QUERY,
|
|
26
28
|
CREATE_ISSUE_MUTATION,
|
|
27
29
|
ADD_ITEM_TO_PROJECT_MUTATION,
|
|
@@ -47,8 +49,6 @@ import {
|
|
|
47
49
|
} from '../comments.js';
|
|
48
50
|
import { READ_ONLY, additiveWrite, destructiveWrite } from './annotations.js';
|
|
49
51
|
|
|
50
|
-
const BOARD_NAMES = Object.keys(BOARDS);
|
|
51
|
-
|
|
52
52
|
/**
|
|
53
53
|
* Extract the GitHub token from MCP request extra context.
|
|
54
54
|
* Returns the OAuth token if present, otherwise undefined (falls back to env var in api.js).
|
|
@@ -85,7 +85,7 @@ export const DEFAULT_LIST_LIMIT = 50;
|
|
|
85
85
|
export const listIssuesTool = {
|
|
86
86
|
name: 'list_issues',
|
|
87
87
|
annotations: READ_ONLY,
|
|
88
|
-
description: `List and filter issues from a project board (
|
|
88
|
+
description: `List and filter issues from a project board (${BOARD_NAMES_TEXT}). Uses generic field filters -- read the board's schema resource first (e.g. roadmap://schema or customer://schema) to discover available fields and valid option values. Field filters go under \`filters\` only (e.g. \`filters: {"Team": "Honey Badger", "Status": "Backlog", "Quarter": "@current"}\`), and \`exclude\` leaves matching items out (e.g. \`exclude: {"Status": "Done"}\`); any other top-level argument that is not listed here is refused with an error naming it. Earlier releases took an unknown top-level string argument as a field filter: a call with \`Team: "X"\` becomes \`filters: {"Team": "X"}\`. Returns at most \`limit\` items (default ${DEFAULT_LIST_LIMIT}; 0 for every matching item, which on a large board takes seconds per hundred items: narrow it with \`closed\` or \`updated\`) as compact entries with \`repo\` (nameWithOwner), \`private\` flag, \`state\` (OPEN/CLOSED), \`createdAt\`/\`updatedAt\` timestamps, \`closedAt\` (only present when the item is closed), and a \`fields\` map of single-select, iteration, date and text values (only non-empty ones; the built-in Title is the entry's \`title\`). The repo URL is always https://github.com/{repo}. Next to \`count\` (items returned), \`hidden\` is the number of matching items left out because their content could not be read (typically issues in private repos the server's GitHub identity cannot access), and \`totalCount\` is GitHub's count of items matching the server-side query (unreadable items, draft issues and pull requests included). \`hidden > 0\` means the result is incomplete. \`truncated: true\` means the limit cut the list with items left: pass \`nextCursor\` as \`cursor\` with the same filters to continue. An issue with open dependencies carries their counts as \`openBlockedBy\` / \`openBlocking\`; when they cannot be read, \`dependencyCountsError\` says why.`,
|
|
89
89
|
inputSchema: {
|
|
90
90
|
type: 'object',
|
|
91
91
|
properties: {
|
|
@@ -105,7 +105,7 @@ export const listIssuesTool = {
|
|
|
105
105
|
},
|
|
106
106
|
repository: {
|
|
107
107
|
type: 'string',
|
|
108
|
-
description: 'Filter by repository. Accepts short name (e.g. "myrepo") which resolves to "giantswarm/myrepo", or full "owner/name" format. On the customer board each customer has their own repo (e.g. "giantswarm/<customer-name>"). On the roadmap board the repos are "giantswarm/roadmap" (public) and "giantswarm/giantswarm" (internal).'
|
|
108
|
+
description: 'Filter by repository. Accepts short name (e.g. "myrepo") which resolves to the board\'s owner ("giantswarm/myrepo" on the roadmap and customer boards), or full "owner/name" format. On the customer board each customer has their own repo (e.g. "giantswarm/<customer-name>"). On the roadmap board the repos are "giantswarm/roadmap" (public) and "giantswarm/giantswarm" (internal).'
|
|
109
109
|
},
|
|
110
110
|
filters: {
|
|
111
111
|
type: 'object',
|
|
@@ -473,7 +473,7 @@ export const createIssueInProjectTool = {
|
|
|
473
473
|
properties: {
|
|
474
474
|
repository: {
|
|
475
475
|
type: 'string',
|
|
476
|
-
description: 'Repository name (e.g., "my-app")
|
|
476
|
+
description: 'Repository name (e.g., "my-app") of the board\'s owner (the giantswarm org on the roadmap and customer boards), or full "owner/name" format. Use giantswarm/roadmap for public-safe issues and giantswarm/giantswarm for internal/customer-specific issues.'
|
|
477
477
|
},
|
|
478
478
|
title: {
|
|
479
479
|
type: 'string',
|
|
@@ -539,7 +539,7 @@ export function issueCreationRefusedMessage(owner, repo) {
|
|
|
539
539
|
export async function handleCreateIssueInProject(args, extra) {
|
|
540
540
|
try {
|
|
541
541
|
const token = extractToken(extra);
|
|
542
|
-
const board = args.board || DEFAULT_BOARD;
|
|
542
|
+
const board = (args.board || DEFAULT_BOARD).toLowerCase();
|
|
543
543
|
const boardId = resolveBoardId(board);
|
|
544
544
|
logger.info('MCP: Creating issue in project', { repository: args.repository, title: args.title, board });
|
|
545
545
|
|
|
@@ -548,7 +548,7 @@ export async function handleCreateIssueInProject(args, extra) {
|
|
|
548
548
|
if (args.repository.includes('/')) {
|
|
549
549
|
[owner, repo] = args.repository.split('/');
|
|
550
550
|
} else {
|
|
551
|
-
owner =
|
|
551
|
+
owner = BOARDS[board].owner;
|
|
552
552
|
repo = args.repository;
|
|
553
553
|
}
|
|
554
554
|
|
package/src/lib/project.js
CHANGED
|
@@ -28,13 +28,100 @@ const CUSTOMER_BOARD_ID = 'PVT_kwDOAHNM9M4AHBOF';
|
|
|
28
28
|
export const DEFAULT_BOARD = 'roadmap';
|
|
29
29
|
|
|
30
30
|
/**
|
|
31
|
-
*
|
|
31
|
+
* The owner a short repository name ("myrepo") resolves to on the built-in boards.
|
|
32
32
|
*/
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
33
|
+
const DEFAULT_OWNER = 'giantswarm';
|
|
34
|
+
|
|
35
|
+
const BUILT_IN_BOARDS = {
|
|
36
|
+
roadmap: { id: ROADMAP_BOARD_ID, number: 273, name: 'Roadmap Board', owner: DEFAULT_OWNER },
|
|
37
|
+
customer: { id: CUSTOMER_BOARD_ID, number: 345, name: 'Customer Board', owner: DEFAULT_OWNER }
|
|
36
38
|
};
|
|
37
39
|
|
|
40
|
+
// A board key is also the scheme of the board's resource URIs ({key}://schema).
|
|
41
|
+
const BOARD_KEY_RE = /^[a-z][a-z0-9-]*$/;
|
|
42
|
+
const EXTRA_BOARD_PROPERTIES = ['id', 'number', 'owner', 'name'];
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Parse the boards an installation adds to the built-in ones (PRO_EXTRA_BOARDS):
|
|
46
|
+
* a JSON object of board key -> { id, number, owner, name }.
|
|
47
|
+
* - id: the project's node ID ("PVT_...")
|
|
48
|
+
* - number: the project's number, as in its URL
|
|
49
|
+
* - owner: the user or organization a short repository name resolves to
|
|
50
|
+
* - name: display name (optional, defaults to "<Key> Board")
|
|
51
|
+
* A mistake fails the start instead of serving a board half configured.
|
|
52
|
+
* @param {string} [json] - The value of PRO_EXTRA_BOARDS
|
|
53
|
+
* @returns {Object} - Board registry entries, keyed by board key
|
|
54
|
+
* @throws {Error} - Naming the entry and what is wrong with it
|
|
55
|
+
*/
|
|
56
|
+
export function parseExtraBoards(json) {
|
|
57
|
+
if (!json?.trim()) return {};
|
|
58
|
+
|
|
59
|
+
const fail = message => { throw new Error(`PRO_EXTRA_BOARDS: ${message}`); };
|
|
60
|
+
|
|
61
|
+
let entries;
|
|
62
|
+
try {
|
|
63
|
+
entries = JSON.parse(json);
|
|
64
|
+
} catch (error) {
|
|
65
|
+
fail(`not valid JSON (${error.message})`);
|
|
66
|
+
}
|
|
67
|
+
const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
68
|
+
if (!isObject(entries)) {
|
|
69
|
+
fail('expected a JSON object of board key -> { id, number, owner, name }');
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const boards = {};
|
|
73
|
+
for (const [key, board] of Object.entries(entries)) {
|
|
74
|
+
if (!BOARD_KEY_RE.test(key)) {
|
|
75
|
+
fail(`board key '${key}' must be lowercase letters, digits and hyphens, starting with a letter`);
|
|
76
|
+
}
|
|
77
|
+
if (BUILT_IN_BOARDS[key]) {
|
|
78
|
+
fail(`'${key}' is a built-in board and cannot be redefined`);
|
|
79
|
+
}
|
|
80
|
+
if (!isObject(board)) {
|
|
81
|
+
fail(`board '${key}' must be an object with id, number and owner`);
|
|
82
|
+
}
|
|
83
|
+
const unknown = Object.keys(board).filter(property => !EXTRA_BOARD_PROPERTIES.includes(property));
|
|
84
|
+
if (unknown.length) {
|
|
85
|
+
fail(`board '${key}' has unknown properties: ${unknown.join(', ')}. Accepted: ${EXTRA_BOARD_PROPERTIES.join(', ')}`);
|
|
86
|
+
}
|
|
87
|
+
if (typeof board.id !== 'string' || !board.id.startsWith('PVT_')) {
|
|
88
|
+
fail(`board '${key}' needs "id", the project's node ID (PVT_...)`);
|
|
89
|
+
}
|
|
90
|
+
if (!Number.isInteger(board.number) || board.number < 1) {
|
|
91
|
+
fail(`board '${key}' needs "number", the project's number as in its URL`);
|
|
92
|
+
}
|
|
93
|
+
if (typeof board.owner !== 'string' || !/^[A-Za-z0-9-]+$/.test(board.owner)) {
|
|
94
|
+
fail(`board '${key}' needs "owner", the user or organization a short repository name resolves to`);
|
|
95
|
+
}
|
|
96
|
+
if (board.name !== undefined && (typeof board.name !== 'string' || !board.name.trim())) {
|
|
97
|
+
fail(`board '${key}': "name" must be a non-empty string`);
|
|
98
|
+
}
|
|
99
|
+
boards[key] = {
|
|
100
|
+
id: board.id,
|
|
101
|
+
number: board.number,
|
|
102
|
+
name: board.name?.trim() || `${key[0].toUpperCase()}${key.slice(1)} Board`,
|
|
103
|
+
owner: board.owner
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
return boards;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Board registry mapping human-readable keys to project IDs and metadata:
|
|
111
|
+
* the built-in boards, then the ones PRO_EXTRA_BOARDS adds.
|
|
112
|
+
*/
|
|
113
|
+
export const BOARDS = { ...BUILT_IN_BOARDS, ...parseExtraBoards(process.env.PRO_EXTRA_BOARDS) };
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The board keys, for the `board` argument of the tools.
|
|
117
|
+
*/
|
|
118
|
+
export const BOARD_NAMES = Object.keys(BOARDS);
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The board keys as prose ("roadmap or customer"), for tool descriptions.
|
|
122
|
+
*/
|
|
123
|
+
export const BOARD_NAMES_TEXT = new Intl.ListFormat('en', { type: 'disjunction' }).format(BOARD_NAMES);
|
|
124
|
+
|
|
38
125
|
/**
|
|
39
126
|
* Resolve a board key (e.g. "roadmap", "customer") to its GitHub project node ID.
|
|
40
127
|
* Defaults to DEFAULT_BOARD when boardKey is null/undefined/empty.
|
|
@@ -46,11 +133,20 @@ export function resolveBoardId(boardKey) {
|
|
|
46
133
|
const key = (boardKey || DEFAULT_BOARD).toLowerCase();
|
|
47
134
|
const entry = BOARDS[key];
|
|
48
135
|
if (!entry) {
|
|
49
|
-
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${
|
|
136
|
+
throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
|
|
50
137
|
}
|
|
51
138
|
return entry.id;
|
|
52
139
|
}
|
|
53
140
|
|
|
141
|
+
/**
|
|
142
|
+
* The owner a short repository name resolves to on a board.
|
|
143
|
+
* @param {string} boardId - GitHub project node ID
|
|
144
|
+
* @returns {string} - The board's owner; the built-in one for a project outside the registry
|
|
145
|
+
*/
|
|
146
|
+
export function resolveBoardOwner(boardId) {
|
|
147
|
+
return Object.values(BOARDS).find(board => board.id === boardId)?.owner || DEFAULT_OWNER;
|
|
148
|
+
}
|
|
149
|
+
|
|
54
150
|
// Fetch repository id
|
|
55
151
|
const REPO_ID_QUERY = `
|
|
56
152
|
query ($owner: String!, $repo: String!) {
|