@falldownthesystem/devtool 0.4.0 → 0.4.1

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.

package/package.json

@@ -1,17 +1,35 @@
 {
 	"name": "@falldownthesystem/devtool",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"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,7 +1,7 @@
 import { get } from '../config/store.js';
 
-function baseUrl() {
-	return `${get('confluence.baseUrl')}/wiki`;
+function apiUrl(path) {
+	return new URL(`/wiki${path}`, get('confluence.baseUrl'));
 }
 
 function authHeader() {
@@ -10,8 +10,10 @@ function authHeader() {
 	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
 }
 
-async function request(path, params = {}) {
-	const url = new URL(path.startsWith('http') ? path : `${baseUrl()}${path}`);
+async function request(url, params = {}) {
+	if (url.origin !== new URL(get('confluence.baseUrl')).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);
 	}
@@ -35,11 +37,13 @@ async function request(path, params = {}) {
 
 async function paginateV2(path, params = {}) {
 	const results = [];
-	let data = await request(path, params);
+	let url = apiUrl(path);
+	let data = await request(url, params);
 	results.push(...(data.results || []));
 
 	while (data._links?.next) {
-		data = await request(data._links.next);
+		url = new URL(data._links.next, url);
+		data = await request(url);
 		results.push(...(data.results || []));
 	}
 
@@ -51,7 +55,7 @@ export async function listSpaces() {
 }
 
 export async function getPage(id) {
-	return request(`/api/v2/pages/${id}`, { 'body-format': 'storage' });
+	return request(apiUrl(`/api/v2/pages/${id}`), { 'body-format': 'storage' });
 }
 
 export async function listSpacePages(spaceId) {
@@ -59,5 +63,5 @@ export async function listSpacePages(spaceId) {
 }
 
 export async function searchPages(cql) {
-	return request('/rest/api/search', { cql });
+	return request(apiUrl('/rest/api/search'), { cql });
 }

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 };
+}

package/src/commands/config.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { getAll, set, runSetup, configPath, isConfigured } from '../config/store.js';
+import { getAll, set, runSetup, configPath, schema } from '../config/store.js';
 import { heading, field, mask, success, error, divider } from '../utils/output.js';
 
 const config = new Command('config')
@@ -17,29 +17,15 @@ config
 	.alias('get')
 	.description('Show current configuration')
 	.action(() => {
-		if (!isConfigured()) {
-			error('Not configured yet. Run: dev config setup');
-			return;
-		}
-
 		const all = getAll();
 
-		heading('Bitbucket');
-		field('Workspace', all.bitbucket.workspace);
-		field('Default repo', all.bitbucket.defaultRepo);
-		field('Email', all.bitbucket.email);
-		field('Token', mask(all.bitbucket.token));
-
-		heading('Jira');
-		field('Base URL', all.jira.baseUrl);
-		field('Token', mask(all.jira.token));
-		field('Default project', all.jira.defaultProject);
-
-		heading('Confluence');
-		field('Base URL', all.confluence.baseUrl);
-		field('Email', all.confluence.email);
-		field('Token', mask(all.confluence.token));
-		field('Default space', all.confluence.defaultSpace);
+		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);
+			}
+		}
 
 		console.log('');
 		divider();
@@ -51,11 +37,8 @@ config
 	.command('set <key> <value>')
 	.description('Set a config value (e.g. bitbucket.workspace my-ws)')
 	.action((key, value) => {
-		const validKeys = [
-			'bitbucket.workspace', 'bitbucket.defaultRepo', 'bitbucket.email', 'bitbucket.token',
-			'jira.baseUrl', 'jira.token', 'jira.defaultProject',
-			'confluence.baseUrl', 'confluence.email', 'confluence.token', 'confluence.defaultSpace',
-		];
+		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(', ')}`);