devcontainers · chrmarti · Sep 22, 2025
@@ -0,0 +1,149 @@
+---
+description: "Discussion of the CLI commands and options part of the codebase"
+---
+
+# CLI Commands and Options
+
+This document covers the command-line interface implementation, including command structure, argument parsing, validation, and extension patterns.
+
+## Architecture Overview
+
+The CLI is built using a modular command structure where each command is implemented as a separate module with standardized interfaces for argument parsing, validation, and execution.
+
+### Key Components
+
+- **Command Registration**: Commands are registered through a central registry system
+- **Argument Parsing**: Uses a consistent parsing framework for options, flags, and positional arguments
+- **Validation Pipeline**: Multi-stage validation including syntax, semantic, and context validation
+- **Error Handling**: Standardized error reporting with user-friendly messages and exit codes
+
+## Command Structure Patterns
+
+### Command Definition
+Commands follow a consistent structure with:
+- Command metadata (name, description, aliases)
+- Argument/option definitions with types and validation rules
+- Handler function for command execution
+- Help text generation
+
+### Option Types
+- **Boolean flags**: Simple on/off switches
+- **String options**: Text input with optional validation patterns
+- **Enum options**: Predefined value sets with validation
+- **Array options**: Multiple values of the same type
+- **File/path options**: Special handling for filesystem references
+
+## Development Conventions
+
+### Adding New Commands
+1. Create command module in appropriate subdirectory
+2. Define command schema with full type information
+3. Implement validation logic (both sync and async where needed)
+4. Add comprehensive error handling with specific error codes
+5. Include help text and examples
+6. Register command in central registry
+7. Add integration tests covering common usage patterns
+
+### Option Naming Conventions
+- Use kebab-case for multi-word options (`--config-file`)
+- Provide short aliases for frequently used options (`-c` for `--config`)
+- Boolean flags should be positive by default (`--enable-feature` not `--disable-feature`)
+- Use consistent naming across related commands
+
+### Validation Patterns
+- **Input Validation**: Check argument types, ranges, and format requirements
+- **Context Validation**: Verify prerequisites, file existence, permissions
+- **Cross-option Validation**: Ensure option combinations are valid
+- **Async Validation**: Handle network-dependent or filesystem validation
+
+## Integration Points
+
+### Configuration System
+Commands integrate with the configuration system to:
+- Load default values from config files
+- Override config with command-line arguments
+- Validate configuration consistency
+
+### Logging and Output
+- Use structured logging for debugging and audit trails
+- Implement consistent output formatting (JSON, table, plain text)
+- Handle progress reporting for long-running operations
+
+### Error Handling
+- Map internal errors to user-friendly messages
+- Use specific exit codes for different error categories
+- Provide actionable error messages with suggested fixes
+
+## Common Patterns
+
+### Async Command Execution
+Most commands involve async operations (file I/O, network requests). Follow patterns for:
+- Proper async/await usage
+- Timeout handling
+- Graceful cancellation
+- Progress reporting
+
+### File System Operations
+- Always validate paths before operations
+- Handle relative vs absolute path resolution
+- Implement proper error handling for permissions, missing files
+- Consider cross-platform path handling
+
+### Configuration Merging
+Commands often need to merge configuration from multiple sources:
+1. Default values
+2. Configuration files
+3. Environment variables
+4. Command-line arguments
+
+## Testing Patterns
+
+### Unit Tests
+- Test command parsing in isolation
+- Validate option validation logic
+- Mock external dependencies
+- Test error conditions and edge cases
+
+### Integration Tests
+- Test complete command execution flows
+- Verify file system interactions
+- Test configuration loading and merging
+- Validate output formatting
+
+## Common Pitfalls
+
+### Argument Parsing
+- Be careful with optional vs required arguments
+- Handle edge cases in string parsing (quotes, escaping)
+- Validate mutually exclusive options
+- Consider default value precedence
+
+### Error Messages
+- Avoid technical jargon in user-facing messages
+- Provide specific error locations (line numbers, file paths)
+- Include suggested fixes when possible
+- Use consistent error formatting
+
+### Performance Considerations
+- Lazy-load command modules to improve startup time
+- Cache validation results when appropriate
+- Optimize for common usage patterns
+- Handle large input sets efficiently
+
+## Extension Points
+
+### Custom Validators
+The validation system supports custom validators for domain-specific requirements.
+
+### Output Formatters
+New output formats can be added through the formatter registry.
+
+### Command Plugins
+External commands can be registered through the plugin system.
+
+## Key Files and Directories
+
+- `/src/spec-node/devContainersSpecCLI.ts` - Main CLI entry point
+- `/src/spec-configuration/` - Configuration parsing and validation
+- `/src/spec-utils/` - Shared utilities for command implementation
+- Tests in `/src/test/` following command structure
@@ -0,0 +1,178 @@
+---
+description: "Discussion of the devcontainers CLI project architecture, conventions, and development patterns"
+---
+
+# DevContainers CLI Project Instructions
+
+## Overview
+
+The DevContainers CLI (`@devcontainers/cli`) is a TypeScript-based Node.js project that implements the [Development Containers specification](https://containers.dev). It provides tooling for building, running, and managing development containers across different container runtimes and orchestrators.
+
+## Architecture
+
+### Core Components
+
+- **`src/spec-configuration/`** - Configuration parsing and validation for devcontainer.json
+- **`src/spec-node/`** - Node.js-specific implementations of the specification
+- **`src/spec-utils/`** - Shared utilities for specification handling
+- **`src/test/`** - Comprehensive test suites including container tests
+
+### Key Design Principles
+
+1. **Specification Compliance**: All features must align with the official devcontainer specification
+2. **Multi-Runtime Support**: Support for Docker, Podman, and other container runtimes
+3. **Cross-Platform**: Works on Windows, macOS, and Linux
+4. **Extensibility**: Plugin architecture for features and lifecycle hooks
+
+## Development Conventions
+
+### TypeScript Patterns
+
+- Use strict TypeScript configuration with `noImplicitAny` and `strictNullChecks`
+- Prefer interfaces over type aliases for object shapes
+- Use proper async/await patterns, avoid callback-style APIs
+- Export types and interfaces from dedicated `types.ts` files
+
+### Error Handling
+
+- Use custom error classes that extend base `Error`
+- Provide meaningful error messages with context
+- Include error codes for programmatic handling
+- Log errors at appropriate levels using the project's logging system
+
+### Testing Strategy
+
+- Unit tests in `src/test/` with `.test.ts` suffix
+- Container integration tests that actually build and run containers
+- Mock external dependencies (Docker API, file system operations)
+- Use descriptive test names that explain the scenario being tested
+
+## Key Integration Points
+
+### Container Runtime Integration
+
+- **Docker**: Primary runtime support via Docker API
+- **Podman**: Alternative runtime with compatibility layer
+- **BuildKit**: For advanced build features and caching
+
+### File System Operations
+
+- Configuration discovery and parsing from workspace roots
+- Template and feature resolution from local and remote sources
+- Volume mounting and bind mount handling across platforms
+
+### External Dependencies
+
+- **Container registries**: For pulling base images and publishing
+- **Git repositories**: For fetching features and templates
+- **Package managers**: npm, pip, apt for installing tools in containers
+
+## Common Development Patterns
+
+### Adding New CLI Commands
+
+1. Define command in `src/spec-node/devContainersSpecCLI.ts`
+2. Implement handler function with proper argument parsing
+3. Add comprehensive error handling and logging
+4. Include unit and integration tests
+5. Update CLI help text and documentation
+
+### Configuration Processing
+
+- Use `src/spec-configuration/` utilities for parsing devcontainer.json
+- Validate configuration against JSON schema
+- Handle inheritance and composition (extends, merging)
+- Support both local and remote configuration sources
+
+### Feature Implementation
+
+- Follow the specification's feature model
+- Support installation scripts and lifecycle hooks
+- Handle dependency resolution and ordering
+- Provide proper cleanup and error recovery
+
+## Common Pitfalls
+
+### Platform-Specific Issues
+
+- **Path handling**: Use `path.posix` for container paths, `path` for host paths
+- **Line endings**: Handle CRLF/LF differences in scripts and configs
+- **File permissions**: Different behavior on Windows vs Unix systems
+- **Container mounting**: Volume vs bind mount differences across platforms
+
+### Container Runtime Differences
+
+- Docker Desktop vs Docker Engine behavior variations
+- Podman compatibility quirks (networking, volumes, security contexts)
+- Image building differences between runtimes
+- Registry authentication handling
+
+### Performance Considerations
+
+- **Image caching**: Leverage BuildKit and registry caching
+- **Parallel operations**: Use proper concurrency for multi-container scenarios
+- **File watching**: Efficient change detection for rebuild scenarios
+- **Network optimization**: Minimize registry pulls and DNS lookups
+
+## Development Workflow
+
+### Setup and Building
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Run container tests (requires Docker)
+npm run test:container
+```
+
+### Testing Guidelines
+
+- Always test with actual containers, not just mocks
+- Test cross-platform scenarios when possible
+- Include negative test cases for error conditions
+- Verify cleanup behavior (containers, volumes, networks)
+
+### Debugging
+
+- Use `--log-level trace` for detailed operation logging
+- Container logs are available via runtime APIs
+- File system operations are logged at debug level
+- Network issues often manifest as timeout errors
+
+## Extension Points
+
+### Custom Features
+
+- Implement in separate npm packages
+- Follow feature specification format
+- Provide proper metadata and documentation
+- Test with multiple base images and scenarios
+
+### Lifecycle Hooks
+
+- `onCreateCommand`, `postCreateCommand`, `postStartCommand`
+- Handle both synchronous and asynchronous operations
+- Provide proper error propagation
+- Support both shell commands and executable scripts
+
+## Related Documentation
+
+- [Contributing Guidelines](../../CONTRIBUTING.md)
+- [Development Container Specification](https://containers.dev)
+- [Feature and Template specifications](https://containers.dev/implementors/features/)
+- [JSON Schema definitions](src/spec-configuration/schemas/)
+
+## Key Files and Directories
+
+- `src/spec-node/devContainersSpecCLI.ts` - Main CLI entry point
+- `src/spec-configuration/configuration.ts` - Configuration parsing logic
+- `src/spec-utils/` - Shared utilities and helpers
+- `src/test/container-features/` - Feature integration tests
+- `.devcontainer/` - Project's own development container configuration
@@ -0,0 +1,28 @@
+---
+mode: edit
+---
+Analyze the user requested part of the codebase (use a suitable <placeholder>) to generate or update `.github/instructions/<placeholder>.instructions.md` for guiding AI coding agents.
+
+Focus on discovering the essential knowledge that would help an AI agents be immediately productive in the <placeholder> part of the codebase. Consider aspects like:
+- The design and how it fits into the overall architecture
+- Component-specific conventions and patterns that differ from common practices
+- Integration points, external dependencies, and cross-component communication patterns
+- Common pitfalls, edge cases, and non-obvious behaviors specific to this part of the codebase
+- What are common ways to add to this part of the codebase?
+
+Source existing conventions from `.github/instructions/*.instructions.md,CONTRIBUTING.md,README.md}` and cross reference any of these files where relevant.
+
+Guidelines (read more at https://aka.ms/vscode-instructions-docs):
+- If `.github/instructions/<placeholder>.instructions.md` exists, merge intelligently - preserve valuable content while updating outdated sections
+- Write concise instructions using markdown structure
+- Document only discoverable patterns, not aspirational practices
+- Reference key files/directories that exemplify important patterns
+
+Your audience is other developers working on this project who know less about this feature area or other agents who come into this area to make changes.
+
+Update `.github/instructions/<placeholder>.instructions.md` for the user. Include an instructions header:
+```
+---
+description: "Discussion of the <placeholder> part of the codebase"
+---
+```