Skip to content

Commit 0cfd6f0

Browse files
chrmartichrmarti
committed
tmp
1 parent 721c21b commit 0cfd6f0

File tree

12 files changed

+609
-29
lines changed

12 files changed

+609
-29
lines changed

‎.github/instructions/cli-commands-options.instructions.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
description: "Discussion of the CLI commands and options part of the codebase"
3+
---
4+
5+
# CLI Commands and Options
6+
7+
This document covers the command-line interface implementation, including command structure, argument parsing, validation, and extension patterns.
8+
9+
## Architecture Overview
10+
11+
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.
12+
13+
### Key Components
14+
15+
- **Command Registration**: Commands are registered through a central registry system
16+
- **Argument Parsing**: Uses a consistent parsing framework for options, flags, and positional arguments
17+
- **Validation Pipeline**: Multi-stage validation including syntax, semantic, and context validation
18+
- **Error Handling**: Standardized error reporting with user-friendly messages and exit codes
19+
20+
## Command Structure Patterns
21+
22+
### Command Definition
23+
Commands follow a consistent structure with:
24+
- Command metadata (name, description, aliases)
25+
- Argument/option definitions with types and validation rules
26+
- Handler function for command execution
27+
- Help text generation
28+
29+
### Option Types
30+
- **Boolean flags**: Simple on/off switches
31+
- **String options**: Text input with optional validation patterns
32+
- **Enum options**: Predefined value sets with validation
33+
- **Array options**: Multiple values of the same type
34+
- **File/path options**: Special handling for filesystem references
35+
36+
## Development Conventions
37+
38+
### Adding New Commands
39+
1. Create command module in appropriate subdirectory
40+
2. Define command schema with full type information
41+
3. Implement validation logic (both sync and async where needed)
42+
4. Add comprehensive error handling with specific error codes
43+
5. Include help text and examples
44+
6. Register command in central registry
45+
7. Add integration tests covering common usage patterns
46+
47+
### Option Naming Conventions
48+
- Use kebab-case for multi-word options (`--config-file`)
49+
- Provide short aliases for frequently used options (`-c` for `--config`)
50+
- Boolean flags should be positive by default (`--enable-feature` not `--disable-feature`)
51+
- Use consistent naming across related commands
52+
53+
### Validation Patterns
54+
- **Input Validation**: Check argument types, ranges, and format requirements
55+
- **Context Validation**: Verify prerequisites, file existence, permissions
56+
- **Cross-option Validation**: Ensure option combinations are valid
57+
- **Async Validation**: Handle network-dependent or filesystem validation
58+
59+
## Integration Points
60+
61+
### Configuration System
62+
Commands integrate with the configuration system to:
63+
- Load default values from config files
64+
- Override config with command-line arguments
65+
- Validate configuration consistency
66+
67+
### Logging and Output
68+
- Use structured logging for debugging and audit trails
69+
- Implement consistent output formatting (JSON, table, plain text)
70+
- Handle progress reporting for long-running operations
71+
72+
### Error Handling
73+
- Map internal errors to user-friendly messages
74+
- Use specific exit codes for different error categories
75+
- Provide actionable error messages with suggested fixes
76+
77+
## Common Patterns
78+
79+
### Async Command Execution
80+
Most commands involve async operations (file I/O, network requests). Follow patterns for:
81+
- Proper async/await usage
82+
- Timeout handling
83+
- Graceful cancellation
84+
- Progress reporting
85+
86+
### File System Operations
87+
- Always validate paths before operations
88+
- Handle relative vs absolute path resolution
89+
- Implement proper error handling for permissions, missing files
90+
- Consider cross-platform path handling
91+
92+
### Configuration Merging
93+
Commands often need to merge configuration from multiple sources:
94+
1. Default values
95+
2. Configuration files
96+
3. Environment variables
97+
4. Command-line arguments
98+
99+
## Testing Patterns
100+
101+
### Unit Tests
102+
- Test command parsing in isolation
103+
- Validate option validation logic
104+
- Mock external dependencies
105+
- Test error conditions and edge cases
106+
107+
### Integration Tests
108+
- Test complete command execution flows
109+
- Verify file system interactions
110+
- Test configuration loading and merging
111+
- Validate output formatting
112+
113+
## Common Pitfalls
114+
115+
### Argument Parsing
116+
- Be careful with optional vs required arguments
117+
- Handle edge cases in string parsing (quotes, escaping)
118+
- Validate mutually exclusive options
119+
- Consider default value precedence
120+
121+
### Error Messages
122+
- Avoid technical jargon in user-facing messages
123+
- Provide specific error locations (line numbers, file paths)
124+
- Include suggested fixes when possible
125+
- Use consistent error formatting
126+
127+
### Performance Considerations
128+
- Lazy-load command modules to improve startup time
129+
- Cache validation results when appropriate
130+
- Optimize for common usage patterns
131+
- Handle large input sets efficiently
132+
133+
## Extension Points
134+
135+
### Custom Validators
136+
The validation system supports custom validators for domain-specific requirements.
137+
138+
### Output Formatters
139+
New output formats can be added through the formatter registry.
140+
141+
### Command Plugins
142+
External commands can be registered through the plugin system.
143+
144+
## Key Files and Directories
145+
146+
- `/src/spec-node/devContainersSpecCLI.ts` - Main CLI entry point
147+
- `/src/spec-configuration/` - Configuration parsing and validation
148+
- `/src/spec-utils/` - Shared utilities for command implementation
149+
- Tests in `/src/test/` following command structure

‎.github/instructions/project-overview.instructions.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
description: "Discussion of the devcontainers CLI project architecture, conventions, and development patterns"
3+
---
4+
5+
# DevContainers CLI Project Instructions
6+
7+
## Overview
8+
9+
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.
10+
11+
## Architecture
12+
13+
### Core Components
14+
15+
- **`src/spec-configuration/`** - Configuration parsing and validation for devcontainer.json
16+
- **`src/spec-node/`** - Node.js-specific implementations of the specification
17+
- **`src/spec-utils/`** - Shared utilities for specification handling
18+
- **`src/test/`** - Comprehensive test suites including container tests
19+
20+
### Key Design Principles
21+
22+
1. **Specification Compliance**: All features must align with the official devcontainer specification
23+
2. **Multi-Runtime Support**: Support for Docker, Podman, and other container runtimes
24+
3. **Cross-Platform**: Works on Windows, macOS, and Linux
25+
4. **Extensibility**: Plugin architecture for features and lifecycle hooks
26+
27+
## Development Conventions
28+
29+
### TypeScript Patterns
30+
31+
- Use strict TypeScript configuration with `noImplicitAny` and `strictNullChecks`
32+
- Prefer interfaces over type aliases for object shapes
33+
- Use proper async/await patterns, avoid callback-style APIs
34+
- Export types and interfaces from dedicated `types.ts` files
35+
36+
### Error Handling
37+
38+
- Use custom error classes that extend base `Error`
39+
- Provide meaningful error messages with context
40+
- Include error codes for programmatic handling
41+
- Log errors at appropriate levels using the project's logging system
42+
43+
### Testing Strategy
44+
45+
- Unit tests in `src/test/` with `.test.ts` suffix
46+
- Container integration tests that actually build and run containers
47+
- Mock external dependencies (Docker API, file system operations)
48+
- Use descriptive test names that explain the scenario being tested
49+
50+
## Key Integration Points
51+
52+
### Container Runtime Integration
53+
54+
- **Docker**: Primary runtime support via Docker API
55+
- **Podman**: Alternative runtime with compatibility layer
56+
- **BuildKit**: For advanced build features and caching
57+
58+
### File System Operations
59+
60+
- Configuration discovery and parsing from workspace roots
61+
- Template and feature resolution from local and remote sources
62+
- Volume mounting and bind mount handling across platforms
63+
64+
### External Dependencies
65+
66+
- **Container registries**: For pulling base images and publishing
67+
- **Git repositories**: For fetching features and templates
68+
- **Package managers**: npm, pip, apt for installing tools in containers
69+
70+
## Common Development Patterns
71+
72+
### Adding New CLI Commands
73+
74+
1. Define command in `src/spec-node/devContainersSpecCLI.ts`
75+
2. Implement handler function with proper argument parsing
76+
3. Add comprehensive error handling and logging
77+
4. Include unit and integration tests
78+
5. Update CLI help text and documentation
79+
80+
### Configuration Processing
81+
82+
- Use `src/spec-configuration/` utilities for parsing devcontainer.json
83+
- Validate configuration against JSON schema
84+
- Handle inheritance and composition (extends, merging)
85+
- Support both local and remote configuration sources
86+
87+
### Feature Implementation
88+
89+
- Follow the specification's feature model
90+
- Support installation scripts and lifecycle hooks
91+
- Handle dependency resolution and ordering
92+
- Provide proper cleanup and error recovery
93+
94+
## Common Pitfalls
95+
96+
### Platform-Specific Issues
97+
98+
- **Path handling**: Use `path.posix` for container paths, `path` for host paths
99+
- **Line endings**: Handle CRLF/LF differences in scripts and configs
100+
- **File permissions**: Different behavior on Windows vs Unix systems
101+
- **Container mounting**: Volume vs bind mount differences across platforms
102+
103+
### Container Runtime Differences
104+
105+
- Docker Desktop vs Docker Engine behavior variations
106+
- Podman compatibility quirks (networking, volumes, security contexts)
107+
- Image building differences between runtimes
108+
- Registry authentication handling
109+
110+
### Performance Considerations
111+
112+
- **Image caching**: Leverage BuildKit and registry caching
113+
- **Parallel operations**: Use proper concurrency for multi-container scenarios
114+
- **File watching**: Efficient change detection for rebuild scenarios
115+
- **Network optimization**: Minimize registry pulls and DNS lookups
116+
117+
## Development Workflow
118+
119+
### Setup and Building
120+
121+
```bash
122+
# Install dependencies
123+
npm install
124+
125+
# Build TypeScript
126+
npm run build
127+
128+
# Run tests
129+
npm test
130+
131+
# Run container tests (requires Docker)
132+
npm run test:container
133+
```
134+
135+
### Testing Guidelines
136+
137+
- Always test with actual containers, not just mocks
138+
- Test cross-platform scenarios when possible
139+
- Include negative test cases for error conditions
140+
- Verify cleanup behavior (containers, volumes, networks)
141+
142+
### Debugging
143+
144+
- Use `--log-level trace` for detailed operation logging
145+
- Container logs are available via runtime APIs
146+
- File system operations are logged at debug level
147+
- Network issues often manifest as timeout errors
148+
149+
## Extension Points
150+
151+
### Custom Features
152+
153+
- Implement in separate npm packages
154+
- Follow feature specification format
155+
- Provide proper metadata and documentation
156+
- Test with multiple base images and scenarios
157+
158+
### Lifecycle Hooks
159+
160+
- `onCreateCommand`, `postCreateCommand`, `postStartCommand`
161+
- Handle both synchronous and asynchronous operations
162+
- Provide proper error propagation
163+
- Support both shell commands and executable scripts
164+
165+
## Related Documentation
166+
167+
- [Contributing Guidelines](../../CONTRIBUTING.md)
168+
- [Development Container Specification](https://containers.dev)
169+
- [Feature and Template specifications](https://containers.dev/implementors/features/)
170+
- [JSON Schema definitions](src/spec-configuration/schemas/)
171+
172+
## Key Files and Directories
173+
174+
- `src/spec-node/devContainersSpecCLI.ts` - Main CLI entry point
175+
- `src/spec-configuration/configuration.ts` - Configuration parsing logic
176+
- `src/spec-utils/` - Shared utilities and helpers
177+
- `src/test/container-features/` - Feature integration tests
178+
- `.devcontainer/` - Project's own development container configuration

‎.github/prompts/extract-instructions.prompt.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
mode: edit
3+
---
4+
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.
5+
6+
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:
7+
- The design and how it fits into the overall architecture
8+
- Component-specific conventions and patterns that differ from common practices
9+
- Integration points, external dependencies, and cross-component communication patterns
10+
- Common pitfalls, edge cases, and non-obvious behaviors specific to this part of the codebase
11+
- What are common ways to add to this part of the codebase?
12+
13+
Source existing conventions from `.github/instructions/*.instructions.md,CONTRIBUTING.md,README.md}` and cross reference any of these files where relevant.
14+
15+
Guidelines (read more at https://aka.ms/vscode-instructions-docs):
16+
- If `.github/instructions/<placeholder>.instructions.md` exists, merge intelligently - preserve valuable content while updating outdated sections
17+
- Write concise instructions using markdown structure
18+
- Document only discoverable patterns, not aspirational practices
19+
- Reference key files/directories that exemplify important patterns
20+
21+
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.
22+
23+
Update `.github/instructions/<placeholder>.instructions.md` for the user. Include an instructions header:
24+
```
25+
---
26+
description: "Discussion of the <placeholder> part of the codebase"
27+
---
28+
```

0 commit comments

Comments
 (0)