Contributing to SystemAdmin-CLI v2

We're excited that you're interested in contributing to SystemAdmin-CLI v2! This guide will help you get started with contributing to our advanced system administration toolkit.

🎯 Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

🚀 Getting Started

Prerequisites

Node.js: Version 18.0.0 or higher
npm: Version 8.0.0 or higher
TypeScript: Version 5.0.0 or higher
Git: Latest version

Development Setup

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/systemadmin-cli-v2.git
cd systemadmin-cli-v2

Install dependencies:
```
npm install
npm run install:all
```
Build the project:
```
npm run build
```
Run tests to ensure everything works:
```
npm test
```

Create a feature branch:

git checkout -b feature/your-feature-name

📁 Project Structure

systemadmin-cli-v2/
├── packages/
│   ├── core/                 # Core system administration logic
│   │   ├── src/
│   │   │   ├── system/       # System detection and info
│   │   │   ├── safety/       # Safety validation framework
│   │   │   ├── mcp/          # MCP server implementation
│   │   │   └── tools/        # Core administration tools
│   │   └── package.json
│   ├── cli/                  # Command-line interface
│   │   ├── src/
│   │   │   ├── commands/     # CLI command implementations
│   │   │   └── utils/        # CLI utilities
│   │   └── package.json
│   └── ui/                   # Optional UI components
├── docs/                     # Documentation
├── tests/                    # Test files
├── .github/                  # GitHub workflows and templates
└── package.json

🛡️ Safety-First Development

SystemAdmin-CLI v2 prioritizes safety above all else. When contributing:

1. Safety Validation

All system-modifying operations MUST include safety validation
Never bypass safety checks for convenience
Always implement dry-run mode for destructive operations
Include rollback mechanisms where possible

2. Required Safety Patterns

// REQUIRED: Safety validation for all tools
async validateAndExecute(params: ToolParams): Promise<ToolResult> {
  // 1. Validate parameters
  const validatedParams = await this.validateParams(params);
  
  // 2. Assess risks
  const riskAssessment = await this.assessRisks(validatedParams);
  
  // 3. Require confirmation for high-risk operations
  if (riskAssessment.level >= SafetyLevel.HIGH) {
    const confirmed = await this.requireConfirmation(riskAssessment);
    if (!confirmed) {
      return { success: false, cancelled: true };
    }
  }
  
  // 4. Execute with safeguards
  return await this.executeWithSafeguards(validatedParams);
}

3. Testing Safety

Every safety mechanism MUST be tested
Include tests for confirmation dialogs
Test dry-run mode functionality
Verify rollback capabilities

🧪 Testing Guidelines

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:safety

# Run tests for a specific package
npm run test -w packages/core

Test Categories

Unit Tests: Test individual functions and classes
Integration Tests: Test component interactions
Safety Tests: Validate safety mechanisms
System Tests: End-to-end functionality
Performance Tests: Resource usage and response times

Writing Tests

// Example test structure
describe('InstallPackageTool', () => {
  beforeEach(() => {
    // Setup test environment
  });

  it('should validate package names', async () => {
    // Test input validation
  });

  it('should require confirmation for system packages', async () => {
    // Test safety mechanisms
  });

  it('should support dry-run mode', async () => {
    // Test dry-run functionality
  });
});

📝 Code Style Guidelines

TypeScript Standards

Use strict mode TypeScript
Provide comprehensive type definitions
Use proper async/await patterns
Implement error boundaries

Code Formatting

Use Prettier for code formatting
Use ESLint for linting
Follow existing code style patterns
Use meaningful variable and function names

Documentation

Document all public APIs with JSDoc
Include examples in documentation
Explain safety considerations
Document command-line options

🔧 Adding New Commands

1. Core Tool Implementation

Create a new tool in packages/core/src/tools/:

// packages/core/src/tools/new-tool.ts
import { BaseTool } from './base-tool.js';
import { ToolResult } from '../types.js';

export class NewTool extends BaseTool<NewToolParams, ToolResult> {
  constructor() {
    super(
      'new_tool',
      'New Tool',
      'Description of what this tool does',
      newToolSchema,
      true,  // isOutputMarkdown
      false  // canUpdateOutput
    );
  }

  async execute(params: NewToolParams): Promise<ToolResult> {
    // Implement tool logic with safety validation
  }
}

2. CLI Command Implementation

Create a new command in packages/cli/src/commands/:

// packages/cli/src/commands/new-command.ts
import { Command } from 'commander';
import { BaseCommand } from './base-command.js';

export class NewCommand extends BaseCommand {
  getCommand(): Command {
    return new Command('new')
      .description('Description of the new command')
      .option('--dry-run', 'show what would be done without executing')
      .action(async (options) => {
        await this.executeWithSafety(options, async () => {
          // Implement command logic
        });
      });
  }
}

3. Registration

Add your new command to packages/cli/src/cli.ts:

import { NewCommand } from './commands/new-command.js';

// Add to the program
program.addCommand(new NewCommand().getCommand());

🏗️ Architecture Guidelines

MCP Server Development

Use the Model Context Protocol for tool integration
Implement proper error handling
Provide comprehensive tool schemas
Use stdio transport for local tools

Cross-Platform Support

Test on multiple operating systems
Use appropriate package managers
Handle platform-specific service management
Provide fallback mechanisms

Performance Considerations

System detection: < 500ms
Command validation: < 100ms
Common operations: < 2 seconds
Maintain responsive UX

📋 Pull Request Process

1. Before Submitting

Code follows the style guidelines
Tests are written and passing
Documentation is updated
Safety mechanisms are implemented
Cross-platform compatibility is verified

2. Pull Request Requirements

Title: Clear, descriptive title
Description: Explain what changes were made and why
Safety Impact: Describe any safety-related changes
Testing: Describe testing performed
Screenshots: If applicable, include screenshots of CLI output

3. Review Process

Automated Checks: CI/CD pipeline runs tests
Code Review: Maintainers review code quality
Safety Review: Safety mechanisms are validated
Testing: Manual testing on multiple platforms
Documentation: Verify documentation updates

🚨 Reporting Issues

Security Issues

DO NOT create public issues for security vulnerabilities
Email security@systemadmin-cli.org with details
Include steps to reproduce and potential impact

Bug Reports

Include:

Environment: OS, Node.js version, SystemAdmin-CLI version
Command: Exact command that failed
Expected vs Actual: What you expected vs what happened
Logs: Relevant log output (with sensitive info redacted)

Feature Requests