Azure DevOps CLI Tool

A Node.js CLI tool for interacting with Azure DevOps services. Provides commands to manage sprints, work items, and team workflows through a simple command-line interface.

Developer Documentation

🚀 Quick Start for Developers

This document provides a clear workflow for developers working on the Azure DevOps CLI tool.

Prerequisites

• Node.js 18+
• npm
• Azure DevOps Personal Access Token (PAT)

Development Workflow

1. Initial Setup

# Clone the repository
git clone <repository-url>
cd azdevopscli-nodejs

# Install dependencies
npm install

2. Configuration

Option 1: Interactive Setup (Recommended)

Run the setup command to configure your credentials interactively:

npm run start setup

This will prompt you for:

• Azure DevOps Organization
• Azure DevOps Project
• Azure DevOps Team
• Personal Access Token (PAT)

The configuration will be saved to ~/.azdevops/config.json.

Option 2: Environment Variables

Alternatively, you can use environment variables by editing the .env file:

AZURE_ORGANIZATION=your-organization-name
AZURE_PROJECT=PROJECT
AZURE_TEAM=TEAM
AZURE_PAT=your-personal-access-token

To generate a Personal Access Token (PAT):

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Click "New Token"
3. Set appropriate scopes (Work Items: Read, Code: Read)
4. Copy the generated token to your configuration

3. Credential Management

For Development (Local)

• Use the interactive setup: npm run start setup
• Or use environment variables in .env file

For Production (npm install)

When users install your CLI from npm, they should:

1. Install the CLI globally:

   npm install -g azdevopscli-nodejs

2. Run the setup command:

   azdevops setup

3. Use the CLI:

   azdevops follow-sprint

The configuration is automatically saved to ~/.azdevops/config.json and persists across sessions.

4. Running the Application

⚠️ IMPORTANT: Always use npm run start to run the application

# ✅ CORRECT - Use this command to run the application
npm run start follow-sprint

# ✅ CORRECT - With sprint parameter
npm run start -- follow-sprint -s "Sprint 47"

❌ DO NOT use these commands:

• node dist/index.js (bypasses build process)
• node src/index.ts (TypeScript files need compilation)
• ts-node src/index.ts (not configured for this project)

4. Development Workflow

Making Changes

1. Edit TypeScript files in the src/ directory
2. Run the application with npm run start (this automatically builds and runs)
3. Test your changes by executing commands
4. Repeat until satisfied

Build Process

The npm run start command automatically:

1. Cleans the dist/ directory
2. Compiles TypeScript to JavaScript using esbuild
3. Runs the compiled application

# Manual build commands (if needed)
npm run build        # Production build
npm run build:dev    # Development build with sourcemaps
npm run clean        # Clean dist directory

5. Project Structure

src/
├── commands/          # CLI command implementations
│   └── follow-sprint/
│       ├── follow-sprint-command.ts  # Command logic
│       └── follow-sprint-ui.ts       # UI and display logic
├── services/          # Business logic and API services
│   ├── auth.ts        # Authentication and configuration
│   ├── azure-client.ts # HTTP client wrapper
│   ├── azure-devops.ts # Azure DevOps API service
│   └── types.ts       # TypeScript type definitions
└── index.ts           # Main entry point

6. Adding New Commands

1. Create a new directory in src/commands/
2. Create command files following the existing pattern
3. Register the command in src/index.ts
4. Test with npm run start your-new-command

Example command structure:

// src/commands/your-command/your-command-command.ts
export class YourCommand {
  private program: Command;

  constructor() {
    this.program = new Command();
    this.setupCommand();
  }

  private setupCommand(): void {
    this.program
      .name("your-command")
      .description("Description of your command")
      .action(async (options) => {
        await this.run(options);
      });
  }

  async run(options: any): Promise<void> {
    // Your command implementation
  }

  getCommand(): Command {
    return this.program;
  }
}

7. Available Scripts

| Script | Description | When to Use | | ------------------- | --------------------------------- | ---------------------------------- | | npm run start | Build and run the application | Always use this to run the app | | npm run build | Compile TypeScript to JavaScript | Manual builds | | npm run build:dev | Development build with sourcemaps | Debugging | | npm run clean | Remove dist directory | Clean builds | | npm test | Run tests | Testing (not implemented yet) |

8. Code Quality Standards

Error Handling

• Create custom error types that implement the Error interface
• Include error codes and user-friendly messages
• Never expose internal system errors to end users
• Log errors with sufficient context for debugging

Security

• Never log sensitive information (passwords, tokens, personal data)
• Validate all user inputs and sanitize data
• Store secrets in environment variables, never in code

9. Troubleshooting

Common Issues

1. "Command not found" errors

   • Ensure you're using npm run start not node directly
   • Check that dependencies are installed with npm install

2. TypeScript compilation errors

   • Run npm run build to see detailed error messages
   • Check TypeScript configuration in tsconfig.json

3. Authentication errors

   • Check that your PAT has appropriate permissions

4. Build errors

   • Run npm run clean then npm run build
   • Check for syntax errors in TypeScript files

Debug Mode

To enable debug logging:

DEBUG=azdevopscli npm run start follow-sprint

10. Git Workflow

Commit Standards

• Write meaningful commit messages following conventional commits
• Use feature branches and pull requests
• Never commit secrets or sensitive data

Before Committing

1. Ensure all changes work with npm run start
2. Test your changes thoroughly
3. Update documentation if needed
4. Check for any sensitive data in your changes

Summary

Key Points for Developers:

1. Always use npm run start to run the application
2. Never run TypeScript files directly - they must be compiled first
3. Follow the established project structure when adding new features
4. Test thoroughly before committing changes
5. Keep the build process simple - let npm run start handle everything

Remember: The npm run start command is designed to handle the entire workflow from build to execution. Use it consistently to ensure a reliable development experience.