@falldownthesystem/devtool 0.4.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 FallDownTheSystem
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -5,8 +5,7 @@ A terminal-first CLI for working with Bitbucket PRs, Jira tickets, and Confluenc
 ## Install
 
 ```bash
-npm install
-npm link
+npm install -g @falldownthesystem/devtool
 ```
 
 This gives you the `dev` command globally. On first run, it'll walk you through connecting your Bitbucket, Jira, and Confluence accounts.
@@ -54,7 +53,7 @@ Stored via the `conf` package in your OS config directory. You'll need:
 
 - **Bitbucket**: workspace, default repo, email, app password
 - **Jira**: base URL, API token, default project
-- **Confluence**: uses the same Jira base URL and token
+- **Confluence**: base URL, email, API token, default space. Cloud and Server/Data Center are detected from the base URL. For Server/Data Center, include any context path (`https://company.com/confluence`) and leave the email empty to use a personal access token, or set it to your username for Basic auth.
 
 ## License
 

package/package.json

@@ -1,17 +1,35 @@
 {
 	"name": "@falldownthesystem/devtool",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "CLI for Bitbucket PRs, Jira tickets, Confluence pages, and Service Desk tickets",
 	"type": "module",
 	"bin": {
 		"dev": "src/index.js"
 	},
+	"files": [
+		"src/"
+	],
 	"scripts": {
-		"start": "node src/index.js"
+		"start": "node src/index.js",
+		"test": "node --test test/config.test.js test/confluence.test.js test/service-desk.test.js"
 	},
-	"keywords": [],
-	"author": "",
+	"keywords": [
+		"cli",
+		"bitbucket",
+		"jira",
+		"confluence",
+		"pull-request",
+		"devtools"
+	],
+	"author": "FallDownTheSystem",
 	"license": "ISC",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/FallDownTheSystem/devtool.git"
+	},
+	"engines": {
+		"node": ">=18"
+	},
 	"dependencies": {
 		"@clack/prompts": "^1.0.0",
 		"cli-table3": "^0.6.5",

package/src/clients/confluence.js

@@ -1,63 +1,171 @@
-import { get } from '../config/store.js';
-
-function baseUrl() {
-	return `${get('confluence.baseUrl')}/wiki`;
-}
-
-function authHeader() {
-	const email = get('confluence.email');
-	const token = get('confluence.token');
-	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
-}
-
-async function request(path, params = {}) {
-	const url = new URL(path.startsWith('http') ? path : `${baseUrl()}${path}`);
-	for (const [k, v] of Object.entries(params)) {
-		if (v !== undefined && v !== null) url.searchParams.set(k, v);
-	}
-
-	const res = await fetch(url, {
-		headers: {
-			'Authorization': authHeader(),
-			'Accept': 'application/json',
-		},
-	});
-
-	if (!res.ok) {
-		const err = new Error(`Confluence API error: ${res.status} ${res.statusText}`);
-		err.status = res.status;
-		err.url = url.toString();
-		throw err;
-	}
-
-	return res.json();
-}
-
-async function paginateV2(path, params = {}) {
-	const results = [];
-	let data = await request(path, params);
-	results.push(...(data.results || []));
-
-	while (data._links?.next) {
-		data = await request(data._links.next);
-		results.push(...(data.results || []));
-	}
-
-	return results;
-}
-
-export async function listSpaces() {
-	return paginateV2('/api/v2/spaces');
-}
-
-export async function getPage(id) {
-	return request(`/api/v2/pages/${id}`, { 'body-format': 'storage' });
-}
-
-export async function listSpacePages(spaceId) {
-	return paginateV2(`/api/v2/spaces/${spaceId}/pages`);
-}
-
-export async function searchPages(cql) {
-	return request('/rest/api/search', { cql });
-}
+import { get } from '../config/store.js';
+
+const deployments = new Map();
+
+// Custom domains hide the atlassian.net hostname, so anything else is probed:
+// Atlassian's edge answers tenant_info anonymously, Server/Data Center does not.
+async function detectDeployment(origin) {
+	if (/\.atlassian\.net$/i.test(new URL(origin).hostname)) return 'cloud';
+	try {
+		const res = await fetch(new URL('/_edge/tenant_info', origin), {
+			headers: { 'Accept': 'application/json' },
+		});
+		if (res.ok && (await res.json()).cloudId) return 'cloud';
+	} catch {
+		// An unreachable or non-JSON probe means no Atlassian edge; the real request reports connection errors.
+	}
+	return 'server';
+}
+
+async function connect() {
+	const base = new URL(get('confluence.baseUrl'));
+	if (!deployments.has(base.origin)) deployments.set(base.origin, detectDeployment(base.origin));
+	const kind = await deployments.get(base.origin);
+	// Cloud always serves Confluence under /wiki; Server/Data Center keeps its own context path.
+	const path = kind === 'cloud' ? '/wiki' : base.pathname.replace(/\/+$/, '');
+	return { kind, origin: base.origin, path };
+}
+
+function apiUrl(conn, path) {
+	return new URL(`${conn.origin}${conn.path}${path}`);
+}
+
+// Cloud v2 links are origin-relative, Server/Data Center links are relative to the context path.
+function nextUrl(conn, link, current) {
+	const contextRelative = conn.kind === 'server'
+		&& link.startsWith('/') && !link.startsWith('//')
+		&& !(conn.path && link.startsWith(`${conn.path}/`));
+	return contextRelative ? apiUrl(conn, link) : new URL(link, current);
+}
+
+// Server/Data Center personal access tokens use Bearer auth; a username switches to Basic.
+function authHeader(conn) {
+	const email = get('confluence.email');
+	const token = get('confluence.token');
+	if (conn.kind === 'server' && !email) return `Bearer ${token}`;
+	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+}
+
+async function request(conn, url, params = {}) {
+	if (url.origin !== conn.origin) {
+		throw new Error('Confluence pagination points to a different site. Check confluence.baseUrl.');
+	}
+	for (const [k, v] of Object.entries(params)) {
+		if (v !== undefined && v !== null) url.searchParams.set(k, v);
+	}
+
+	const res = await fetch(url, {
+		headers: {
+			'Authorization': authHeader(conn),
+			'Accept': 'application/json',
+		},
+	});
+
+	if (!res.ok) {
+		const err = new Error(`Confluence API error: ${res.status} ${res.statusText}`);
+		err.status = res.status;
+		err.url = url.toString();
+		throw err;
+	}
+
+	// Server/Data Center answers rejected credentials with a login page instead of a 401.
+	if (!res.headers.get('content-type')?.includes('json')) {
+		const err = new Error('Confluence returned a non-JSON response. Check confluence.baseUrl and confluence.token.');
+		err.url = url.toString();
+		throw err;
+	}
+
+	return res.json();
+}
+
+async function paginate(conn, path, params = {}) {
+	const results = [];
+	let url = apiUrl(conn, path);
+	let data = await request(conn, url, params);
+	results.push(...(data.results || []));
+
+	while (data._links?.next) {
+		url = nextUrl(conn, data._links.next, url);
+		data = await request(conn, url);
+		results.push(...(data.results || []));
+	}
+
+	return results;
+}
+
+// Server/Data Center v1 content is reshaped to the Cloud v2 fields the formatters read.
+function serverSpace(space) {
+	return {
+		id: String(space.id),
+		key: space.key,
+		name: space.name,
+		type: space.type,
+		status: space.status,
+	};
+}
+
+function serverPage(page) {
+	return {
+		id: page.id,
+		title: page.title,
+		status: page.status,
+		spaceId: page.space?.id != null ? String(page.space.id) : undefined,
+		createdAt: page.history?.createdDate,
+		version: page.version ? { number: page.version.number } : undefined,
+		body: page.body,
+	};
+}
+
+// The content listing silently returns nothing for an unknown space key, so the space is looked up first.
+async function serverSpaceKey(conn, { spaceId, spaceKey }) {
+	if (!spaceKey) return (await listSpaces()).find((s) => s.id === String(spaceId))?.key;
+	try {
+		return (await request(conn, apiUrl(conn, `/rest/api/space/${encodeURIComponent(spaceKey)}`))).key;
+	} catch (err) {
+		if (err.status === 404) return undefined;
+		throw err;
+	}
+}
+
+export async function listSpaces() {
+	const conn = await connect();
+	if (conn.kind === 'cloud') return paginate(conn, '/api/v2/spaces');
+	return (await paginate(conn, '/rest/api/space', { limit: 100 })).map(serverSpace);
+}
+
+export async function getPage(id) {
+	const conn = await connect();
+	if (conn.kind === 'cloud') {
+		return request(conn, apiUrl(conn, `/api/v2/pages/${id}`), { 'body-format': 'storage' });
+	}
+	return serverPage(await request(conn, apiUrl(conn, `/rest/api/content/${id}`), {
+		expand: 'body.storage,version,space,history',
+	}));
+}
+
+// Cloud lists pages by space ID and Server/Data Center by space key; returns null for an unknown space.
+export async function listSpacePages({ spaceId, spaceKey }) {
+	const conn = await connect();
+	if (conn.kind === 'cloud') {
+		const id = spaceId
+			?? (await request(conn, apiUrl(conn, '/api/v2/spaces'), { keys: spaceKey })).results?.[0]?.id;
+		if (!id) return null;
+		return paginate(conn, `/api/v2/spaces/${id}/pages`);
+	}
+
+	const key = await serverSpaceKey(conn, { spaceId, spaceKey });
+	if (!key) return null;
+	const pages = await paginate(conn, '/rest/api/content', {
+		spaceKey: key,
+		type: 'page',
+		expand: 'version,history',
+		limit: 100,
+	});
+	return pages.map(serverPage);
+}
+
+export async function searchPages(cql) {
+	const conn = await connect();
+	const result = await request(conn, apiUrl(conn, '/rest/api/search'), { cql });
+	return { ...result, totalSize: result.totalSize ?? result.totalCount };
+}

package/src/clients/serviceDesk.js

@@ -1,119 +1,181 @@
-import { get } from '../config/store.js';
-
-function baseUrl() {
-	return get('serviceDesk.baseUrl');
-}
-
-function authHeader() {
-	const email = get('serviceDesk.email');
-	const token = get('serviceDesk.token');
-	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
-}
-
-async function request(path, params = {}, extraHeaders = {}) {
-	const url = new URL(path.startsWith('http') ? path : `${baseUrl()}${path}`);
-	for (const [k, v] of Object.entries(params)) {
-		if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, v);
-	}
-
-	const res = await fetch(url, {
-		headers: {
-			'Authorization': authHeader(),
-			'Accept': 'application/json',
-			...extraHeaders,
-		},
-	});
-
-	if (!res.ok) {
-		const err = new Error(`Service Desk API error: ${res.status} ${res.statusText}`);
-		err.status = res.status;
-		err.url = url.toString();
-		throw err;
-	}
-
-	return res.json();
-}
-
-export async function getIssue(issueKey) {
-	return request(`/rest/api/3/issue/${encodeURIComponent(issueKey)}`, {
-		expand: 'renderedFields',
-	});
-}
-
-export async function getIssueComments(issueKey) {
-	const data = await request(`/rest/api/3/issue/${encodeURIComponent(issueKey)}/comment`, {
-		orderBy: 'created',
-		maxResults: 100,
-	});
-	return data.comments || [];
-}
-
-export async function searchIssues(jql, maxResults = 50, nextPageToken = '') {
-	const fields = 'summary,status,assignee,priority,updated,issuetype,reporter,customfield_10010';
-	const data = await request('/rest/api/3/search/jql', {
-		jql,
-		fields,
-		maxResults,
-		nextPageToken,
-	});
-	return {
-		issues: data.issues || [],
-		nextPageToken: data.nextPageToken || null,
-		isLast: data.isLast !== false,
-		maxResults,
-	};
-}
-
-export async function getMyIssues() {
-	const project = get('serviceDesk.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);
-}
-
-let _serviceDeskIdCache = null;
-
-async function getServiceDeskId(projectKey) {
-	if (_serviceDeskIdCache && _serviceDeskIdCache.projectKey === projectKey) {
-		return _serviceDeskIdCache.id;
-	}
-	const data = await request('/rest/servicedeskapi/servicedesk', { start: 0, limit: 100 }, { 'X-ExperimentalApi': 'opt-in' });
-	const match = (data.values || []).find((sd) => sd.projectKey === projectKey);
-	if (!match) {
-		throw new Error(`No Service Desk found for project ${projectKey}`);
-	}
-	_serviceDeskIdCache = { projectKey, id: 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 }, { 'X-ExperimentalApi': 'opt-in' });
-	return (data.values || []).map((q) => ({ id: q.id, name: q.name, jql: q.jql }));
-}
-
-export async function findQueue(nameOrId) {
-	const queues = await listQueues();
-	const idMatch = queues.find((q) => String(q.id) === String(nameOrId));
-	if (idMatch) return idMatch;
-	const lower = nameOrId.toLowerCase();
-	const exact = queues.find((q) => q.name.toLowerCase() === lower);
-	if (exact) return exact;
-	const partial = queues.filter((q) => q.name.toLowerCase().includes(lower));
-	if (partial.length === 1) return partial[0];
-	if (partial.length > 1) {
-		const err = new Error(`Ambiguous queue "${nameOrId}" — matches: ${partial.map((q) => q.name).join(', ')}`);
-		err.candidates = partial;
-		throw err;
-	}
-	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);
-	return { ...result, queue };
-}
+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.`);
+}
+
+function baseUrl() {
+	let url;
+	try {
+		url = new URL(get('serviceDesk.baseUrl'));
+	} catch {
+		throw configurationError('invalid base URL');
+	}
+	if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || /[^/]/.test(url.pathname)) {
+		throw configurationError('the base URL must be an HTTPS site URL without a path, query, or credentials');
+	}
+	return new URL(url.origin);
+}
+
+function authHeader() {
+	const email = get('serviceDesk.email');
+	const token = get('serviceDesk.token');
+	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+}
+
+async function fetchJson(url, headers = {}) {
+	const res = await fetch(url, {
+		redirect: 'manual',
+		headers: { 'Accept': 'application/json', ...headers },
+	});
+
+	if (res.redirected || (res.status >= 300 && res.status < 400)) {
+		throw configurationError('the API returned a redirect; authentication may not reach the intended site');
+	}
+	if (res.url && new URL(res.url).origin !== url.origin) {
+		throw configurationError('the API response came from an unexpected host');
+	}
+	if (!res.ok) {
+		const err = new Error(`Service Desk API error: ${res.status} ${res.statusText}`);
+		err.status = res.status;
+		err.url = url.toString();
+		throw err;
+	}
+
+	const contentType = res.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
+	if (!/^application\/(?:[\w.+-]+\+)?json$/.test(contentType || '')) {
+		throw configurationError('expected a JSON API response, but received a different content type');
+	}
+	let data;
+	try {
+		data = await res.json();
+	} catch {
+		throw configurationError('the API response contains invalid JSON');
+	}
+	if (!data || typeof data !== 'object' || Array.isArray(data)) {
+		throw configurationError('unexpected API response structure');
+	}
+	return data;
+}
+
+async function request(path, params = {}, { extraHeaders = {}, validate = () => true } = {}) {
+	const site = baseUrl();
+	if (!site.hostname.endsWith('.atlassian.net')) {
+		const info = await fetchJson(new URL('/rest/api/2/serverInfo', site));
+		let canonical;
+		try {
+			canonical = new URL(info.baseUrl);
+		} catch {
+			throw configurationError('serverInfo did not return a valid canonical base URL');
+		}
+		if (canonical.origin !== site.origin || canonical.pathname.replace(/\/+$/, '') !== '') {
+			throw configurationError(`serverInfo identifies a different canonical base URL: ${canonical.origin}${canonical.pathname.replace(/\/+$/, '')}`);
+		}
+	}
+
+	const url = new URL(path, site);
+	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 });
+	if (!validate(data)) throw configurationError('unexpected API response structure');
+	return data;
+}
+
+export async function getIssue(issueKey) {
+	return request(`/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`, {
+		orderBy: 'created',
+		maxResults: 100,
+	}, {
+		validate: (data) => Array.isArray(data.comments),
+	});
+	return data.comments;
+}
+
+export async function searchIssues(jql, maxResults = 50, nextPageToken = '') {
+	const fields = 'summary,status,assignee,priority,updated,issuetype,reporter,customfield_10010';
+	const data = await request('/rest/api/3/search/jql', {
+		jql,
+		fields,
+		maxResults,
+		nextPageToken,
+	}, {
+		validate: (data) => Array.isArray(data.issues)
+			&& (data.isLast === undefined || typeof data.isLast === 'boolean')
+			&& (data.nextPageToken == null || typeof data.nextPageToken === 'string'),
+	});
+	return {
+		issues: data.issues,
+		nextPageToken: data.nextPageToken || null,
+		isLast: data.isLast !== false,
+		maxResults,
+	};
+}
+
+export async function getMyIssues() {
+	const project = get('serviceDesk.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);
+}
+
+let _serviceDeskIdCache = null;
+
+async function getServiceDeskId(projectKey) {
+	if (_serviceDeskIdCache && _serviceDeskIdCache.projectKey === projectKey) {
+		return _serviceDeskIdCache.id;
+	}
+	const data = await request('/rest/servicedeskapi/servicedesk', { start: 0, limit: 100 }, {
+		extraHeaders: { 'X-ExperimentalApi': 'opt-in' },
+		validate: (data) => Array.isArray(data.values),
+	});
+	const match = data.values.find((sd) => sd.projectKey === projectKey);
+	if (!match) {
+		throw new Error(`No Service Desk found for project ${projectKey}`);
+	}
+	_serviceDeskIdCache = { projectKey, id: 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 }, {
+		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();
+	const idMatch = queues.find((q) => String(q.id) === String(nameOrId));
+	if (idMatch) return idMatch;
+	const lower = nameOrId.toLowerCase();
+	const exact = queues.find((q) => q.name.toLowerCase() === lower);
+	if (exact) return exact;
+	const partial = queues.filter((q) => q.name.toLowerCase().includes(lower));
+	if (partial.length === 1) return partial[0];
+	if (partial.length > 1) {
+		const err = new Error(`Ambiguous queue "${nameOrId}" — matches: ${partial.map((q) => q.name).join(', ')}`);
+		err.candidates = partial;
+		throw err;
+	}
+	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);
+	return { ...result, queue };
+}