CLI Package (@schwab/cli)

Overview

The @schwab/cli package provides a comprehensive command-line interface for automating Charles Schwab development workflows. It integrates with Git, GitHub, Jira, and various development tools to streamline common development tasks including branch management, pull request operations, and ticket tracking.

Architecture

Package Configuration

Dependencies

Core Dependencies

{
  "@inquirer/prompts": "^7.1.0",        // Interactive prompts
  "@octokit/rest": "^21.0.2",           // GitHub API client
  "@schwab/utilities": "workspace:*",    // Shared utilities
  "chalk": "^5.3.0",                    // Terminal colors
  "inquirer": "^12.1.0",                // CLI interactions
  "simple-git": "^3.27.0",              // Git operations
  "terminal-kit": "^3.1.2"              // Terminal UI
}

Core Commands

1. Pull Request Management

PR Command (pr.mjs)

import { select } from '@inquirer/prompts';
import chalk from 'chalk';
import { githubListPullRequests } from './utilities/githubListPullRequests.mjs';
import { selectTicketNumber } from './utilities/selectTicketNumber.mjs';

// Select Jira ticket and find matching PRs
const jiraTicket = await selectTicketNumber();
const ghPRs = await githubListPullRequests();

const matchingPrs = ghPRs.data.filter((pr) => {
  return pr.head.ref.includes(jiraTicket);
});

if (matchingPrs.length === 0) {
  console.log(chalk.red(`No PRs available for Jira Ticket: ${jiraTicket}`));
  process.exit(1);
}

2. Branch Operations

Available Commands:

• checkout - Interactive branch checkout with ticket filtering
• reset - Reset branch to specific state
• branches-cleanup.sh - Clean up local branches
• kill.sh - Force terminate processes

3. Commit Management

Features:

• Interactive commit creation
• Commit message standardization
• Pre-commit validation
• Automated push operations

4. Ticket Management

Capabilities:

• Jira ticket selection with search
• Worklog management and time tracking
• Ticket status updates
• Assignment management

Command Structure

Main Entry Point

CLI Entry Point (schwab-cli.sh)

#!/bin/sh

RED='\033[0;91m'
GREEN='\033[0;32m' 
YELLOW='\033[0;33m'
RESET='\033[0m'

cli_dir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )

if [ "$1" != "" ]; then
    if [ -f "$cli_dir/$1.mjs" ]; then
        commandPath="node $cli_dir/$1.mjs"
        
        for var in "$@"; do
            if [ "$1" != "$var" ]; then
                commandPath="$commandPath $var"
            fi
        done
        
        $commandPath
    else
         echo -e "${RED}Error:${RESET} ${YELLOW}$1${RESET} is not valid command."
    fi
fi

Available Commands

Command	File	Description
pr	pr.mjs	Pull request management and operations
checkout	checkout.mjs	Interactive branch checkout
commit	commit.mjs	Commit creation with standardization
ticket	ticket.mjs	Jira ticket operations
worklog	worklog.mjs	Time tracking and worklog management
ready	ready.mjs	Mark tickets/PRs as ready for review
contrib	contrib.mjs	Contribution and collaboration tools
test	test.mjs	Testing utilities and runners
context	context.mjs	Development context management
reset	reset.mjs	Reset operations for branches/state
release-report	release-report.mjs	Generate release reports
pullflags	pullflags.mjs	Feature flag synchronization
assignments	assignments.mjs	Task and assignment management

Utility Functions

GitHub Integration

Location: src/utilities/githubListPullRequests.mjs

• GitHub API authentication
• Pull request listing and filtering
• Repository operations
• Issue management

Jira Integration

Location: src/utilities/selectTicketNumber.mjs

• Jira API authentication
• Ticket search and selection
• Status management
• Worklog operations

Terminal Operations

Features:

• Interactive prompts with validation
• Colored output for status indication
• Table displays for data presentation
• Progress indicators for long operations

Development Workflow Integration

1. Branch Management Workflow

Typical Branch Workflow

# 1. Select and checkout ticket branch
schwab-cli checkout

# 2. Make changes and commit
schwab-cli commit

# 3. Create/manage pull request
schwab-cli pr

# 4. Mark as ready for review
schwab-cli ready

2. Ticket Management Workflow

Ticket Management

# 1. Select active ticket
schwab-cli ticket

# 2. Log work time
schwab-cli worklog

# 3. Update assignments
schwab-cli assignments

Configuration

Environment Variables

Required Environment Variables

# GitHub Configuration
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_OWNER=charlesschwab
GITHUB_REPO=nextjs-web

# Jira Configuration
JIRA_HOST=schwab.atlassian.net
JIRA_USERNAME=developer@schwab.com
JIRA_API_TOKEN=xxxxxxxxxxxxxxxxxxxx

# CLI Configuration
CLI_DEFAULT_BRANCH=main
CLI_AUTO_PUSH=true

CLI Configuration File

Location: .schwab-cli.config.json

CLI Configuration

{
  "github": {
    "defaultBranch": "main",
    "autoPush": true,
    "requirePR": true
  },
  "jira": {
    "projectKeys": ["CMS", "PLAT", "SEC"],
    "defaultTransitions": ["In Progress", "Done"],
    "worklogRequired": true
  },
  "git": {
    "commitMessageTemplate": "{ticketKey}: {description}",
    "branchNameTemplate": "feature/{ticketKey}-{description}",
    "autoCleanup": true
  }
}

Interactive Features

1. Command Selection

• Dynamic command discovery
• Help system with command descriptions
• Tab completion support
• Command history

2. Data Selection

• Searchable ticket lists
• Branch filtering and selection
• PR status filtering
• Multi-selection support

3. Progress Indicators

• Long-running operation feedback
• Upload/download progress bars
• API call status indication
• Error handling with retry options

Testing and Validation

Test Commands

CLI Testing

# Run CLI tests
schwab-cli test

# Validate configuration
schwab-cli --validate

# Debug mode
schwab-cli --debug pr

Error Handling

• Graceful exit on user cancellation
• API error handling and retry logic
• Network connectivity validation
• Permission checking

Security Features

1. Token Management

• Secure token storage
• Token validation and refresh
• Scoped permissions verification
• Automatic token rotation support

2. Access Control

• Role-based command access
• Repository permission validation
• Jira project access verification
• Audit logging for sensitive operations

Performance Optimization

1. Caching

• API response caching
• Command result memoization
• Configuration caching
• Offline mode support

2. Batch Operations

• Bulk PR operations
• Mass ticket updates
• Batch branch operations
• Parallel API calls

Troubleshooting

Common Issues

Issue	Cause	Solution
Command not found	Missing executable permissions	chmod +x schwab-cli.sh
GitHub API errors	Invalid token or permissions	Verify GITHUB_TOKEN
Jira connection issues	Network or authentication	Check Jira credentials
Git operation failures	Repository state conflicts	Run git status and resolve

Debug Mode

Debug Commands

# Enable verbose logging
export CLI_DEBUG=true

# Show API requests
export CLI_VERBOSE_API=true

# Dry run mode
schwab-cli --dry-run commit

Future Enhancements

Planned Features

1. AI Integration: Automated commit message generation
2. Advanced Workflows: Custom workflow definition and execution
3. Team Collaboration: Shared team configurations and templates
4. Analytics: Development metrics and reporting
5. Mobile Support: CLI companion mobile app

Integration Roadmap

• CI/CD Integration: Pipeline trigger and monitoring
• Slack Integration: Team notifications and updates
• IDE Plugins: VS Code and IntelliJ extensions
• Dashboard: Web-based CLI operation dashboard

Dependencies and Compatibility

Node.js Requirements

• Minimum Version: Node.js 18.0.0
• Recommended: Node.js 20.x LTS
• Platform Support: Linux, macOS, Windows (WSL)

External Dependencies

• Git: Version 2.30+
• GitHub CLI: Optional but recommended
• Jira CLI: Optional for advanced operations
• Terminal: Modern terminal with color support

---

The CLI package serves as a central automation hub for Charles Schwab development workflows, significantly improving developer productivity through streamlined Git, GitHub, and Jira operations. Its modular design allows for easy extension and customization to meet evolving team needs.