@falldownthesystem/devtool 0.5.0 → 0.6.1

package/src/clients/graph.js

@@ -0,0 +1,263 @@
+import { open, rm, lstat, mkdtemp, link } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { validateGraphSite } from '../config/store.js';
+
+const BASE = 'https://graph.microsoft.com/v1.0';
+const MAIL_FIELDS = 'id,subject,from,toRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,bodyPreview,webLink,parentFolderId';
+
+export function graphUrl(path, params = {}) {
+	const url = new URL(path.startsWith('/') ? `${BASE}${path}` : path);
+	if (url.origin !== 'https://graph.microsoft.com' || !url.pathname.startsWith('/v1.0/') || url.username || url.password || url.hash) {
+		throw new Error('Refused an invalid Microsoft Graph URL.');
+	}
+	for (const [key, value] of Object.entries(params)) {
+		if (value !== undefined && value !== '') url.searchParams.set(key, String(value));
+	}
+	return url;
+}
+
+export function graphId(value) {
+	if (typeof value !== 'string' || !value.trim() || value === '.' || value === '..') throw new Error('A resource ID is required.');
+	return encodeURIComponent(value);
+}
+
+export function graphLimit(value = 25) {
+	if (!/^\d+$/.test(String(value)) || Number(value) < 1 || Number(value) > 1000) {
+		throw new Error('Limit must be an integer from 1 to 1000.');
+	}
+	return Number(value);
+}
+
+export function siteAddress(site) {
+	if (!site) throw new Error('Set defaultSite on the Microsoft Graph connection or pass --site <site-url-or-id>.');
+	if (!/^https?:/i.test(site)) return `/sites/${graphId(site)}`;
+	const invalid = validateGraphSite(site);
+	if (invalid) throw new Error(invalid);
+	const url = new URL(site);
+	const path = url.pathname.split('/').filter(Boolean).map((part) => graphId(decodeURIComponent(part))).join('/');
+	return path ? `/sites/${url.hostname}:/${path}` : `/sites/${url.hostname}`;
+}
+
+function mailboxPath(mailbox) {
+	return mailbox ? `/users/${graphId(mailbox)}` : '/me';
+}
+
+export function calendarRange({ from, to } = {}, now = new Date()) {
+	function parse(value) {
+		if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/i.test(value) || !Number.isFinite(Date.parse(value))) {
+			throw new Error('Calendar dates must use ISO 8601 with a timezone, for example 2026-09-14T09:00:00+03:00.');
+		}
+		return new Date(value);
+	}
+	const start = from ? parse(from) : now;
+	const end = to ? parse(to) : new Date(start.getTime() + 30 * 86400000);
+	if (end <= start || end - start > 366 * 86400000) throw new Error('Calendar end must follow start, within 366 days.');
+	return { startDateTime: start.toISOString(), endDateTime: end.toISOString() };
+}
+
+function calendarPath({ mailbox, calendar } = {}) {
+	return `${mailboxPath(mailbox)}/${calendar ? `calendars/${graphId(calendar)}` : 'calendar'}`;
+}
+
+function eventStart(event) {
+	const value = event.start?.dateTime || '';
+	const start = Date.parse(/(?:[zZ]|[+-]\d{2}:\d{2})$/.test(value) ? value : `${value}Z`);
+	if (!Number.isFinite(start)) throw new Error('Microsoft Graph returned an event without a valid start time.');
+	return start;
+}
+
+export function createGraphClient({ auth, defaultSite, fetchImpl = fetch }) {
+	async function response(path, params = {}, { sharedMail = false, calendars = false, availability = false, headers = {}, scheduleQuery, timeout = 60000 } = {}) {
+		const url = graphUrl(path, params);
+		if (scheduleQuery && (url.pathname !== '/v1.0/me/calendar/getSchedule' || url.search)) throw new Error('Only the read-only getSchedule query can use POST.');
+		const token = await auth.token({ sharedMail, calendars, availability });
+		const result = await fetchImpl(url, {
+			method: scheduleQuery ? 'POST' : 'GET',
+			headers: { ...headers, Accept: 'application/json', Authorization: `Bearer ${token}`, ...(scheduleQuery ? { 'Content-Type': 'application/json' } : {}) },
+			...(scheduleQuery ? { body: JSON.stringify(scheduleQuery) } : {}),
+			redirect: 'manual',
+			signal: AbortSignal.timeout(timeout),
+		});
+		return result;
+	}
+
+	async function check(result) {
+		if (result.ok) return;
+		let message = `Microsoft Graph request failed (${result.status}).`;
+		if (result.status === 401) message = 'Microsoft Graph rejected the sign-in. Run: dev graph login';
+		else if (result.status === 403) message = 'Microsoft Graph access denied. Check delegated permissions, administrator consent, and your access to this resource. Shared mail also needs Mail.Read.Shared and Exchange access.';
+		else if (result.status === 404) message = 'Microsoft Graph resource not found. Check its ID and your access.';
+		else if (result.status === 429) message = `Microsoft Graph rate limit reached. Retry after ${result.headers.get('retry-after') || 'a few'} seconds.`;
+		else if (result.status >= 300 && result.status < 400) message = 'Refused an unexpected Microsoft Graph redirect.';
+		if (result.headers.get('content-type')?.includes('application/json')) {
+			try {
+				const body = await result.json();
+				const code = body.error?.code;
+				if (typeof code === 'string' && /^[a-z0-9_.-]{1,80}$/i.test(code)) message += ` Code: ${code}.`;
+			} catch {}
+		} else {
+			await result.body?.cancel();
+		}
+		const err = new Error(message);
+		err.status = result.status;
+		throw err;
+	}
+
+	async function request(path, params, options) {
+		const result = await response(path, params, options);
+		await check(result);
+		return result.json();
+	}
+
+	async function collection(path, params = {}, { limit = 25, pageSize = 100, requireComplete = false, ...options } = {}) {
+		limit = graphLimit(limit);
+		let next = graphUrl(path, { ...params, $top: Math.min(limit, pageSize) }).href;
+		const seen = new Set();
+		const items = [];
+		while (next && items.length < limit) {
+			if (seen.has(next) || seen.size >= 1000) throw new Error('Microsoft Graph returned invalid pagination.');
+			seen.add(next);
+			const page = await request(next, {}, options);
+			if (!Array.isArray(page.value)) throw new Error('Microsoft Graph returned an invalid collection.');
+			const overflow = page.value.length > limit - items.length;
+			items.push(...page.value.slice(0, limit - items.length));
+			next = page['@odata.nextLink'];
+			if (requireComplete && (overflow || (next && items.length >= limit))) throw new Error('Calendar range exceeds 1000 events. Narrow --from and --to.');
+		}
+		return items;
+	}
+
+	async function siteId(site) {
+		const target = site || defaultSite;
+		if (target && !/^https?:/i.test(target)) return graphId(target);
+		const data = await request(siteAddress(target), { $select: 'id' });
+		return graphId(data.id);
+	}
+
+	async function calendarEvents(options = {}) {
+		const range = calendarRange(options);
+		// Read the entire bounded window before sorting, so page order cannot hide an earlier occurrence.
+		const events = await collection(`${calendarPath(options)}/calendarView`, range, {
+			limit: 1000, pageSize: 1000, requireComplete: true, calendars: true, headers: { Prefer: 'outlook.timezone="UTC"' },
+		});
+		return { range, events: events.sort((a, b) => eventStart(a) - eventStart(b)) };
+	}
+
+	return {
+		async availability(schedules, options = {}) {
+			if (!Array.isArray(schedules) || !schedules.length || schedules.length > 20 || schedules.some((address) => !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address))) {
+				throw new Error('Supply 1–20 email addresses for the availability query.');
+			}
+			const range = calendarRange(options);
+			if (!options.to) range.endDateTime = new Date(Date.parse(range.startDateTime) + 86400000).toISOString();
+			if (Date.parse(range.endDateTime) - Date.parse(range.startDateTime) >= 62 * 86400000) throw new Error('Availability range must be shorter than 62 days.');
+			const interval = Number(options.interval ?? 30);
+			if (!Number.isInteger(interval) || interval < 5 || interval > 1440) throw new Error('Availability interval must be 5–1440 minutes.');
+			const result = await request('/me/calendar/getSchedule', {}, {
+				availability: true,
+				headers: { Prefer: 'outlook.timezone="UTC"' },
+				scheduleQuery: {
+					schedules,
+					startTime: { dateTime: range.startDateTime.replace(/Z$/, ''), timeZone: 'UTC' },
+					endTime: { dateTime: range.endDateTime.replace(/Z$/, ''), timeZone: 'UTC' },
+					availabilityViewInterval: interval,
+				},
+			});
+			if (!Array.isArray(result.value)) throw new Error('Microsoft Graph returned an invalid availability result.');
+			return { from: range.startDateTime, to: range.endDateTime, intervalMinutes: interval, schedules: result.value };
+		},
+		calendars: ({ mailbox, limit } = {}) => collection(`${mailboxPath(mailbox)}/calendars`, {}, { limit, calendars: true }),
+		calendarEvents: async (options = {}) => {
+			const limit = graphLimit(options.limit);
+			return (await calendarEvents(options)).events.slice(0, limit);
+		},
+		nextEvent: async (options = {}) => {
+			const { range, events } = await calendarEvents(options);
+			const start = Date.parse(range.startDateTime);
+			const event = events.find((item) => !item.isCancelled && item.responseStatus?.response !== 'declined' && eventStart(item) >= start) || null;
+			return { from: range.startDateTime, to: range.endDateTime, event };
+		},
+		calendarEvent: (id, options = {}) => request(`${calendarPath(options)}/events/${graphId(id)}`, {}, { calendars: true, headers: { Prefer: 'outlook.timezone="UTC"' } }),
+
+		chats: ({ limit } = {}) => collection('/me/chats', { $expand: 'members', $orderby: 'lastMessagePreview/createdDateTime desc' }, { limit, pageSize: 50 }),
+		chat: (id) => request(`/chats/${graphId(id)}`, { $expand: 'members' }),
+		chatMessages: (id, { limit } = {}) => collection(`/chats/${graphId(id)}/messages`, { $orderby: 'createdDateTime desc' }, { limit, pageSize: 50 }),
+		chatMessage: (chatId, messageId) => request(`/chats/${graphId(chatId)}/messages/${graphId(messageId)}`),
+
+		mailFolders: ({ mailbox, parent, limit } = {}) => collection(`${mailboxPath(mailbox)}/mailFolders${parent ? `/${graphId(parent)}/childFolders` : ''}`, {}, { limit, sharedMail: !!mailbox }),
+		mailMessages: ({ mailbox, folder, search, limit } = {}) => {
+			const path = `${mailboxPath(mailbox)}${folder ? `/mailFolders/${graphId(folder)}` : ''}/messages`;
+			return collection(path, {
+				$select: MAIL_FIELDS,
+				$search: search ? JSON.stringify(search) : undefined,
+				$orderby: search ? undefined : 'receivedDateTime desc',
+			}, { limit, sharedMail: !!mailbox });
+		},
+		mailMessage: (id, { mailbox, folder } = {}) => request(`${mailboxPath(mailbox)}${folder ? `/mailFolders/${graphId(folder)}` : ''}/messages/${graphId(id)}`, {
+			$select: `${MAIL_FIELDS},body,ccRecipients`,
+		}, { sharedMail: !!mailbox, headers: { Prefer: 'outlook.body-content-type="text"' } }),
+
+		sites: (query, { limit } = {}) => collection('/sites', { search: query, $select: 'id,name,displayName,description,webUrl' }, { limit }),
+		site: (site) => request(siteAddress(site || defaultSite), { $select: 'id,name,displayName,description,webUrl' }),
+		drives: async ({ site, limit } = {}) => collection(`/sites/${await siteId(site)}/drives`, {}, { limit }),
+		files: (drive, { folder, path, limit } = {}) => {
+			if (folder && path) throw new Error('Use either --folder or --path, not both.');
+			let location = folder ? `items/${graphId(folder)}` : 'root';
+			if (path) location = `root:/${path.replace(/\\/g, '/').split('/').filter(Boolean).map(graphId).join('/')}:`;
+			return collection(`/drives/${graphId(drive)}/${location}/children`, {}, { limit });
+		},
+		file: (drive, id) => request(`/drives/${graphId(drive)}/items/${graphId(id)}`),
+		lists: async ({ site, limit } = {}) => collection(`/sites/${await siteId(site)}/lists`, {}, { limit }),
+		listItems: async (list, { site, limit } = {}) => collection(`/sites/${await siteId(site)}/lists/${graphId(list)}/items`, { $expand: 'fields' }, { limit }),
+		listItem: async (list, item, { site } = {}) => request(`/sites/${await siteId(site)}/lists/${graphId(list)}/items/${graphId(item)}`, { $expand: 'fields' }),
+
+		async download(drive, id, destination, { timeout = 120 } = {}) {
+			if (!/^\d+$/.test(String(timeout)) || Number(timeout) < 1 || Number(timeout) > 86400) throw new Error('Download timeout must be 1–86400 seconds.');
+			const milliseconds = Number(timeout) * 1000;
+			try {
+				await lstat(destination);
+				throw Object.assign(new Error('Destination already exists. Choose a new local path.'), { code: 'EEXIST' });
+			} catch (err) {
+				if (err.code !== 'ENOENT') throw err;
+			}
+			const directory = await mkdtemp(join(dirname(resolve(destination)), '.devtool-download-'));
+			const temporary = join(directory, 'content');
+			let failure;
+			try {
+				let result = await response(`/drives/${graphId(drive)}/items/${graphId(id)}/content`, {}, { timeout: milliseconds });
+				if (result.status === 302) {
+					const target = new URL(result.headers.get('location'));
+					await result.body?.cancel();
+					if (target.protocol !== 'https:' || !target.hostname.endsWith('.sharepoint.com') || target.username || target.password || target.port) {
+						throw new Error('Refused a download redirect outside SharePoint Online.');
+					}
+					// The download URL already authorizes this request; never forward the Graph bearer token.
+					result = await fetchImpl(target, { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(milliseconds) });
+				}
+				await check(result);
+				if (!result.body) throw new Error('SharePoint returned no file content.');
+				const file = await open(temporary, 'wx', 0o600);
+				try {
+					await pipeline(Readable.fromWeb(result.body), file.createWriteStream());
+				} finally {
+					await file.close();
+				}
+				// Publish only a complete file. An atomic hard link refuses a concurrently created destination.
+				await link(temporary, destination);
+				return { path: resolve(destination), downloaded: true };
+			} catch (err) {
+				failure = err;
+				throw err;
+			} finally {
+				try {
+					await rm(directory, { recursive: true, force: true });
+				} catch (err) {
+					if (failure) failure.message += ' Temporary download cleanup failed.';
+					else throw new Error('The download is complete, but temporary file cleanup failed.', { cause: err });
+				}
+			}
+		},
+	};
+}

package/src/clients/jira.js

@@ -1,13 +1,12 @@
 import { Version2Client } from 'jira.js';
-import { get } from '../config/store.js';
 
-let client = null;
+const clients = new Map();
 
-function getClient() {
-	if (!client) {
-		const token = get('jira.token');
-		client = new Version2Client({
-			host: get('jira.baseUrl'),
+function getClient({ baseUrl, token }) {
+	const key = `${baseUrl}\n${token}`;
+	if (!clients.has(key)) {
+		const client = new Version2Client({
+			host: baseUrl,
 			authentication: {
 				basic: { email: '', apiToken: token },
 			},
@@ -16,20 +15,21 @@ function getClient() {
 			config.headers['Authorization'] = `Bearer ${token}`;
 			return config;
 		});
+		clients.set(key, client);
 	}
-	return client;
+	return clients.get(key);
 }
 
-export async function getIssue(issueKey) {
-	return getClient().issues.getIssue({
+export async function getIssue(connection, issueKey) {
+	return getClient(connection).issues.getIssue({
 		issueIdOrKey: issueKey,
 		fields: ['*all'],
 		expand: 'renderedFields',
 	});
 }
 
-export async function getIssueComments(issueKey) {
-	const result = await getClient().issueComments.getComments({
+export async function getIssueComments(connection, issueKey) {
+	const result = await getClient(connection).issueComments.getComments({
 		issueIdOrKey: issueKey,
 		orderBy: 'created',
 		maxResults: 100,
@@ -37,8 +37,8 @@ export async function getIssueComments(issueKey) {
 	return result.comments || [];
 }
 
-export async function searchIssues(jql, startAt = 0, maxResults = 50) {
-	const result = await getClient().issueSearch.searchForIssuesUsingJql({
+export async function searchIssues(connection, jql, startAt = 0, maxResults = 50) {
+	const result = await getClient(connection).issueSearch.searchForIssuesUsingJql({
 		jql,
 		startAt,
 		maxResults,
@@ -52,21 +52,21 @@ export async function searchIssues(jql, startAt = 0, maxResults = 50) {
 	};
 }
 
-export async function getMyIssues() {
-	const project = get('jira.defaultProject');
+export async function getMyIssues(connection) {
+	const project = connection.defaultProject;
 	const jql = project
 		? `project = ${project} AND assignee = currentUser() AND status != Done ORDER BY updated DESC`
 		: `assignee = currentUser() AND status != Done ORDER BY updated DESC`;
-	return searchIssues(jql);
+	return searchIssues(connection, jql);
 }
 
-export async function getIssueChildren(issueKey) {
-	const issue = await getIssue(issueKey);
+export async function getIssueChildren(connection, issueKey) {
+	const issue = await getIssue(connection, issueKey);
 	const type = issue.fields.issuetype?.name;
 	const parent = { key: issue.key, type, summary: issue.fields.summary };
 
 	if (type === 'Epic') {
-		const response = await getClient().instance.get(
+		const response = await getClient(connection).instance.get(
 			`/rest/agile/1.0/epic/${encodeURIComponent(issueKey)}/issue`,
 			{
 				params: {

package/src/clients/serviceDesk.js

@@ -1,13 +1,11 @@
-import { get } from '../config/store.js';
-
 function configurationError(reason) {
-	return new Error(`Service Desk configuration error: ${reason}. Check serviceDesk.baseUrl; use the canonical https://<site>.atlassian.net URL.`);
+	return new Error(`Service Desk configuration error: ${reason}. Check the base URL of the Service Desk connection; use the canonical https://<site>.atlassian.net URL.`);
 }
 
-function baseUrl() {
+function baseUrl(connection) {
 	let url;
 	try {
-		url = new URL(get('serviceDesk.baseUrl'));
+		url = new URL(connection.baseUrl);
 	} catch {
 		throw configurationError('invalid base URL');
 	}
@@ -17,9 +15,7 @@ function baseUrl() {
 	return new URL(url.origin);
 }
 
-function authHeader() {
-	const email = get('serviceDesk.email');
-	const token = get('serviceDesk.token');
+function authHeader({ email = '', token = '' }) {
 	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
 }
 
@@ -58,8 +54,8 @@ async function fetchJson(url, headers = {}) {
 	return data;
 }
 
-async function request(path, params = {}, { extraHeaders = {}, validate = () => true } = {}) {
-	const site = baseUrl();
+async function request(connection, path, params = {}, { extraHeaders = {}, validate = () => true } = {}) {
+	const site = baseUrl(connection);
 	if (!site.hostname.endsWith('.atlassian.net')) {
 		const info = await fetchJson(new URL('/rest/api/2/serverInfo', site));
 		let canonical;
@@ -77,21 +73,21 @@ async function request(path, params = {}, { extraHeaders = {}, validate = () =>
 	for (const [k, v] of Object.entries(params)) {
 		if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, v);
 	}
-	const data = await fetchJson(url, { 'Authorization': authHeader(), ...extraHeaders });
+	const data = await fetchJson(url, { 'Authorization': authHeader(connection), ...extraHeaders });
 	if (!validate(data)) throw configurationError('unexpected API response structure');
 	return data;
 }
 
-export async function getIssue(issueKey) {
-	return request(`/rest/api/3/issue/${encodeURIComponent(issueKey)}`, {
+export async function getIssue(connection, issueKey) {
+	return request(connection, `/rest/api/3/issue/${encodeURIComponent(issueKey)}`, {
 		expand: 'renderedFields',
 	}, {
 		validate: (data) => typeof data.key === 'string' && data.fields && typeof data.fields === 'object' && !Array.isArray(data.fields),
 	});
 }
 
-export async function getIssueComments(issueKey) {
-	const data = await request(`/rest/api/3/issue/${encodeURIComponent(issueKey)}/comment`, {
+export async function getIssueComments(connection, issueKey) {
+	const data = await request(connection, `/rest/api/3/issue/${encodeURIComponent(issueKey)}/comment`, {
 		orderBy: 'created',
 		maxResults: 100,
 	}, {
@@ -100,9 +96,9 @@ export async function getIssueComments(issueKey) {
 	return data.comments;
 }
 
-export async function searchIssues(jql, maxResults = 50, nextPageToken = '') {
+export async function searchIssues(connection, jql, maxResults = 50, nextPageToken = '') {
 	const fields = 'summary,status,assignee,priority,updated,issuetype,reporter,customfield_10010';
-	const data = await request('/rest/api/3/search/jql', {
+	const data = await request(connection, '/rest/api/3/search/jql', {
 		jql,
 		fields,
 		maxResults,
@@ -120,21 +116,21 @@ export async function searchIssues(jql, maxResults = 50, nextPageToken = '') {
 	};
 }
 
-export async function getMyIssues() {
-	const project = get('serviceDesk.defaultProject');
+export async function getMyIssues(connection) {
+	const project = connection.defaultProject;
 	const jql = project
 		? `project = ${project} AND assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC`
 		: `assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC`;
-	return searchIssues(jql);
+	return searchIssues(connection, jql);
 }
 
-let _serviceDeskIdCache = null;
+// Keyed by site as well as project, because two sites can both have a project with the same key.
+const serviceDeskIds = new Map();
 
-async function getServiceDeskId(projectKey) {
-	if (_serviceDeskIdCache && _serviceDeskIdCache.projectKey === projectKey) {
-		return _serviceDeskIdCache.id;
-	}
-	const data = await request('/rest/servicedeskapi/servicedesk', { start: 0, limit: 100 }, {
+async function getServiceDeskId(connection, projectKey) {
+	const key = `${baseUrl(connection).origin} ${projectKey}`;
+	if (serviceDeskIds.has(key)) return serviceDeskIds.get(key);
+	const data = await request(connection, '/rest/servicedeskapi/servicedesk', { start: 0, limit: 100 }, {
 		extraHeaders: { 'X-ExperimentalApi': 'opt-in' },
 		validate: (data) => Array.isArray(data.values),
 	});
@@ -142,23 +138,23 @@ async function getServiceDeskId(projectKey) {
 	if (!match) {
 		throw new Error(`No Service Desk found for project ${projectKey}`);
 	}
-	_serviceDeskIdCache = { projectKey, id: match.id };
+	serviceDeskIds.set(key, match.id);
 	return match.id;
 }
 
-export async function listQueues() {
-	const projectKey = get('serviceDesk.defaultProject');
-	if (!projectKey) throw new Error('serviceDesk.defaultProject is not configured');
-	const sdId = await getServiceDeskId(projectKey);
-	const data = await request(`/rest/servicedeskapi/servicedesk/${sdId}/queue`, { start: 0, limit: 100 }, {
+export async function listQueues(connection) {
+	const projectKey = connection.defaultProject;
+	if (!projectKey) throw new Error('No default project is set on the Service Desk connection');
+	const sdId = await getServiceDeskId(connection, projectKey);
+	const data = await request(connection, `/rest/servicedeskapi/servicedesk/${sdId}/queue`, { start: 0, limit: 100 }, {
 		extraHeaders: { 'X-ExperimentalApi': 'opt-in' },
 		validate: (data) => Array.isArray(data.values),
 	});
 	return data.values.map((q) => ({ id: q.id, name: q.name, jql: q.jql }));
 }
 
-export async function findQueue(nameOrId) {
-	const queues = await listQueues();
+export async function findQueue(connection, nameOrId) {
+	const queues = await listQueues(connection);
 	const idMatch = queues.find((q) => String(q.id) === String(nameOrId));
 	if (idMatch) return idMatch;
 	const lower = nameOrId.toLowerCase();
@@ -174,8 +170,8 @@ export async function findQueue(nameOrId) {
 	throw new Error(`No queue found matching "${nameOrId}"`);
 }
 
-export async function searchByQueue(nameOrId, maxResults = 50, nextPageToken = '') {
-	const queue = await findQueue(nameOrId);
-	const result = await searchIssues(queue.jql, maxResults, nextPageToken);
+export async function searchByQueue(connection, nameOrId, maxResults = 50, nextPageToken = '') {
+	const queue = await findQueue(connection, nameOrId);
+	const result = await searchIssues(connection, queue.jql, maxResults, nextPageToken);
 	return { ...result, queue };
 }

package/src/commands/config.js

@@ -1,31 +1,80 @@
 import { Command } from 'commander';
-import { getAll, set, runSetup, configPath, schema } from '../config/store.js';
+import {
+	types, label, listConnections, removeConnection, setDefault, setField, configPath,
+} from '../config/store.js';
+import { runSetup, addConnection, editConnection, describe } from '../config/setup.js';
 import { heading, field, mask, success, error, divider } from '../utils/output.js';
 
+function attempt(action) {
+	return async (...args) => {
+		try {
+			await action(...args);
+		} catch (err) {
+			error(err.message);
+			process.exitCode = 1;
+		}
+	};
+}
+
+function parseType(input) {
+	if (input === undefined) return undefined;
+	const type = Object.keys(types).find((t) => t.toLowerCase() === input.toLowerCase());
+	if (!type) throw new Error(`Unknown connection type "${input}". Valid types: ${Object.keys(types).join(', ')}`);
+	return type;
+}
+
 const config = new Command('config')
-	.description('Manage configuration');
+	.description('Manage connections');
 
 config
 	.command('setup')
-	.description('Run interactive setup')
-	.action(async () => {
-		await runSetup();
-	});
+	.description('Add or edit connections interactively')
+	.action(attempt(runSetup));
+
+config
+	.command('add [type]')
+	.description(`Add a connection (${Object.keys(types).join(', ')})`)
+	.option('-n, --name <name>', 'Connection name')
+	.action(attempt((type, opts) => addConnection(parseType(type), opts.name)));
+
+config
+	.command('edit <connection>')
+	.description('Edit a connection interactively')
+	.action(attempt(editConnection));
+
+config
+	.command('remove <connection>')
+	.alias('rm')
+	.description('Remove a connection')
+	.action(attempt((ref) => {
+		success(`Removed connection "${label(removeConnection(ref))}"`);
+	}));
+
+config
+	.command('default <connection>')
+	.description('Use a connection when no --connection is given for its type')
+	.action(attempt((ref) => {
+		const connection = setDefault(ref);
+		success(`"${label(connection)}" is now the default ${types[connection.type].title} connection`);
+	}));
 
 config
 	.command('show')
-	.alias('get')
-	.description('Show current configuration')
+	.aliases(['get', 'list'])
+	.description('Show all connections')
 	.action(() => {
-		const all = getAll();
+		const connections = listConnections();
+		if (!connections.length) {
+			console.log('\nNo connections configured. Run `dev config add` to add one.');
+		}
 
-		for (const [section, definition] of Object.entries(schema)) {
-			heading(definition.title);
-			for (const [key, property] of Object.entries(definition.properties)) {
-				const value = all[section]?.[key] ?? '';
-				field(property.title, property.writeOnly ? mask(value) : value);
+		connections.forEach((connection, index) => {
+			heading(describe(connections, index));
+			for (const [key, property] of Object.entries(types[connection.type].fields)) {
+				const value = connection[key] ?? '';
+				field(property.title, property.secret && value ? mask(value) : value);
 			}
-		}
+		});
 
 		console.log('');
 		divider();
@@ -35,17 +84,12 @@ config
 
 config
 	.command('set <key> <value>')
-	.description('Set a config value (e.g. bitbucket.workspace my-ws)')
-	.action((key, value) => {
-		const validKeys = Object.entries(schema).flatMap(([section, definition]) =>
-			Object.keys(definition.properties).map((key) => `${section}.${key}`));
-		if (!validKeys.includes(key)) {
-			error(`Invalid key: ${key}`);
-			console.log(`Valid keys: ${validKeys.join(', ')}`);
-			return;
-		}
-		set(key, value);
-		success(`Set ${key}`);
-	});
+	.description('Set a connection field, as <connection>.<field> (e.g. bitbucket.workspace my-ws)')
+	.action(attempt((key, value) => {
+		const dot = key.lastIndexOf('.');
+		if (dot <= 0) throw new Error(`Invalid key: ${key}. Use <connection>.<field>, e.g. jira.baseUrl`);
+		const connection = setField(key.slice(0, dot), key.slice(dot + 1), value);
+		success(`Set ${key.slice(dot + 1)} on connection "${label(connection)}"`);
+	}));
 
 export default config;