azdevops-cli/README.md

Azure DevOps CLI tool for sprint management and work item tracking

# 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

```bash
# 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:

```bash
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:

```env
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:**

   ```bash
   npm install -g azdevopscli-nodejs
   ```

2. **Run the setup command:**

   ```bash
   azdevops setup
   ```

3. **Use the CLI:**
   ```bash
   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**

```bash
# ✅ 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

```bash
# 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:

```typescript
// 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:

```bash
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.