@falldownthesystem/devtool 0.5.0 → 0.6.1

package/src/commands/confluence.js

@@ -13,7 +13,7 @@ import {
 import { spinner } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
 import { getOutputMode, outputJson } from '../utils/mode.js';
-import { get } from '../config/store.js';
+import { connectionFor } from '../utils/connection.js';
 
 const confluence = new Command('confluence')
 	.description('Confluence pages');
@@ -24,7 +24,7 @@ confluence.command('spaces')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Fetching spaces...').start() : null;
 		try {
-			const spaces = await listSpaces();
+			const spaces = await listSpaces(connectionFor(this, 'confluence'));
 			if (s) s.success({ text: `${spaces.length} space(s) found` });
 			if (mode === 'json') outputJson(curateSpacesJson(spaces));
 			else if (mode === 'plain') plainSpaces(spaces);
@@ -42,7 +42,7 @@ confluence.command('view <id>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching page ${id}...`).start() : null;
 		try {
-			const page = await getPage(id);
+			const page = await getPage(connectionFor(this, 'confluence'), id);
 			if (s) s.success({ text: page.title || `Page ${id}` });
 			if (mode === 'json') outputJson(curatePageJson(page));
 			else if (mode === 'plain') plainPageView(page);
@@ -62,15 +62,16 @@ confluence.command('pages')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Fetching pages...').start() : null;
 		try {
+			const connection = connectionFor(this, 'confluence');
 			const spaceId = opts.spaceId;
-			const spaceKey = spaceId ? undefined : opts.space || get('confluence.defaultSpace');
+			const spaceKey = spaceId ? undefined : opts.space || connection.defaultSpace;
 			if (!spaceId && !spaceKey) {
 				if (s) s.error({ text: 'No space specified' });
-				console.error('Specify --space <key>, --space-id <id>, or set confluence.defaultSpace');
+				console.error('Specify --space <key>, --space-id <id>, or set defaultSpace on the Confluence connection');
 				process.exitCode = 1;
 				return;
 			}
-			const pages = await listSpacePages({ spaceId, spaceKey });
+			const pages = await listSpacePages(connection, { spaceId, spaceKey });
 			if (!pages) {
 				if (s) s.error({ text: `Space "${spaceId || spaceKey}" not found` });
 				process.exitCode = 1;
@@ -93,7 +94,7 @@ confluence.command('search <cql>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Searching...').start() : null;
 		try {
-			const result = await searchPages(cql);
+			const result = await searchPages(connectionFor(this, 'confluence'), cql);
 			const count = result.totalSize || (result.results || []).length;
 			if (s) s.success({ text: `${count} result(s)` });
 			if (mode === 'json') outputJson(curateSearchJson(result));

package/src/commands/graph.js

@@ -0,0 +1,147 @@
+import { Command, InvalidArgumentError } from 'commander';
+import { createGraphClient, graphLimit } from '../clients/graph.js';
+import { createGraphAuth } from '../clients/graph-auth.js';
+import { label, listConnections, getConnection } from '../config/store.js';
+import { addConnection, editConnection } from '../config/setup.js';
+import { getOutputMode } from '../utils/mode.js';
+import { connectionFor } from '../utils/connection.js';
+import { spinner } from '../utils/output.js';
+import {
+	formatGraph, graphText, curateChatJson, curateChatMessageJson, curateMailJson,
+	curateFolderJson, curateSiteJson, curateDriveJson, curateFileJson, curateListJson, curateListItemJson,
+	curateCalendarJson, curateEventJson, curateNextEventJson, curateAvailabilityJson, formatNextEvent, formatAvailability,
+} from '../formatters/graph.js';
+
+function limit(value) {
+	try { return graphLimit(value); }
+	catch (err) { throw new InvalidArgumentError(err.message); }
+}
+
+export function graphErrorMessage(err) {
+	const code = err.cause?.code || err.code;
+	if (err.name === 'TimeoutError' || ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT'].includes(code)) return 'Microsoft Graph request timed out. Check your connection; for a slow file download, increase --timeout.';
+	if (['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'ENETUNREACH', 'EHOSTUNREACH'].includes(code)) return `Cannot reach Microsoft Graph (${code}). Check your network, VPN, and proxy settings.`;
+	if (['UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'SELF_SIGNED_CERT_IN_CHAIN', 'CERT_HAS_EXPIRED', 'DEPTH_ZERO_SELF_SIGNED_CERT', 'ERR_TLS_CERT_ALTNAME_INVALID'].includes(code)) return 'Microsoft Graph TLS certificate validation failed. Check the certificate chain and your proxy configuration.';
+	if (err.cause?.message === 'unexpected redirect') return 'Refused an additional SharePoint download redirect.';
+	if (err.cause && code && /^[a-z0-9_.-]{1,80}$/i.test(code)) return `Microsoft Graph connection failed (${code}). Check your network and proxy settings.`;
+	return graphText(err.message || 'Microsoft Graph request failed.');
+}
+
+function connectGraph(cmd) {
+	const connection = connectionFor(cmd, 'graph');
+	const auth = createGraphAuth({ connection });
+	return { auth, client: createGraphClient({ auth, defaultSite: connection.defaultSite }) };
+}
+
+// Edits the selected Graph connection, or adds one when none exists yet.
+async function setupGraph(ref) {
+	if (!ref && !listConnections().some((c) => c.type === 'graph')) return addConnection('graph');
+	return editConnection(label(getConnection('graph', ref)));
+}
+
+export function createGraphCommand({ connect = connectGraph, setup = setupGraph } = {}) {
+	const graph = new Command('graph').description('Read Microsoft Graph: Teams, email, calendars, and SharePoint')
+		.configureOutput({ writeErr: (text) => {
+			const message = graphText(text).trim();
+			process.stderr.write(getOutputMode(graph) === 'json' ? `${JSON.stringify({ error: { message, status: null } })}\n` : `${message}\n`);
+		} });
+	const calendar = graph.command('calendar').alias('calendars').description('Read your calendars and accessible shared calendars')
+		.option('--mailbox <address>', 'Calendar owner address or user ID; requires existing calendar access')
+		.option('--calendar <id>', 'Calendar ID from list; defaults to the primary calendar');
+	const teams = graph.command('teams').description('Read your Teams chats (not channel messages)');
+	const mail = graph.command('mail').alias('email').description('Read email and folders')
+		.option('--mailbox <address>', 'Shared mailbox or folder owner; requires Mail.Read.Shared and Exchange access');
+	const sharepoint = graph.command('sharepoint').alias('sp').description('Read SharePoint sites, libraries, files, and lists')
+		.option('--site <url-or-id>', 'Override the connection\'s default site');
+
+	function action(command, title, load, { curate = (value) => value, format = formatGraph, columns, records = false, interactive = false, connected = true } = {}) {
+		command.action(async function (...args) {
+			const mode = getOutputMode(this);
+			const s = mode === 'rich' && !interactive ? spinner(title).start() : null;
+			try {
+				if (interactive && (mode !== 'rich' || !process.stdin.isTTY || !process.stdout.isTTY)) {
+					throw new Error('Setup and sign-in require an interactive terminal without --json or --plain. Data commands never open a browser.');
+				}
+				const result = await load(connected ? connect(this) : {}, args, this.optsWithGlobals());
+				const data = Array.isArray(result) ? result.map(curate) : curate(result);
+				s?.success();
+				if (data !== undefined) format(data, { mode, title, columns, records });
+			} catch (err) {
+				s?.error();
+				const message = graphErrorMessage(err);
+				console.error(mode === 'json' ? JSON.stringify({ error: { message, status: err.status || null } }) : message);
+				process.exitCode = 1;
+			}
+		});
+		return command;
+	}
+
+	const bounded = (command) => command.option('-n, --limit <count>', 'Maximum results (1-1000; more results may exist)', limit, 25);
+	const mailFolder = (command) => command.option('--folder <id-or-name>', 'Folder ID or well-known name such as inbox');
+	const idName = [['ID', (x) => x.id, 38], ['Name', (x) => x.name, 48]];
+
+	action(graph.command('setup').description('Add or edit a Graph connection: tenant ID, client ID, and default SharePoint site'), 'Graph setup', (_, __, opts) => setup(opts.connection), { interactive: true, connected: false });
+	action(graph.command('login').description('Sign in through your browser; no client secret')
+		.option('--shared-mail', 'Also request Mail.Read.Shared for shared mailboxes and folders')
+		.option('--calendars', 'Also request calendar details and free/busy permissions')
+		.option('--all', 'Sign in once for all supported read-only services, including shared email and calendars'), 'Graph sign-in', ({ auth }, _, opts) => auth.login(opts), { interactive: true });
+	action(graph.command('status').description('Show the locally cached account (does not check token validity)'), 'Cached Graph account', ({ auth }) => auth.status());
+	action(graph.command('logout').description('Remove this application’s local cached account; does not revoke server grants'), 'Graph sign-out', ({ auth }) => auth.logout());
+
+	const dateWindow = (command) => command
+		.option('--from <datetime>', 'ISO start with timezone; defaults to now')
+		.option('--to <datetime>', 'ISO end with timezone; defaults to 30 days after start (maximum 366 days)');
+	action(bounded(calendar.command('list').description('List your calendars, including shared calendars added to your mailbox')), 'Calendars', ({ client }, _, opts) => client.calendars(opts), {
+		curate: curateCalendarJson, columns: [...idName, ['Owner', (x) => x.owner?.address, 32]],
+	});
+	action(bounded(dateWindow(calendar.command('events').description('Read recurring occurrences and appointments in a date range, in UTC'))), 'Calendar events', ({ client }, _, opts) => client.calendarEvents(opts), {
+		curate: curateEventJson,
+		columns: [['ID', (x) => x.id, 32], ['Subject', (x) => x.subject, 44], ['Start (UTC)', (x) => x.start?.dateTime, 30], ['Location', (x) => x.location, 28]],
+	});
+	action(dateWindow(calendar.command('next').description('Show the next event in the selected calendar; skip cancelled, declined, and already-started events')), 'Next calendar event', ({ client }, _, opts) => client.nextEvent(opts), { curate: curateNextEventJson, format: formatNextEvent });
+	action(calendar.command('availability <addresses...>').description('Read free/busy times for users or rooms; no calendar changes')
+		.option('--from <datetime>', 'ISO start with timezone; defaults to now')
+		.option('--to <datetime>', 'ISO end with timezone; defaults to 24 hours later (range under 62 days)')
+		.option('--interval <minutes>', 'Slot size, 5–1440 minutes', '30'), 'Calendar availability', async ({ client }, [addresses], opts) => {
+			if (opts.mailbox || opts.calendar) throw new Error('Availability uses the supplied email addresses, not --mailbox or --calendar.');
+			const result = await client.availability(addresses, opts);
+			if (result.schedules.some((schedule) => schedule.error)) process.exitCode = 1;
+			return result;
+		}, { curate: curateAvailabilityJson, format: formatAvailability });
+	action(calendar.command('view <event-id>').description('Read an event from the selected calendar'), 'Calendar event', ({ client }, [id], opts) => client.calendarEvent(id, opts), { curate: curateEventJson });
+
+	action(bounded(teams.command('chats').alias('list').description('List your chats; expanded members may be limited to 25')), 'Teams chats', ({ client }, _, opts) => client.chats(opts), {
+		curate: curateChatJson,
+		columns: [['ID', (x) => x.id, 42], ['Topic / members', (x) => x.topic || x.members.map((m) => m.name || m.email).join(', '), 48], ['Type', (x) => x.type, 16]],
+	});
+	action(teams.command('view <chat-id>').description('Show a chat and its members'), 'Teams chat', ({ client }, [id]) => client.chat(id), { curate: curateChatJson });
+	action(bounded(teams.command('messages <chat-id>').description('Read chat messages, newest first')), 'Teams messages', ({ client }, [id], opts) => client.chatMessages(id, opts), { curate: curateChatMessageJson, records: true });
+	action(teams.command('message <chat-id> <message-id>').description('Read one chat message'), 'Teams message', ({ client }, [chat, message]) => client.chatMessage(chat, message), { curate: curateChatMessageJson });
+
+	action(bounded(mail.command('folders').description('List mailbox folders')
+		.option('--parent <folder-id>', 'List child folders of this folder')), 'Mail folders', ({ client }, _, opts) => client.mailFolders(opts), {
+		curate: curateFolderJson, columns: [...idName, ['Unread / total', (x) => `${x.unread} / ${x.total}`, 18]],
+	});
+	const mailColumns = [['ID', (x) => x.id, 36], ['Subject', (x) => x.subject, 44], ['From', (x) => x.from?.address, 30], ['Received', (x) => x.receivedAt, 26]];
+	action(bounded(mailFolder(mail.command('list').alias('messages').description('List email across all folders, newest first; use --folder inbox for the inbox'))), 'Email', ({ client }, _, opts) => client.mailMessages(opts), { curate: curateMailJson, columns: mailColumns });
+	action(bounded(mailFolder(mail.command('search <query>').description('Search email using Microsoft message search syntax'))), 'Email search', ({ client }, [search], opts) => client.mailMessages({ ...opts, search }), { curate: curateMailJson, columns: mailColumns });
+	action(mailFolder(mail.command('view <message-id>').description('Read email content without changing its read status')), 'Email message', ({ client }, [id], opts) => client.mailMessage(id, opts), { curate: curateMailJson });
+
+	action(bounded(sharepoint.command('sites <query>').description('Find sites by text')), 'SharePoint sites', ({ client }, [query], opts) => client.sites(query, opts), { curate: curateSiteJson, columns: idName });
+	action(sharepoint.command('site [url-or-id]').description('Show a site; defaults to the connection\'s default site'), 'SharePoint site', ({ client }, [site], opts) => client.site(site || opts.site), { curate: curateSiteJson });
+	action(bounded(sharepoint.command('libraries').alias('drives').description('List the site’s document libraries')), 'Document libraries', ({ client }, _, opts) => client.drives(opts), { curate: curateDriveJson, columns: idName });
+	action(bounded(sharepoint.command('files <drive-id>').description('List files and folders in a document library')
+		.option('--folder <item-id>', 'Folder item ID')
+		.option('--path <path>', 'Folder path relative to the library root')), 'SharePoint files', ({ client }, [drive], opts) => client.files(drive, opts), {
+		curate: curateFileJson, columns: [...idName, ['Type', (x) => x.type, 12], ['Bytes', (x) => x.size, 14]],
+	});
+	action(sharepoint.command('file <drive-id> <item-id>').description('Show file or folder metadata'), 'SharePoint file', ({ client }, [drive, id]) => client.file(drive, id), { curate: curateFileJson });
+	action(sharepoint.command('download <drive-id> <item-id> <destination>').description('Download a file to a new local path; never overwrite')
+		.option('--timeout <seconds>', 'Per-request download timeout, 1–86400 seconds', '120'), 'SharePoint download', ({ client }, [drive, id, destination], opts) => client.download(drive, id, destination, opts));
+	action(bounded(sharepoint.command('lists').description('List SharePoint lists')), 'SharePoint lists', ({ client }, _, opts) => client.lists(opts), { curate: curateListJson, columns: idName });
+	action(bounded(sharepoint.command('items <list-id>').description('Read list items and their fields')), 'SharePoint list items', ({ client }, [list], opts) => client.listItems(list, opts), { curate: curateListItemJson, records: true });
+	action(sharepoint.command('item <list-id> <item-id>').description('Read one list item and its fields'), 'SharePoint list item', ({ client }, [list, item], opts) => client.listItem(list, item, opts), { curate: curateListItemJson });
+	return graph;
+}
+
+export default createGraphCommand();

package/src/commands/jira.js

@@ -15,6 +15,7 @@ import {
 import { spinner } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
 import { getOutputMode, outputJson } from '../utils/mode.js';
+import { connectionFor } from '../utils/connection.js';
 
 const jira = new Command('jira')
 	.description('Jira tickets');
@@ -26,7 +27,7 @@ jira.command('view <key>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching ${key}...`).start() : null;
 		try {
-			const issue = await getIssue(key);
+			const issue = await getIssue(connectionFor(this, 'jira'), key);
 			if (s) s.success({ text: key });
 			if (mode === 'json') outputJson(curateIssueJson(issue));
 			else if (mode === 'plain') plainIssueView(issue);
@@ -43,7 +44,7 @@ jira.command('comments <key>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching comments for ${key}...`).start() : null;
 		try {
-			const comments = await getIssueComments(key);
+			const comments = await getIssueComments(connectionFor(this, 'jira'), key);
 			if (s) s.success({ text: `${comments.length} comment(s)` });
 			if (mode === 'json') outputJson(curateCommentsJson(comments));
 			else if (mode === 'plain') plainIssueComments(comments);
@@ -65,7 +66,7 @@ jira.command('search <jql>')
 		const startAt = (parseInt(opts.page, 10) - 1) * perPage;
 		const s = mode === 'rich' ? spinner('Searching...').start() : null;
 		try {
-			const result = await searchIssues(jql, startAt, perPage);
+			const result = await searchIssues(connectionFor(this, 'jira'), jql, startAt, perPage);
 			if (s) s.success({ text: `${result.total} issue(s) matched` });
 			if (mode === 'json') outputJson(curateSearchJson(result));
 			else if (mode === 'plain') plainIssueSearch(result);
@@ -83,7 +84,7 @@ jira.command('children <key>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching children of ${key}...`).start() : null;
 		try {
-			const result = await getIssueChildren(key);
+			const result = await getIssueChildren(connectionFor(this, 'jira'), key);
 			if (s) s.success({ text: `${result.total} ${result.source === 'epic' ? 'issue(s) in epic' : 'subtask(s)'}` });
 			if (mode === 'json') outputJson(curateChildrenJson(result));
 			else if (mode === 'plain') plainIssueChildren(result);
@@ -101,7 +102,7 @@ jira.command('mine')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Fetching my issues...').start() : null;
 		try {
-			const result = await getMyIssues();
+			const result = await getMyIssues(connectionFor(this, 'jira'));
 			if (s) s.success({ text: `${result.total} issue(s)` });
 			if (mode === 'json') outputJson(curateSearchJson(result));
 			else if (mode === 'plain') plainIssueSearch(result);

package/src/commands/pr.js

@@ -14,23 +14,7 @@ import {
 import { spinner } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
 import { getOutputMode, outputJson } from '../utils/mode.js';
-
-function withMode(cmd, fetchFn, { json, plain, rich }) {
-	return async (...args) => {
-		const mode = getOutputMode(cmd);
-		const s = mode === 'rich' ? spinner('Loading...').start() : null;
-		try {
-			const data = await fetchFn(...args);
-			if (s) s.success({ text: '' });
-			if (mode === 'json') outputJson(json(data));
-			else if (mode === 'plain') plain(data);
-			else rich(data);
-		} catch (err) {
-			if (s) s.error({ text: 'Failed' });
-			handleError(err, err.url || 'bitbucket');
-		}
-	};
-}
+import { connectionFor } from '../utils/connection.js';
 
 const pr = new Command('pr')
 	.description('Bitbucket pull requests');
@@ -45,7 +29,7 @@ pr.command('list')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Fetching pull requests...').start() : null;
 		try {
-			const prs = await listPullRequests({ state: opts.state, author: opts.author, repo: opts.repo });
+			const prs = await listPullRequests(connectionFor(this, 'bitbucket'), { state: opts.state, author: opts.author, repo: opts.repo });
 			if (s) s.success({ text: `${prs.length} pull request(s) found` });
 			if (mode === 'json') outputJson(curateListJson(prs));
 			else if (mode === 'plain') plainPrList(prs);
@@ -64,7 +48,7 @@ pr.command('view <id>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching PR #${id}...`).start() : null;
 		try {
-			const data = await getPullRequest(id, opts.repo);
+			const data = await getPullRequest(connectionFor(this, 'bitbucket'), id, opts.repo);
 			if (s) s.success({ text: `PR #${id}` });
 			if (mode === 'json') outputJson(curateViewJson(data));
 			else if (mode === 'plain') plainPrView(data);
@@ -82,7 +66,7 @@ pr.command('comments <id>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching comments for PR #${id}...`).start() : null;
 		try {
-			const comments = await getPullRequestComments(id, opts.repo);
+			const comments = await getPullRequestComments(connectionFor(this, 'bitbucket'), id, opts.repo);
 			if (s) s.success({ text: `${comments.length} comment(s)` });
 			if (mode === 'json') outputJson(curateCommentsJson(comments));
 			else if (mode === 'plain') plainPrComments(comments);
@@ -100,7 +84,7 @@ pr.command('diff <id>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching diffstat for PR #${id}...`).start() : null;
 		try {
-			const files = await getPullRequestDiffstat(id, opts.repo);
+			const files = await getPullRequestDiffstat(connectionFor(this, 'bitbucket'), id, opts.repo);
 			if (s) s.success({ text: `${files.length} file(s) changed` });
 			if (mode === 'json') outputJson(curateDiffstatJson(files));
 			else if (mode === 'plain') plainPrDiffstat(files);
@@ -118,7 +102,7 @@ pr.command('activity <id>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching activity for PR #${id}...`).start() : null;
 		try {
-			const activities = await getPullRequestActivity(id, opts.repo);
+			const activities = await getPullRequestActivity(connectionFor(this, 'bitbucket'), id, opts.repo);
 			if (s) s.success({ text: `${activities.length} activity item(s)` });
 			if (mode === 'json') outputJson(curateActivityJson(activities));
 			else if (mode === 'plain') plainPrActivity(activities);

package/src/commands/sd.js

@@ -16,6 +16,7 @@ import {
 import { spinner } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
 import { getOutputMode, outputJson } from '../utils/mode.js';
+import { connectionFor } from '../utils/connection.js';
 
 const sd = new Command('sd')
 	.alias('servicedesk')
@@ -28,7 +29,7 @@ sd.command('view <key>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching ${key}...`).start() : null;
 		try {
-			const issue = await getIssue(key);
+			const issue = await getIssue(connectionFor(this, 'serviceDesk'), key);
 			if (s) s.success({ text: key });
 			if (mode === 'json') outputJson(curateIssueJson(issue));
 			else if (mode === 'plain') plainIssueView(issue);
@@ -45,7 +46,7 @@ sd.command('comments <key>')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner(`Fetching comments for ${key}...`).start() : null;
 		try {
-			const comments = await getIssueComments(key);
+			const comments = await getIssueComments(connectionFor(this, 'serviceDesk'), key);
 			if (s) s.success({ text: `${comments.length} comment(s)` });
 			if (mode === 'json') outputJson(curateCommentsJson(comments));
 			else if (mode === 'plain') plainIssueComments(comments);
@@ -66,7 +67,7 @@ sd.command('search <jql>')
 		const perPage = parseInt(opts.perPage, 10);
 		const s = mode === 'rich' ? spinner('Searching...').start() : null;
 		try {
-			const result = await searchIssues(jql, perPage, opts.next || '');
+			const result = await searchIssues(connectionFor(this, 'serviceDesk'), jql, perPage, opts.next || '');
 			if (s) s.success({ text: `${result.issues.length} issue(s) returned` });
 			if (mode === 'json') outputJson(curateSearchJson(result));
 			else if (mode === 'plain') plainIssueSearch(result);
@@ -78,12 +79,12 @@ sd.command('search <jql>')
 	});
 
 sd.command('queues')
-	.description('List Service Desk queues for the default project')
+	.description('List Service Desk queues for the connection\'s default project')
 	.action(async function () {
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Fetching queues...').start() : null;
 		try {
-			const queues = await listQueues();
+			const queues = await listQueues(connectionFor(this, 'serviceDesk'));
 			if (s) s.success({ text: `${queues.length} queue(s)` });
 			if (mode === 'json') outputJson(curateQueuesJson(queues));
 			else if (mode === 'plain') plainQueueList(queues);
@@ -103,7 +104,7 @@ sd.command('queue <nameOrId>')
 		const perPage = parseInt(opts.perPage, 10);
 		const s = mode === 'rich' ? spinner(`Fetching queue "${nameOrId}"...`).start() : null;
 		try {
-			const result = await searchByQueue(nameOrId, perPage, opts.next || '');
+			const result = await searchByQueue(connectionFor(this, 'serviceDesk'), nameOrId, perPage, opts.next || '');
 			if (s) s.success({ text: `${result.issues.length} issue(s) in "${result.queue.name}"` });
 			if (mode === 'json') outputJson(curateSearchJson(result));
 			else if (mode === 'plain') plainIssueSearch(result);
@@ -121,7 +122,7 @@ sd.command('mine')
 		const mode = getOutputMode(this);
 		const s = mode === 'rich' ? spinner('Fetching my tickets...').start() : null;
 		try {
-			const result = await getMyIssues();
+			const result = await getMyIssues(connectionFor(this, 'serviceDesk'));
 			if (s) s.success({ text: `${result.issues.length} ticket(s)` });
 			if (mode === 'json') outputJson(curateSearchJson(result));
 			else if (mode === 'plain') plainIssueSearch(result);

package/src/config/setup.js

@@ -0,0 +1,113 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import {
+	types, label, listConnections, isDefault, saveConnection, validateName, resolveIndex, fieldProblem,
+} from './store.js';
+
+function answer(value) {
+	if (p.isCancel(value)) {
+		p.cancel('Setup cancelled.');
+		process.exit(0);
+	}
+	return (value ?? '').trim();
+}
+
+export function describe(connections, index) {
+	const connection = connections[index];
+	const { title } = types[connection.type];
+	const sameType = connections.filter((c) => c.type === connection.type).length;
+	const marker = sameType > 1 && isDefault(connections, index) ? ', default' : '';
+	return `${label(connection)} (${title}${marker})`;
+}
+
+async function chooseType() {
+	return answer(await p.select({
+		message: 'Connection type',
+		options: Object.entries(types).map(([value, { title }]) => ({ value, label: title })),
+	}));
+}
+
+// Service Desk Cloud often shares an Atlassian account with Confluence Cloud.
+async function reusableCredentials(connections) {
+	const sources = connections.filter((c) => c.type === 'confluence' && c.email && c.token);
+	if (!sources.length) return null;
+	const choice = answer(await p.select({
+		message: 'Service Desk credentials',
+		options: [
+			...sources.map((c) => ({ value: label(c), label: `Reuse email and token from Confluence connection "${label(c)}"` })),
+			{ value: '', label: 'Enter new credentials' },
+		],
+	}));
+	return sources.find((c) => label(c) === choice) ?? null;
+}
+
+async function promptConnection(type, existing = {}, index = -1) {
+	const connections = listConnections();
+	const connection = { type };
+	if (existing.default) connection.default = true;
+	if (types[type].note) p.note(types[type].note, types[type].title);
+
+	const unnamedTaken = connections.some((c, i) => i !== index && c.type === type && !c.name);
+	connection.name = answer(await p.text({
+		message: unnamedTaken ? 'Connection name' : 'Connection name (optional)',
+		placeholder: unnamedTaken ? 'work' : `leave empty to refer to it as "${type}"`,
+		initialValue: existing.name || '',
+		validate: (v) => validateName(connections, { type, name: (v ?? '').trim() }, index),
+	}));
+
+	const reused = type === 'serviceDesk' ? await reusableCredentials(connections) : null;
+
+	for (const [key, field] of Object.entries(types[type].fields)) {
+		if (reused && (key === 'email' || key === 'token')) {
+			connection[key] = reused[key];
+			continue;
+		}
+		const keep = field.secret && existing[key];
+		const message = keep ? `${field.message} (leave empty to keep the current one)` : field.message;
+		const validate = (v) => {
+			const value = (v ?? '').trim();
+			if (!value) return field.required && !keep ? 'Required' : undefined;
+			return fieldProblem(type, key, value);
+		};
+		const value = field.secret
+			? answer(await p.password({ message, validate }))
+			: answer(await p.text({ message, placeholder: field.placeholder, initialValue: existing[key] || '', validate }));
+		connection[key] = value || (keep ? existing[key] : '');
+	}
+
+	saveConnection(connection, index);
+	return connection;
+}
+
+export async function addConnection(type, name) {
+	p.intro(pc.cyan('Add a connection'));
+	const connection = await promptConnection(type || await chooseType(), { name });
+	p.outro(pc.green(`Saved connection "${label(connection)}"`));
+}
+
+export async function editConnection(ref) {
+	const index = resolveIndex(ref);
+	const existing = listConnections()[index];
+	p.intro(pc.cyan(`Edit connection "${label(existing)}"`));
+	const connection = await promptConnection(existing.type, existing, index);
+	p.outro(pc.green(`Saved connection "${label(connection)}"`));
+}
+
+export async function runSetup() {
+	p.intro(pc.cyan('DevTool Setup'));
+	for (;;) {
+		const connections = listConnections();
+		const choice = answer(await p.select({
+			message: connections.length ? 'Edit a connection, or add a new one' : 'No connections configured yet',
+			options: [
+				...connections.map((_, i) => ({ value: String(i), label: `Edit ${describe(connections, i)}` })),
+				{ value: 'add', label: 'Add a connection' },
+				{ value: 'done', label: 'Done' },
+			],
+		}));
+		if (choice === 'done') break;
+		if (choice === 'add') await promptConnection(await chooseType());
+		else await promptConnection(connections[choice].type, connections[choice], Number(choice));
+	}
+	p.outro(pc.green('Configuration saved!'));
+}