@falldownthesystem/devtool 0.1.0 → 0.2.0

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`devtool` — a Node.js CLI (`dev`) for interacting with Bitbucket pull requests and Jira tickets from the terminal. Uses ES modules, commander for CLI parsing, and the `conf` package for persistent config storage.
+
+## Commands
+
+```bash
+# Run the CLI
+node src/index.js <command>
+
+# Install globally for `dev` command
+npm link
+```
+
+No build step, no tests, no linter configured yet.
+
+## Architecture
+
+```
+src/
+  index.js          # Entry point — commander program, registers subcommands, auto-setup hook
+  config/store.js   # Conf-based config (persisted to OS config dir via `conf` package)
+  clients/          # API clients (bitbucket.js uses fetch + Basic auth, jira.js uses jira.js SDK + Bearer token)
+  commands/         # Commander subcommands (config, pr, jira)
+  formatters/       # Output formatting — each has three variants: rich (colored tables), plain (compact text), JSON (curated objects)
+  utils/
+    output.js       # Shared UI primitives: spinner, table (cli-table3), heading, field, divider, mask
+    errors.js       # handleError — maps HTTP status codes and connection errors to user-friendly messages
+    mode.js         # getOutputMode — reads --json/--plain global flags, returns 'json'|'plain'|'rich'
+```
+
+### Output Mode Pattern
+
+Every command supports three output modes via global flags `--json` and `--plain`:
+- **rich** (default): colored output with tables (cli-table3) and spinners
+- **plain**: no colors, no tables, compact text — suitable for piping
+- **json**: curated JSON (not raw API responses) via `curate*Json` functions in formatters
+
+Commands follow this pattern: check mode → conditionally show spinner → fetch data → format via mode-specific function. The `withMode` helper in `commands/pr.js` abstracts this for simple cases.
+
+### Config
+
+Stored via `conf` package (projectName: `devtool`). Interactive setup runs automatically on first use (preAction hook in index.js). Config keys:
+- `bitbucket.{workspace, defaultRepo, email, token}`
+- `jira.{baseUrl, token, defaultProject}`
+
+### API Clients
+
+- **Bitbucket** (`clients/bitbucket.js`): Raw fetch against `api.bitbucket.org/2.0`, Basic auth, manual pagination via `next` links
+- **Jira** (`clients/jira.js`): Uses `jira.js` SDK (Version2Client) with Bearer token auth (overrides SDK's built-in Basic auth via request interceptor)

package/README.md

@@ -5,7 +5,8 @@ A terminal-first CLI for working with Bitbucket PRs, Jira tickets, and Confluenc
 ## Install
 
 ```bash
-npm install -g @falldownthesystem/devtool
+npm install
+npm link
 ```
 
 This gives you the `dev` command globally. On first run, it'll walk you through connecting your Bitbucket, Jira, and Confluence accounts.
@@ -22,6 +23,7 @@ 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 children PROJ-123   # epic children or subtasks (auto-detect)
 dev jira mine                # your open tickets
 
 dev confluence spaces        # list spaces

package/package.json

@@ -1,34 +1,17 @@
 {
 	"name": "@falldownthesystem/devtool",
-	"version": "0.1.0",
+	"version": "0.2.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",
+	"keywords": [],
+	"author": "",
 	"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/jira.js

@@ -59,3 +59,40 @@ export async function getMyIssues() {
 		: `assignee = currentUser() AND status != Done ORDER BY updated DESC`;
 	return searchIssues(jql);
 }
+
+export async function getIssueChildren(issueKey) {
+	const issue = await getIssue(issueKey);
+	const type = issue.fields.issuetype?.name;
+	const parent = { key: issue.key, type, summary: issue.fields.summary };
+
+	if (type === 'Epic') {
+		const response = await getClient().instance.get(
+			`/rest/agile/1.0/epic/${encodeURIComponent(issueKey)}/issue`,
+			{
+				params: {
+					fields: 'summary,status,assignee,priority,updated,issuetype',
+					maxResults: 100,
+				},
+			}
+		);
+		const data = response.data;
+		return {
+			issues: data.issues || [],
+			total: data.total ?? (data.issues || []).length,
+			startAt: data.startAt || 0,
+			maxResults: data.maxResults || 100,
+			parent,
+			source: 'epic',
+		};
+	}
+
+	const subtasks = issue.fields.subtasks || [];
+	return {
+		issues: subtasks,
+		total: subtasks.length,
+		startAt: 0,
+		maxResults: subtasks.length,
+		parent,
+		source: 'subtasks',
+	};
+}

package/src/commands/jira.js

@@ -4,11 +4,13 @@ import {
 	getIssueComments,
 	searchIssues,
 	getMyIssues,
+	getIssueChildren,
 } from '../clients/jira.js';
 import {
 	formatIssueView, formatIssueComments, formatIssueSearch,
 	plainIssueView, plainIssueComments, plainIssueSearch,
 	curateIssueJson, curateCommentsJson, curateSearchJson,
+	formatIssueChildren, plainIssueChildren, curateChildrenJson,
 } from '../formatters/jira.js';
 import { spinner } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
@@ -74,6 +76,24 @@ jira.command('search <jql>')
 		}
 	});
 
+jira.command('children <key>')
+	.alias('subs')
+	.description('List epic children or issue subtasks')
+	.action(async function (key) {
+		const mode = getOutputMode(this);
+		const s = mode === 'rich' ? spinner(`Fetching children of ${key}...`).start() : null;
+		try {
+			const result = await getIssueChildren(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);
+			else formatIssueChildren(result);
+		} catch (err) {
+			if (s) s.error({ text: `Failed to fetch children of ${key}` });
+			handleError(err, `jira children ${key}`);
+		}
+	});
+
 jira.command('mine')
 	.alias('my')
 	.description('Show my open issues')

package/src/formatters/jira.js

@@ -109,6 +109,23 @@ export function curateSearchJson(result) {
 	};
 }
 
+export function curateChildrenJson(result) {
+	return {
+		parent: result.parent,
+		source: result.source,
+		total: result.total,
+		issues: result.issues.map((issue) => ({
+			key: issue.key,
+			summary: issue.fields?.summary || null,
+			status: issue.fields?.status?.name || null,
+			type: issue.fields?.issuetype?.name || null,
+			assignee: issue.fields?.assignee?.displayName || null,
+			priority: issue.fields?.priority?.name || null,
+			updated: issue.fields?.updated || null,
+		})),
+	};
+}
+
 // --- Plain formatters ---
 
 export function plainIssueView(issue) {
@@ -149,6 +166,27 @@ export function plainIssueSearch(result) {
 	if (result.total > showing) console.log(`Showing ${result.startAt + 1}-${showing} of ${result.total}`);
 }
 
+export function plainIssueChildren(result) {
+	const label = result.source === 'epic' ? 'epic children' : 'subtasks';
+	console.log(`${result.parent.key} (${result.parent.type}) "${result.parent.summary}" - ${result.total} ${label}`);
+	if (result.issues.length === 0) { console.log('None.'); return; }
+	for (const issue of result.issues) {
+		const f = issue.fields || {};
+		const parts = [
+			`${issue.key}`,
+			f.status?.name ? `[${f.status.name}]` : null,
+			f.issuetype?.name ? `(${f.issuetype.name})` : null,
+			f.summary ? `"${f.summary}"` : null,
+		].filter(Boolean);
+		const meta = [
+			f.assignee?.displayName || null,
+			f.priority?.name || null,
+			f.updated ? relativeTime(f.updated) : null,
+		].filter(Boolean).join(', ');
+		console.log(`${parts.join(' ')}${meta ? ` - ${meta}` : ''}`);
+	}
+}
+
 // --- Rich formatters (original) ---
 
 export function formatIssueView(issue) {
@@ -234,3 +272,36 @@ export function formatIssueSearch(result) {
 	}
 	console.log('');
 }
+
+export function formatIssueChildren(result) {
+	const { issues, parent, source } = result;
+	const label = source === 'epic' ? 'children' : 'subtasks';
+
+	heading(`${parent.key} ${parent.summary}`);
+	console.log(pc.dim(`  ${parent.type} · ${result.total} ${label}`));
+	divider();
+
+	if (issues.length === 0) {
+		console.log(pc.dim('  None.'));
+		console.log('');
+		return;
+	}
+
+	const rows = issues.map((issue) => {
+		const f = issue.fields || {};
+		return [
+			pc.bold(issue.key),
+			(f.summary || '').length > 50
+				? f.summary.slice(0, 47) + '...'
+				: f.summary || '',
+			f.issuetype?.name || pc.dim('—'),
+			statusColor(f.status?.name),
+			f.assignee?.displayName || pc.dim('Unassigned'),
+			priorityColor(f.priority?.name),
+			f.updated ? relativeTime(f.updated) : pc.dim('—'),
+		];
+	});
+
+	console.log(table(['Key', 'Summary', 'Type', 'Status', 'Assignee', 'Priority', 'Updated'], rows));
+	console.log('');
+}

package/LICENSE

@@ -1,15 +0,0 @@
-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.