@falldownthesystem/devtool 0.1.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

@@ -0,0 +1,59 @@
+# dev
+
+A terminal-first CLI for working with Bitbucket PRs, Jira tickets, and Confluence pages. Skip the browser, stay in your terminal.
+
+## Install
+
+```bash
+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.
+
+## Usage
+
+```bash
+dev pr list                  # your open PRs
+dev pr view 42               # PR details, reviewers, status
+dev pr comments 42           # review comments
+dev pr diff 42               # changed files
+dev pr activity 42           # approvals, updates, comments
+
+dev jira view PROJ-123       # ticket details
+dev jira comments PROJ-123   # ticket comments
+dev jira search "sprint = 5" # JQL search
+dev jira mine                # your open tickets
+
+dev confluence spaces        # list spaces
+dev confluence view 12345    # read a page
+dev confluence pages         # pages in a space
+dev confluence search "auth" # CQL search
+
+dev config setup             # re-run setup
+dev config show              # current config (tokens masked)
+dev config set <key> <value> # set a single value
+```
+
+Most commands have short aliases: `ls`, `read`, `find`, `my`.
+
+### Output modes
+
+Every command supports three output formats:
+
+```bash
+dev pr list              # colored tables (default)
+dev pr list --plain      # no colors, no tables, pipe-friendly
+dev pr list --json       # curated JSON, not raw API dumps
+```
+
+## Config
+
+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
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@falldownthesystem/devtool",
+	"version": "0.1.0",
+	"description": "CLI for Bitbucket PRs, Jira tickets, and Confluence pages",
+	"type": "module",
+	"bin": {
+		"dev": "src/index.js"
+	},
+	"files": [
+		"src/"
+	],
+	"scripts": {
+		"start": "node src/index.js"
+	},
+	"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",
+		"commander": "^14.0.3",
+		"conf": "^15.1.0",
+		"jira.js": "^5.3.0",
+		"picocolors": "^1.1.1"
+	}
+}

package/src/clients/bitbucket.js

@@ -0,0 +1,85 @@
+import { get } from '../config/store.js';
+
+const BASE_URL = 'https://api.bitbucket.org/2.0';
+
+function authHeader() {
+	const email = get('bitbucket.email');
+	const token = get('bitbucket.token');
+	return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
+}
+
+function repoPath(repoOverride) {
+	const workspace = get('bitbucket.workspace');
+	const repo = repoOverride || get('bitbucket.defaultRepo');
+	return `/repositories/${workspace}/${repo}`;
+}
+
+async function request(path, params = {}) {
+	const url = new URL(path.startsWith('http') ? path : `${BASE_URL}${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(`Bitbucket API error: ${res.status} ${res.statusText}`);
+		err.status = res.status;
+		err.url = url.toString();
+		throw err;
+	}
+
+	return res.json();
+}
+
+async function paginate(path, params = {}) {
+	const results = [];
+	let data = await request(path, params);
+	results.push(...(data.values || []));
+
+	while (data.next) {
+		data = await request(data.next);
+		results.push(...(data.values || []));
+	}
+
+	return results;
+}
+
+export async function listPullRequests(options = {}) {
+	const { state = 'OPEN', author, repo } = options;
+	const path = `${repoPath(repo)}/pullrequests`;
+	const params = { state, pagelen: 50 };
+
+	const prs = await paginate(path, params);
+
+	if (author) {
+		const authorLower = author.toLowerCase();
+		return prs.filter((pr) =>
+			pr.author.display_name.toLowerCase().includes(authorLower)
+			|| pr.author.nickname?.toLowerCase().includes(authorLower)
+		);
+	}
+
+	return prs;
+}
+
+export async function getPullRequest(id, repo) {
+	return request(`${repoPath(repo)}/pullrequests/${id}`);
+}
+
+export async function getPullRequestComments(id, repo) {
+	return paginate(`${repoPath(repo)}/pullrequests/${id}/comments`);
+}
+
+export async function getPullRequestDiffstat(id, repo) {
+	return paginate(`${repoPath(repo)}/pullrequests/${id}/diffstat`);
+}
+
+export async function getPullRequestActivity(id, repo) {
+	return paginate(`${repoPath(repo)}/pullrequests/${id}/activity`);
+}

package/src/clients/confluence.js

@@ -0,0 +1,63 @@
+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 });
+}

package/src/clients/jira.js

@@ -0,0 +1,61 @@
+import { Version2Client } from 'jira.js';
+import { get } from '../config/store.js';
+
+let client = null;
+
+function getClient() {
+	if (!client) {
+		const token = get('jira.token');
+		client = new Version2Client({
+			host: get('jira.baseUrl'),
+			authentication: {
+				basic: { email: '', apiToken: token },
+			},
+		});
+		client.instance.interceptors.request.use((config) => {
+			config.headers['Authorization'] = `Bearer ${token}`;
+			return config;
+		});
+	}
+	return client;
+}
+
+export async function getIssue(issueKey) {
+	return getClient().issues.getIssue({
+		issueIdOrKey: issueKey,
+		fields: ['*all'],
+		expand: 'renderedFields',
+	});
+}
+
+export async function getIssueComments(issueKey) {
+	const result = await getClient().issueComments.getComments({
+		issueIdOrKey: issueKey,
+		orderBy: 'created',
+		maxResults: 100,
+	});
+	return result.comments || [];
+}
+
+export async function searchIssues(jql, startAt = 0, maxResults = 50) {
+	const result = await getClient().issueSearch.searchForIssuesUsingJql({
+		jql,
+		startAt,
+		maxResults,
+		fields: ['key', 'summary', 'status', 'assignee', 'priority', 'updated'],
+	});
+	return {
+		issues: result.issues || [],
+		total: result.total || 0,
+		startAt: result.startAt || 0,
+		maxResults: result.maxResults || maxResults,
+	};
+}
+
+export async function getMyIssues() {
+	const project = get('jira.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);
+}

package/src/commands/config.js

@@ -0,0 +1,68 @@
+import { Command } from 'commander';
+import { getAll, set, runSetup, configPath, isConfigured } from '../config/store.js';
+import { heading, field, mask, success, error, divider } from '../utils/output.js';
+
+const config = new Command('config')
+	.description('Manage configuration');
+
+config
+	.command('setup')
+	.description('Run interactive setup')
+	.action(async () => {
+		await runSetup();
+	});
+
+config
+	.command('show')
+	.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);
+
+		console.log('');
+		divider();
+		field('Config file', configPath());
+		console.log('');
+	});
+
+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',
+		];
+		if (!validKeys.includes(key)) {
+			error(`Invalid key: ${key}`);
+			console.log(`Valid keys: ${validKeys.join(', ')}`);
+			return;
+		}
+		set(key, value);
+		success(`Set ${key}`);
+	});
+
+export default config;

package/src/commands/confluence.js

@@ -0,0 +1,113 @@
+import { Command } from 'commander';
+import {
+	listSpaces,
+	getPage,
+	listSpacePages,
+	searchPages,
+} from '../clients/confluence.js';
+import {
+	formatSpaces, formatPageView, formatPages, formatSearch,
+	plainSpaces, plainPageView, plainPages, plainSearch,
+	curateSpacesJson, curatePageJson, curatePagesJson, curateSearchJson,
+} from '../formatters/confluence.js';
+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';
+
+const confluence = new Command('confluence')
+	.description('Confluence pages');
+
+confluence.command('spaces')
+	.description('List all spaces')
+	.action(async function () {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner('Fetching spaces...').start() : null;
+		try {
+			const spaces = await listSpaces();
+			if (s) s.success({ text: `${spaces.length} space(s) found` });
+			if (mode === 'json') outputJson(curateSpacesJson(spaces));
+			else if (mode === 'plain') plainSpaces(spaces);
+			else formatSpaces(spaces);
+		} catch (err) {
+			if (s) s.error({ text: 'Failed to fetch spaces' });
+			handleError(err, err.url || 'confluence');
+		}
+	});
+
+confluence.command('view <id>')
+	.alias('read')
+	.description('View a page')
+	.action(async function (id) {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner(`Fetching page ${id}...`).start() : null;
+		try {
+			const page = await getPage(id);
+			if (s) s.success({ text: page.title || `Page ${id}` });
+			if (mode === 'json') outputJson(curatePageJson(page));
+			else if (mode === 'plain') plainPageView(page);
+			else formatPageView(page);
+		} catch (err) {
+			if (s) s.error({ text: `Failed to fetch page ${id}` });
+			handleError(err, err.url || 'confluence');
+		}
+	});
+
+confluence.command('pages')
+	.alias('ls')
+	.description('List pages in a space')
+	.option('-s, --space <key>', 'Space key (overrides default)')
+	.option('--space-id <id>', 'Space ID (skip key lookup)')
+	.action(async function (opts) {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner('Fetching pages...').start() : null;
+		try {
+			let spaceId = opts.spaceId;
+			if (!spaceId) {
+				const spaceKey = opts.space || get('confluence.defaultSpace');
+				if (!spaceKey) {
+					if (s) s.error({ text: 'No space specified' });
+					console.error('Specify --space <key>, --space-id <id>, or set confluence.defaultSpace');
+					process.exitCode = 1;
+					return;
+				}
+				const spaces = await listSpaces();
+				const match = spaces.find((sp) => sp.key === spaceKey);
+				if (!match) {
+					if (s) s.error({ text: `Space "${spaceKey}" not found` });
+					process.exitCode = 1;
+					return;
+				}
+				spaceId = match.id;
+			}
+			const pages = await listSpacePages(spaceId);
+			if (s) s.success({ text: `${pages.length} page(s) found` });
+			if (mode === 'json') outputJson(curatePagesJson(pages));
+			else if (mode === 'plain') plainPages(pages);
+			else formatPages(pages);
+		} catch (err) {
+			if (s) s.error({ text: 'Failed to fetch pages' });
+			handleError(err, err.url || 'confluence');
+		}
+	});
+
+confluence.command('search <cql>')
+	.alias('find')
+	.description('Search pages with CQL')
+	.action(async function (cql) {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner('Searching...').start() : null;
+		try {
+			const result = await searchPages(cql);
+			const count = result.totalSize || (result.results || []).length;
+			if (s) s.success({ text: `${count} result(s)` });
+			if (mode === 'json') outputJson(curateSearchJson(result));
+			else if (mode === 'plain') plainSearch(result);
+			else formatSearch(result);
+		} catch (err) {
+			if (s) s.error({ text: 'Search failed' });
+			handleError(err, err.url || 'confluence');
+		}
+	});
+
+export default confluence;

package/src/commands/jira.js

@@ -0,0 +1,95 @@
+import { Command } from 'commander';
+import {
+	getIssue,
+	getIssueComments,
+	searchIssues,
+	getMyIssues,
+} from '../clients/jira.js';
+import {
+	formatIssueView, formatIssueComments, formatIssueSearch,
+	plainIssueView, plainIssueComments, plainIssueSearch,
+	curateIssueJson, curateCommentsJson, curateSearchJson,
+} from '../formatters/jira.js';
+import { spinner } from '../utils/output.js';
+import { handleError } from '../utils/errors.js';
+import { getOutputMode, outputJson } from '../utils/mode.js';
+
+const jira = new Command('jira')
+	.description('Jira tickets');
+
+jira.command('view <key>')
+	.alias('read')
+	.description('View issue details')
+	.action(async function (key) {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner(`Fetching ${key}...`).start() : null;
+		try {
+			const issue = await getIssue(key);
+			if (s) s.success({ text: key });
+			if (mode === 'json') outputJson(curateIssueJson(issue));
+			else if (mode === 'plain') plainIssueView(issue);
+			else formatIssueView(issue);
+		} catch (err) {
+			if (s) s.error({ text: `Failed to fetch ${key}` });
+			handleError(err, `jira issue ${key}`);
+		}
+	});
+
+jira.command('comments <key>')
+	.description('List issue comments')
+	.action(async function (key) {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner(`Fetching comments for ${key}...`).start() : null;
+		try {
+			const comments = await getIssueComments(key);
+			if (s) s.success({ text: `${comments.length} comment(s)` });
+			if (mode === 'json') outputJson(curateCommentsJson(comments));
+			else if (mode === 'plain') plainIssueComments(comments);
+			else formatIssueComments(comments);
+		} catch (err) {
+			if (s) s.error({ text: `Failed to fetch comments for ${key}` });
+			handleError(err, `jira comments ${key}`);
+		}
+	});
+
+jira.command('search <jql>')
+	.alias('find')
+	.description('Search issues with JQL')
+	.option('-p, --page <number>', 'Page number', '1')
+	.option('-n, --per-page <number>', 'Results per page', '20')
+	.action(async function (jql, opts) {
+		const mode = getOutputMode(this);
+		const perPage = parseInt(opts.perPage, 10);
+		const startAt = (parseInt(opts.page, 10) - 1) * perPage;
+		const s = mode === 'rich' ? spinner('Searching...').start() : null;
+		try {
+			const result = await searchIssues(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);
+			else formatIssueSearch(result);
+		} catch (err) {
+			if (s) s.error({ text: 'Search failed' });
+			handleError(err, `jira search "${jql}"`);
+		}
+	});
+
+jira.command('mine')
+	.alias('my')
+	.description('Show my open issues')
+	.action(async function () {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner('Fetching my issues...').start() : null;
+		try {
+			const result = await getMyIssues();
+			if (s) s.success({ text: `${result.total} issue(s)` });
+			if (mode === 'json') outputJson(curateSearchJson(result));
+			else if (mode === 'plain') plainIssueSearch(result);
+			else formatIssueSearch(result);
+		} catch (err) {
+			if (s) s.error({ text: 'Failed to fetch issues' });
+			handleError(err, 'jira my issues');
+		}
+	});
+
+export default jira;