@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 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
@@ -12,6 +12,7 @@
12
12
  *
13
13
  * Optional environment variables:
14
14
  * - HTTP_PORT: Port for HTTP transport (default: 8080)
15
+ * - PRO_EXTRA_BOARDS: JSON object of further boards to serve (docs/extra-boards.md)
15
16
  */
16
17
 
17
18
  import { startMCPServer } from '../src/lib/mcp/server.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.16.0-rc.1",
3
+ "version": "1.16.0-rc.3",
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/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: ${Object.keys(BOARDS).join(', ')}`);
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" -> "giantswarm/myrepo" or "giantswarm/myrepo" -> "giantswarm/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 `giantswarm/${trimmed}`;
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) {
@@ -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: 'Describe the fields of a project board (roadmap or customer) 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.',
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: ['roadmap', 'customer'],
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: ['roadmap', 'customer'],
165
+ enum: BOARD_NAMES,
166
166
  description: 'Which board to look on. Defaults to "roadmap".'
167
167
  }
168
168
  }
@@ -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
- * Supported boards: roadmap, customer
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: ${Object.keys(BOARDS).join(', ')}`);
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: ${Object.keys(BOARDS).join(', ')}`);
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: ${Object.keys(BOARDS).join(', ')}`);
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') {
@@ -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 (roadmap or customer). 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.`,
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") within the giantswarm org, or full "owner/name" format. Use giantswarm/roadmap for public-safe issues and giantswarm/giantswarm for internal/customer-specific issues.'
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 = 'giantswarm';
551
+ owner = BOARDS[board].owner;
552
552
  repo = args.repository;
553
553
  }
554
554
 
@@ -28,13 +28,100 @@ const CUSTOMER_BOARD_ID = 'PVT_kwDOAHNM9M4AHBOF';
28
28
  export const DEFAULT_BOARD = 'roadmap';
29
29
 
30
30
  /**
31
- * Board registry mapping human-readable keys to project IDs and metadata.
31
+ * The owner a short repository name ("myrepo") resolves to on the built-in boards.
32
32
  */
33
- export const BOARDS = {
34
- roadmap: { id: ROADMAP_BOARD_ID, number: 273, name: 'Roadmap Board' },
35
- customer: { id: CUSTOMER_BOARD_ID, number: 345, name: 'Customer Board' }
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: ${Object.keys(BOARDS).join(', ')}`);
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!) {