@falldownthesystem/devtool 0.1.0

package/src/formatters/jira.js

@@ -0,0 +1,236 @@
+import { table, heading, field, divider, pc } from '../utils/output.js';
+
+function statusColor(name) {
+	if (!name) return pc.dim('Unknown');
+	const lower = name.toLowerCase();
+	if (lower === 'done' || lower === 'closed' || lower === 'resolved') return pc.green(name);
+	if (lower === 'in progress' || lower === 'in review') return pc.blue(name);
+	if (lower === 'to do' || lower === 'open' || lower === 'backlog') return pc.yellow(name);
+	return name;
+}
+
+function priorityColor(name) {
+	if (!name) return pc.dim('None');
+	const lower = name.toLowerCase();
+	if (lower === 'highest' || lower === 'blocker') return pc.red(pc.bold(name));
+	if (lower === 'high' || lower === 'critical') return pc.red(name);
+	if (lower === 'low' || lower === 'minor') return pc.dim(name);
+	if (lower === 'lowest' || lower === 'trivial') return pc.dim(name);
+	return name;
+}
+
+function relativeTime(dateStr) {
+	if (!dateStr) return '';
+	const diff = Date.now() - new Date(dateStr).getTime();
+	const mins = Math.floor(diff / 60000);
+	if (mins < 60) return `${mins}m ago`;
+	const hours = Math.floor(mins / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	if (days < 30) return `${days}d ago`;
+	return new Date(dateStr).toLocaleDateString();
+}
+
+function extractSprint(fields) {
+	for (const key of Object.keys(fields)) {
+		if (!key.startsWith('customfield_')) continue;
+		const val = fields[key];
+		if (Array.isArray(val) && val.length > 0 && typeof val[0] === 'object' && val[0].name) {
+			if ('state' in val[0] || 'goal' in val[0]) {
+				return val[val.length - 1].name;
+			}
+		}
+		if (typeof val === 'string' && val.includes('com.atlassian.greenhopper')) {
+			const match = val.match(/name=([^,\]]+)/);
+			if (match) return match[1];
+		}
+	}
+	return null;
+}
+
+function extractStoryPoints(fields) {
+	for (const key of Object.keys(fields)) {
+		if (!key.startsWith('customfield_')) continue;
+		const val = fields[key];
+		if (typeof val === 'number' && val > 0 && val <= 100) {
+			const keyNum = parseInt(key.replace('customfield_', ''), 10);
+			if (keyNum > 10000) return val;
+		}
+	}
+	return null;
+}
+
+function descriptionText(desc) {
+	if (!desc) return '';
+	return typeof desc === 'string' ? desc : JSON.stringify(desc);
+}
+
+// --- JSON curators ---
+
+export function curateIssueJson(issue) {
+	const f = issue.fields;
+	return {
+		key: issue.key,
+		summary: f.summary,
+		status: f.status?.name || null,
+		priority: f.priority?.name || null,
+		type: f.issuetype?.name || null,
+		assignee: f.assignee?.displayName || null,
+		reporter: f.reporter?.displayName || null,
+		labels: f.labels || [],
+		components: (f.components || []).map((c) => c.name),
+		sprint: extractSprint(f),
+		storyPoints: extractStoryPoints(f),
+		created: f.created,
+		updated: f.updated,
+		description: descriptionText(f.description),
+	};
+}
+
+export function curateCommentsJson(comments) {
+	return comments.map((c) => ({
+		author: c.author?.displayName || null,
+		date: c.created,
+		body: typeof c.body === 'string' ? c.body : JSON.stringify(c.body || ''),
+	}));
+}
+
+export function curateSearchJson(result) {
+	return {
+		total: result.total,
+		issues: result.issues.map((issue) => ({
+			key: issue.key,
+			summary: issue.fields.summary,
+			status: issue.fields.status?.name || null,
+			assignee: issue.fields.assignee?.displayName || null,
+			priority: issue.fields.priority?.name || null,
+			updated: issue.fields.updated,
+		})),
+	};
+}
+
+// --- Plain formatters ---
+
+export function plainIssueView(issue) {
+	const f = issue.fields;
+	console.log(`${issue.key} ${f.summary}`);
+	console.log(`Status: ${f.status?.name || 'Unknown'}`);
+	console.log(`Priority: ${f.priority?.name || 'None'}`);
+	console.log(`Type: ${f.issuetype?.name || 'Unknown'}`);
+	console.log(`Assignee: ${f.assignee?.displayName || 'Unassigned'}`);
+	console.log(`Reporter: ${f.reporter?.displayName || 'Unknown'}`);
+	if (f.labels?.length > 0) console.log(`Labels: ${f.labels.join(', ')}`);
+	if (f.components?.length > 0) console.log(`Components: ${f.components.map((c) => c.name).join(', ')}`);
+	const sprint = extractSprint(f);
+	if (sprint) console.log(`Sprint: ${sprint}`);
+	const points = extractStoryPoints(f);
+	if (points) console.log(`Story Points: ${points}`);
+	console.log(`Created: ${f.created}`);
+	console.log(`Updated: ${f.updated}`);
+	const desc = descriptionText(f.description);
+	if (desc) console.log(`Description:\n${desc.trim()}`);
+}
+
+export function plainIssueComments(comments) {
+	if (comments.length === 0) { console.log('No comments.'); return; }
+	for (const c of comments) {
+		const body = typeof c.body === 'string' ? c.body : JSON.stringify(c.body || '');
+		console.log(`${c.author?.displayName || 'Unknown'} (${relativeTime(c.created)}): ${body.trim()}`);
+	}
+}
+
+export function plainIssueSearch(result) {
+	if (result.issues.length === 0) { console.log('No issues found.'); return; }
+	for (const issue of result.issues) {
+		const f = issue.fields;
+		console.log(`${issue.key} [${f.status?.name}] "${f.summary}" - ${f.assignee?.displayName || 'Unassigned'} (${f.priority?.name}, ${relativeTime(f.updated)})`);
+	}
+	const showing = result.startAt + result.issues.length;
+	if (result.total > showing) console.log(`Showing ${result.startAt + 1}-${showing} of ${result.total}`);
+}
+
+// --- Rich formatters (original) ---
+
+export function formatIssueView(issue) {
+	const f = issue.fields;
+
+	heading(`${issue.key} ${f.summary}`);
+	divider();
+	field('Status', statusColor(f.status?.name));
+	field('Priority', priorityColor(f.priority?.name));
+	field('Type', f.issuetype?.name);
+	field('Assignee', f.assignee?.displayName || pc.dim('Unassigned'));
+	field('Reporter', f.reporter?.displayName);
+	field('Labels', f.labels?.length > 0 ? f.labels.join(', ') : null);
+	field('Components', f.components?.map((c) => c.name).join(', ') || null);
+
+	const sprint = extractSprint(f);
+	if (sprint) field('Sprint', sprint);
+
+	const points = extractStoryPoints(f);
+	if (points) field('Story Points', points);
+
+	field('Created', new Date(f.created).toLocaleString());
+	field('Updated', new Date(f.updated).toLocaleString());
+
+	if (f.description) {
+		heading('Description');
+		const desc = descriptionText(f.description);
+		const lines = desc.trim().split('\n');
+		const truncated = lines.slice(0, 30);
+		for (const line of truncated) {
+			console.log(`  ${line}`);
+		}
+		if (lines.length > 30) {
+			console.log(pc.dim(`  ... (${lines.length - 30} more lines)`));
+		}
+	}
+
+	console.log('');
+}
+
+export function formatIssueComments(comments) {
+	if (comments.length === 0) {
+		console.log(pc.dim('  No comments.'));
+		return;
+	}
+
+	for (const c of comments) {
+		console.log(`\n  ${pc.bold(c.author?.displayName || 'Unknown')} ${pc.dim(relativeTime(c.created))}`);
+		if (c.body) {
+			const lines = (typeof c.body === 'string' ? c.body : JSON.stringify(c.body)).trim().split('\n');
+			for (const line of lines) {
+				console.log(`  ${line}`);
+			}
+		}
+	}
+	console.log('');
+}
+
+export function formatIssueSearch(result) {
+	const { issues, total, startAt, maxResults } = result;
+
+	if (issues.length === 0) {
+		console.log(pc.dim('  No issues found.'));
+		return;
+	}
+
+	const rows = issues.map((issue) => [
+		pc.bold(issue.key),
+		(issue.fields.summary || '').length > 55
+			? issue.fields.summary.slice(0, 52) + '...'
+			: issue.fields.summary || '',
+		statusColor(issue.fields.status?.name),
+		issue.fields.assignee?.displayName || pc.dim('Unassigned'),
+		priorityColor(issue.fields.priority?.name),
+		relativeTime(issue.fields.updated),
+	]);
+
+	console.log(table(['Key', 'Summary', 'Status', 'Assignee', 'Priority', 'Updated'], rows));
+
+	const showing = startAt + issues.length;
+	if (total > showing) {
+		console.log(pc.dim(`  Showing ${startAt + 1}-${showing} of ${total} results`));
+	}
+	console.log('');
+}

package/src/formatters/pr.js

@@ -0,0 +1,306 @@
+import { table, heading, field, divider, pc } from '../utils/output.js';
+
+function stateLabel(state, draft) {
+	if (draft) return pc.yellow('DRAFT');
+	switch (state) {
+		case 'OPEN': return pc.green(state);
+		case 'MERGED': return pc.blue(state);
+		case 'DECLINED': return pc.red(state);
+		case 'SUPERSEDED': return pc.dim(state);
+		default: return state;
+	}
+}
+
+function stateText(state, draft) {
+	return draft ? 'DRAFT' : state;
+}
+
+function approvalStatus(participant) {
+	if (participant.approved) return pc.green('APPROVED');
+	if (participant.state === 'changes_requested') return pc.red('CHANGES REQUESTED');
+	return pc.dim('PENDING');
+}
+
+function approvalStatusText(participant) {
+	if (participant.approved) return 'APPROVED';
+	if (participant.state === 'changes_requested') return 'CHANGES_REQUESTED';
+	return 'PENDING';
+}
+
+function approvalCount(pr) {
+	const approved = (pr.participants || []).filter((p) => p.approved).length;
+	const total = (pr.participants || []).filter((p) => p.role === 'REVIEWER').length;
+	if (total === 0) return pc.dim('0');
+	if (approved === total) return pc.green(`${approved}/${total}`);
+	return `${approved}/${total}`;
+}
+
+function approvalNumbers(pr) {
+	const approved = (pr.participants || []).filter((p) => p.approved).length;
+	const total = (pr.participants || []).filter((p) => p.role === 'REVIEWER').length;
+	return { approved, total };
+}
+
+function relativeTime(dateStr) {
+	const diff = Date.now() - new Date(dateStr).getTime();
+	const mins = Math.floor(diff / 60000);
+	if (mins < 60) return `${mins}m ago`;
+	const hours = Math.floor(mins / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	if (days < 30) return `${days}d ago`;
+	return new Date(dateStr).toLocaleDateString();
+}
+
+function reviewers(pr) {
+	return (pr.participants || []).filter((p) => p.role === 'REVIEWER');
+}
+
+// --- JSON curators ---
+
+export function curateListJson(prs) {
+	return prs.map((pr) => {
+		const { approved, total } = approvalNumbers(pr);
+		return {
+			id: pr.id,
+			title: pr.title,
+			author: pr.author.display_name,
+			state: pr.state,
+			draft: pr.draft || false,
+			approvals: { approved, total },
+			source: pr.source.branch.name,
+			destination: pr.destination.branch.name,
+			updated: pr.updated_on,
+		};
+	});
+}
+
+export function curateViewJson(pr) {
+	return {
+		id: pr.id,
+		title: pr.title,
+		state: pr.state,
+		draft: pr.draft || false,
+		author: pr.author.display_name,
+		source: pr.source.branch.name,
+		destination: pr.destination.branch.name,
+		created: pr.created_on,
+		updated: pr.updated_on,
+		description: pr.description || '',
+		reviewers: reviewers(pr).map((r) => ({
+			name: r.user.display_name,
+			status: approvalStatusText(r),
+		})),
+	};
+}
+
+export function curateCommentsJson(comments) {
+	return comments
+		.filter((c) => !c.deleted)
+		.sort((a, b) => new Date(a.created_on) - new Date(b.created_on))
+		.map((c) => ({
+			author: c.user.display_name,
+			date: c.created_on,
+			content: c.content?.raw || '',
+			inline: c.inline ? { path: c.inline.path, line: c.inline.from || c.inline.to } : null,
+		}));
+}
+
+export function curateDiffstatJson(files) {
+	return files.map((f) => ({
+		file: f.new?.path || f.old?.path || null,
+		status: f.status,
+		added: f.lines_added || 0,
+		removed: f.lines_removed || 0,
+	}));
+}
+
+export function curateActivityJson(activities) {
+	return activities.map((a) => {
+		if (a.approval) return { type: 'approval', user: a.approval.user.display_name, date: a.approval.date };
+		if (a.update) return { type: 'update', user: a.update.author?.display_name, date: a.update.date, state: a.update.state };
+		if (a.comment) return { type: 'comment', user: a.comment.user.display_name, date: a.comment.created_on, content: (a.comment.content?.raw || '').split('\n')[0] };
+		if (a.changes_requested) return { type: 'changes_requested', user: a.changes_requested.user.display_name, date: a.changes_requested.date };
+		return { type: 'unknown' };
+	});
+}
+
+// --- Plain formatters ---
+
+export function plainPrList(prs) {
+	if (prs.length === 0) { console.log('No pull requests found.'); return; }
+	for (const pr of prs) {
+		const { approved, total } = approvalNumbers(pr);
+		console.log(`#${pr.id} ${stateText(pr.state, pr.draft)} "${pr.title}" by ${pr.author.display_name} (${approved}/${total} approvals, ${relativeTime(pr.updated_on)})`);
+	}
+}
+
+export function plainPrView(pr) {
+	console.log(`#${pr.id} ${pr.title}`);
+	console.log(`State: ${stateText(pr.state, pr.draft)}`);
+	console.log(`Author: ${pr.author.display_name}`);
+	console.log(`Source: ${pr.source.branch.name} -> ${pr.destination.branch.name}`);
+	console.log(`Created: ${pr.created_on}`);
+	console.log(`Updated: ${pr.updated_on}`);
+	const revs = reviewers(pr);
+	if (revs.length > 0) {
+		console.log(`Reviewers: ${revs.map((r) => `${r.user.display_name} (${approvalStatusText(r)})`).join(', ')}`);
+	}
+	if (pr.description) {
+		console.log(`Description:\n${pr.description.trim()}`);
+	}
+}
+
+export function plainPrComments(comments) {
+	const sorted = comments.filter((c) => !c.deleted).sort((a, b) => new Date(a.created_on) - new Date(b.created_on));
+	if (sorted.length === 0) { console.log('No comments.'); return; }
+	for (const c of sorted) {
+		const inline = c.inline ? ` [${c.inline.path}:${c.inline.from || c.inline.to}]` : '';
+		console.log(`${c.user.display_name} (${relativeTime(c.created_on)})${inline}: ${(c.content?.raw || '').trim()}`);
+	}
+}
+
+export function plainPrDiffstat(files) {
+	if (files.length === 0) { console.log('No file changes.'); return; }
+	for (const f of files) {
+		console.log(`${f.status} ${f.new?.path || f.old?.path} +${f.lines_added || 0} -${f.lines_removed || 0}`);
+	}
+	const added = files.reduce((s, f) => s + (f.lines_added || 0), 0);
+	const removed = files.reduce((s, f) => s + (f.lines_removed || 0), 0);
+	console.log(`${files.length} files changed, +${added}, -${removed}`);
+}
+
+export function plainPrActivity(activities) {
+	if (activities.length === 0) { console.log('No activity.'); return; }
+	for (const a of activities) {
+		if (a.approval) console.log(`APPROVED by ${a.approval.user.display_name} (${relativeTime(a.approval.date)})`);
+		else if (a.update) console.log(`UPDATED by ${a.update.author?.display_name || 'Unknown'} (${relativeTime(a.update.date)})${a.update.state ? ` -> ${a.update.state}` : ''}`);
+		else if (a.comment) console.log(`COMMENT by ${a.comment.user.display_name} (${relativeTime(a.comment.created_on)}): ${(a.comment.content?.raw || '').split('\n')[0].slice(0, 80)}`);
+		else if (a.changes_requested) console.log(`CHANGES_REQUESTED by ${a.changes_requested.user.display_name} (${relativeTime(a.changes_requested.date)})`);
+	}
+}
+
+// --- Rich formatters (original) ---
+
+export function formatPrList(prs) {
+	if (prs.length === 0) {
+		console.log(pc.dim('  No pull requests found.'));
+		return;
+	}
+
+	const rows = prs.map((pr) => [
+		pc.bold(`#${pr.id}`),
+		pr.title.length > 60 ? pr.title.slice(0, 57) + '...' : pr.title,
+		pr.author.display_name,
+		stateLabel(pr.state, pr.draft),
+		approvalCount(pr),
+		relativeTime(pr.updated_on),
+	]);
+
+	console.log(table(['ID', 'Title', 'Author', 'State', 'Approvals', 'Updated'], rows));
+}
+
+export function formatPrView(pr) {
+	heading(`#${pr.id} ${pr.title}`);
+	divider();
+	field('State', stateLabel(pr.state, pr.draft));
+	field('Author', pr.author.display_name);
+	field('Source', `${pr.source.branch.name} (${pr.source.repository?.full_name || ''})`);
+	field('Destination', `${pr.destination.branch.name} (${pr.destination.repository?.full_name || ''})`);
+	field('Created', new Date(pr.created_on).toLocaleString());
+	field('Updated', new Date(pr.updated_on).toLocaleString());
+
+	if (pr.description) {
+		heading('Description');
+		console.log(pr.description.trim());
+	}
+
+	const revs = reviewers(pr);
+	if (revs.length > 0) {
+		heading('Reviewers');
+		for (const r of revs) {
+			console.log(`  ${r.user.display_name}: ${approvalStatus(r)}`);
+		}
+	}
+
+	console.log('');
+}
+
+export function formatPrComments(comments) {
+	if (comments.length === 0) {
+		console.log(pc.dim('  No comments.'));
+		return;
+	}
+
+	const sorted = comments
+		.filter((c) => !c.deleted)
+		.sort((a, b) => new Date(a.created_on) - new Date(b.created_on));
+
+	for (const c of sorted) {
+		const inline = c.inline ? pc.dim(` [${c.inline.path}:${c.inline.from || c.inline.to}]`) : '';
+		console.log(`\n  ${pc.bold(c.user.display_name)} ${pc.dim(relativeTime(c.created_on))}${inline}`);
+		if (c.content?.raw) {
+			const lines = c.content.raw.trim().split('\n');
+			for (const line of lines) {
+				console.log(`  ${line}`);
+			}
+		}
+	}
+	console.log('');
+}
+
+export function formatPrDiffstat(files) {
+	if (files.length === 0) {
+		console.log(pc.dim('  No file changes.'));
+		return;
+	}
+
+	const rows = files.map((f) => {
+		const added = f.lines_added || 0;
+		const removed = f.lines_removed || 0;
+		return [
+			f.new?.path || f.old?.path || '(unknown)',
+			f.status,
+			pc.green(`+${added}`),
+			pc.red(`-${removed}`),
+		];
+	});
+
+	console.log(table(['File', 'Status', 'Added', 'Removed'], rows));
+
+	const totalAdded = files.reduce((s, f) => s + (f.lines_added || 0), 0);
+	const totalRemoved = files.reduce((s, f) => s + (f.lines_removed || 0), 0);
+	console.log(`  ${files.length} files changed, ${pc.green(`+${totalAdded}`)}, ${pc.red(`-${totalRemoved}`)}`);
+	console.log('');
+}
+
+export function formatPrActivity(activities) {
+	if (activities.length === 0) {
+		console.log(pc.dim('  No activity.'));
+		return;
+	}
+
+	for (const a of activities) {
+		if (a.approval) {
+			const user = a.approval.user.display_name;
+			const date = relativeTime(a.approval.date);
+			console.log(`  ${pc.green('APPROVED')} by ${pc.bold(user)} ${pc.dim(date)}`);
+		} else if (a.update) {
+			const user = a.update.author?.display_name || 'Unknown';
+			const date = relativeTime(a.update.date);
+			const state = a.update.state ? ` → ${stateLabel(a.update.state, false)}` : '';
+			console.log(`  ${pc.blue('UPDATED')} by ${pc.bold(user)} ${pc.dim(date)}${state}`);
+		} else if (a.comment) {
+			const user = a.comment.user.display_name;
+			const date = relativeTime(a.comment.created_on);
+			const snippet = (a.comment.content?.raw || '').split('\n')[0].slice(0, 80);
+			console.log(`  ${pc.yellow('COMMENT')} by ${pc.bold(user)} ${pc.dim(date)}`);
+			if (snippet) console.log(`    ${snippet}`);
+		} else if (a.changes_requested) {
+			const user = a.changes_requested.user.display_name;
+			const date = relativeTime(a.changes_requested.date);
+			console.log(`  ${pc.red('CHANGES REQUESTED')} by ${pc.bold(user)} ${pc.dim(date)}`);
+		}
+	}
+	console.log('');
+}

package/src/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { isConfigured, runSetup } from './config/store.js';
+import configCmd from './commands/config.js';
+import prCmd from './commands/pr.js';
+import jiraCmd from './commands/jira.js';
+import confluenceCmd from './commands/confluence.js';
+
+const program = new Command();
+
+program
+	.name('dev')
+	.description('CLI for Bitbucket PRs, Jira tickets, and Confluence pages')
+	.version('0.2.0')
+	.option('--json', 'Output raw JSON')
+	.option('--plain', 'Output compact plain text (no tables, no colors)');
+
+program.addCommand(configCmd);
+program.addCommand(prCmd);
+program.addCommand(jiraCmd);
+program.addCommand(confluenceCmd);
+
+program.hook('preAction', async (thisCommand, actionCommand) => {
+	const cmdChain = [];
+	let cmd = actionCommand;
+	while (cmd) {
+		cmdChain.unshift(cmd.name());
+		cmd = cmd.parent;
+	}
+	if (cmdChain.includes('config')) return;
+
+	if (!isConfigured()) {
+		console.log('First run detected. Let\'s set up your configuration.\n');
+		await runSetup();
+		console.log('');
+	}
+});
+
+program.parse();

package/src/utils/errors.js

@@ -0,0 +1,43 @@
+import { error } from './output.js';
+
+export function handleError(err, context = '') {
+	if (err.status === 401 || err.statusCode === 401) {
+		const service = context.includes('bitbucket') ? 'Bitbucket' : context.includes('jira') ? 'Jira' : context.includes('confluence') ? 'Confluence' : '';
+		error(`Authentication failed${service ? ` for ${service}` : ''}. Check your API token.`);
+		if (context) error(`Endpoint: ${context}`);
+		process.exitCode = 1;
+		return;
+	}
+
+	if (err.status === 403 || err.statusCode === 403) {
+		error('Access denied. Your token may lack the required scopes.');
+		if (context) error(`Endpoint: ${context}`);
+		process.exitCode = 1;
+		return;
+	}
+
+	if (err.status === 404 || err.statusCode === 404) {
+		error('Not found. Check that the resource exists and you have access.');
+		if (context) error(`Endpoint: ${context}`);
+		process.exitCode = 1;
+		return;
+	}
+
+	if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND') {
+		error(`Could not connect to server.`);
+		if (context) error(`URL: ${context}`);
+		error('Check that the URL is correct and the server is reachable.');
+		process.exitCode = 1;
+		return;
+	}
+
+	if (err.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' || err.code === 'SELF_SIGNED_CERT_IN_CHAIN') {
+		error('SSL certificate error. If using a self-signed cert, set NODE_TLS_REJECT_UNAUTHORIZED=0');
+		process.exitCode = 1;
+		return;
+	}
+
+	error(err.message || String(err));
+	if (context) error(`Context: ${context}`);
+	process.exitCode = 1;
+}

package/src/utils/mode.js

@@ -0,0 +1,10 @@
+export function getOutputMode(cmd) {
+	const globals = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
+	if (globals.json) return 'json';
+	if (globals.plain) return 'plain';
+	return 'rich';
+}
+
+export function outputJson(data) {
+	console.log(JSON.stringify(data, null, 2));
+}

package/src/utils/output.js

@@ -0,0 +1,68 @@
+import pc from 'picocolors';
+import Table from 'cli-table3';
+
+const HIDE_CURSOR = '\x1B[?25l';
+const SHOW_CURSOR = '\x1B[?25h';
+const CLEAR_LINE = '\x1B[2K\r';
+
+export function spinner(text) {
+	return {
+		start() {
+			process.stdout.write(`${HIDE_CURSOR}${pc.dim('–')} ${text}`);
+			return this;
+		},
+		success({ text: msg } = {}) {
+			process.stdout.write(`${CLEAR_LINE}${pc.green('✓')} ${msg || text}${SHOW_CURSOR}\n`);
+			return this;
+		},
+		error({ text: msg } = {}) {
+			process.stdout.write(`${CLEAR_LINE}${pc.red('✗')} ${msg || text}${SHOW_CURSOR}\n`);
+			return this;
+		},
+	};
+}
+
+export function table(head, rows, options = {}) {
+	const t = new Table({
+		head: head.map((h) => pc.bold(pc.cyan(h))),
+		style: { head: [], border: [] },
+		wordWrap: true,
+		...options,
+	});
+	for (const row of rows) {
+		t.push(row);
+	}
+	return t.toString();
+}
+
+export function heading(text) {
+	console.log(`\n${pc.bold(pc.cyan(text))}`);
+}
+
+export function field(label, value) {
+	if (value === undefined || value === null || value === '') return;
+	console.log(`  ${pc.dim(label + ':')} ${value}`);
+}
+
+export function divider() {
+	console.log(pc.dim('─'.repeat(60)));
+}
+
+export function success(text) {
+	console.log(pc.green(`✓ ${text}`));
+}
+
+export function warn(text) {
+	console.log(pc.yellow(`⚠ ${text}`));
+}
+
+export function error(text) {
+	console.log(pc.red(`✗ ${text}`));
+}
+
+export function mask(str) {
+	if (!str || str.length < 8) return '****';
+	return str.slice(0, 4) + '•'.repeat(Math.min(str.length - 4, 16));
+}
+
+export { pc };