Skip to content

Commit 086199d

Browse files
CopilotMalcolmnixon
Copilot
and
Malcolmnixon
authored
Add comprehensive project documentation (#16)
* Initial plan * Add comprehensive documentation files and enhance README - Add ARCHITECTURE.md with Mermaid diagram - Add CODE_OF_CONDUCT.md (Contributor Covenant 2.1) - Add CONTRIBUTING.md with development guidelines - Add SECURITY.md with security policy - Enhance README.md with feature table and better structure - Update AGENTS.md with references to new documentation - Update .cspell.json with new words Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Address code review feedback - Add missing files to project structure in CONTRIBUTING.md - Add WASM platform support clarification in ARCHITECTURE.md Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> * Convert features table to bullet list with icons Replace features table with icon-based bullet list for better readability Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
1 parent 9b19cd2 commit 086199d

File tree

7 files changed

+889
-7
lines changed

7 files changed

+889
-7
lines changed

‎.cspell.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,13 @@
2121
"DotnetToolWrapper",
2222
"github",
2323
"workflows",
24-
"yaml"
24+
"yaml",
25+
"mermaid",
26+
"PowerPC",
27+
"malware",
28+
"sandboxing",
29+
"socio",
30+
"appsettings"
2531
],
2632
"ignorePaths": [
2733
"node_modules",

‎AGENTS.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,15 @@ Quality checks are automated through GitHub Actions:
8484
1. Follow the markdown linting rules in `.markdownlint.json`
8585
2. Check spelling against `.cspell.json` dictionary
8686
3. Keep README.md synchronized with actual functionality
87+
4. Update ARCHITECTURE.md if making architectural changes
88+
5. Reference appropriate documentation files (README.md, ARCHITECTURE.md, CONTRIBUTING.md, SECURITY.md)
89+
90+
### When Addressing Security Issues
91+
92+
1. Follow the security policy outlined in `SECURITY.md`
93+
2. Never commit sensitive information
94+
3. Consider all supported platforms when evaluating security impact
95+
4. Update security documentation if introducing new security considerations
8796

8897
## Common Tasks
8998

@@ -109,6 +118,15 @@ Before committing:
109118
2. Run spelling checks: `npx cspell "**/*.md"`
110119
3. Run markdown linting: `npx markdownlint "**/*.md"`
111120

121+
## Related Documentation
122+
123+
- [README.md](README.md) - Project overview and quick start guide
124+
- [ARCHITECTURE.md](ARCHITECTURE.md) - Detailed architecture and design documentation
125+
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines and development setup
126+
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Community code of conduct
127+
- [SECURITY.md](SECURITY.md) - Security policy and vulnerability reporting
128+
- [LICENSE](LICENSE) - MIT License terms
129+
112130
## Contact
113131

114132
For questions or issues, please refer to the repository's issue tracker on GitHub.

‎ARCHITECTURE.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Architecture
2+
3+
This document describes the architecture and design of the DotnetToolWrapper project.
4+
5+
## Overview
6+
7+
DotnetToolWrapper is a .NET console application that serves as a universal launcher for native applications packaged
8+
as [.NET Tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools). It enables developers to distribute
9+
platform-specific native executables through the .NET tool ecosystem.
10+
11+
## Problem Statement
12+
13+
The .NET tool ecosystem provides a convenient way to distribute and install command-line tools globally or locally
14+
within projects. However, .NET tools are inherently limited to .NET applications. Many useful command-line tools are
15+
written in other languages (C, C++, Rust, Go, etc.) and compiled to native executables. DotnetToolWrapper bridges this
16+
gap by providing a managed .NET entry point that launches the appropriate native executable for the current platform.
17+
18+
## High-Level Architecture
19+
20+
```mermaid
21+
flowchart TB
22+
subgraph package[".NET Tool Package"]
23+
settings["DotnetToolSettings.xml<br/>Defines tool command name and entry point"]
24+
25+
subgraph wrapper["DemaConsulting.DotnetToolWrapper.dll<br/>(This Application)"]
26+
step1["1. Detect OS and Architecture"]
27+
step2["2. Read DotnetToolWrapper.json"]
28+
step3["3. Locate native executable"]
29+
step4["4. Launch native executable"]
30+
step5["5. Return exit code"]
31+
32+
step1 --> step2 --> step3 --> step4 --> step5
33+
end
34+
35+
config["DotnetToolWrapper.json<br/>Maps platforms to executables<br/><br/>{<br/> 'win-x64': { 'program': 'win-x64/tool.exe' },<br/> 'linux-x64': { 'program': 'linux-x64/tool' },<br/> 'osx-arm64': { 'program': 'osx-arm64/tool' }<br/>}"]
36+
37+
natives["Native Executables<br/><br/>win-x64/tool.exe (Windows x64)<br/>linux-x64/tool (Linux x64)<br/>osx-arm64/tool (macOS ARM64)<br/>..."]
38+
39+
settings --> wrapper
40+
wrapper --> config
41+
config --> natives
42+
end
43+
```
44+
45+
## Core Components
46+
47+
### Program.cs
48+
49+
The main application logic consists of several key functions:
50+
51+
#### Platform Detection
52+
53+
- **`GetOs()`**: Detects the operating system (Windows, Linux, FreeBSD, macOS)
54+
- **`GetArchitecture()`**: Detects the CPU architecture (x86, x64, ARM, ARM64, WASM, S390x)
55+
- **`GetTarget()`**: Combines OS and architecture into a target string (e.g., "win-x64", "linux-arm64")
56+
57+
#### Configuration Management
58+
59+
The application reads `DotnetToolWrapper.json` to determine which native executable to launch for the detected platform.
60+
This JSON file is located in the same directory as the wrapper DLL.
61+
62+
#### Process Execution
63+
64+
The wrapper locates the native executable, constructs a process with the original command-line arguments, and executes
65+
it in the current working directory. The wrapper then waits for the process to complete and returns its exit code.
66+
67+
## Configuration Schema
68+
69+
### DotnetToolWrapper.json
70+
71+
The configuration file uses a simple JSON structure:
72+
73+
```json
74+
{
75+
"<target-string>": {
76+
"program": "<path-to-executable>"
77+
}
78+
}
79+
```
80+
81+
- **Target String**: Combination of OS and architecture (e.g., "win-x64", "linux-arm64")
82+
- **Program Path**: Relative or absolute path to the native executable
83+
- Relative paths are resolved from the wrapper's installation directory
84+
- Environment variables are expanded
85+
86+
### Supported Target Strings
87+
88+
| OS | Architectures | Notes |
89+
|---------|--------------------------------------------------|---------------------------------|
90+
| win | x86, x64, arm, arm64 | Windows platforms |
91+
| linux | x86, x64, arm, arm64, s390x | Linux distributions |
92+
| freebsd | x86, x64, arm, arm64 | FreeBSD platforms |
93+
| osx | x64, arm64 | macOS platforms |
94+
| browser | wasm | WebAssembly (experimental) |
95+
96+
## Design Decisions
97+
98+
### Multi-Framework Targeting
99+
100+
The application targets .NET 8.0, 9.0, and 10.0 to ensure broad compatibility across different .NET installations.
101+
This allows the tool to work with both current and recent .NET SDK versions.
102+
103+
### Minimal Dependencies
104+
105+
The application has no external dependencies beyond the .NET standard library. This keeps the package size small and
106+
reduces potential compatibility issues.
107+
108+
### Process Execution Model
109+
110+
The wrapper uses `ProcessStartInfo` with `UseShellExecute = false` to directly execute the native program without
111+
involving the system shell. This provides better security and more predictable behavior across platforms.
112+
113+
### Exit Code Propagation
114+
115+
The wrapper exits with the same exit code as the wrapped native executable, ensuring that build scripts and automation
116+
tools can correctly detect success or failure.
117+
118+
### Working Directory Preservation
119+
120+
The wrapper executes the native program in the user's current working directory, not in the installation directory.
121+
This ensures that relative file paths in command-line arguments work as expected.
122+
123+
## Extension Points
124+
125+
### Environment Variables
126+
127+
The `program` path in the configuration supports environment variable expansion using standard .NET
128+
`Environment.ExpandEnvironmentVariables()`. This allows for dynamic configuration based on the runtime environment.
129+
130+
### Future Enhancements
131+
132+
Potential future extensions could include:
133+
134+
- Custom environment variable injection
135+
- Pre-launch and post-launch hooks
136+
- Configuration-based argument transformation
137+
- Logging and diagnostics options
138+
139+
## Security Considerations
140+
141+
- The wrapper does not validate or sanitize command-line arguments; they are passed directly to the native executable
142+
- The configuration file must be trusted, as it specifies which executables to run
143+
- The wrapper should be distributed with native executables from trusted sources
144+
- Package creators should scan native executables for malware before distribution
145+
146+
## Performance Characteristics
147+
148+
- **Startup Overhead**: Minimal (< 50ms on modern hardware)
149+
- **Memory Footprint**: Small (~20-30 MB for the .NET runtime + wrapper)
150+
- **CPU Usage**: Negligible (the wrapper is idle while the native process runs)
151+
152+
## Testing Strategy
153+
154+
The project does not currently include automated tests. Testing is performed through:
155+
156+
1. Manual testing on target platforms (Windows, Linux, macOS)
157+
2. Integration testing with sample .NET tool packages
158+
3. CI/CD builds that verify compilation for all target frameworks
159+
160+
## Build and Release Process
161+
162+
The project uses GitHub Actions for CI/CD:
163+
164+
1. **Build Workflow**: Compiles the application for all target frameworks
165+
2. **SBOM Generation**: Creates Software Bill of Materials for transparency
166+
3. **Artifact Publishing**: Publishes build artifacts for packaging
167+
4. **Release Workflow**: Creates releases with versioned artifacts
168+
169+
## Related Documentation
170+
171+
- [README.md](README.md) - Usage instructions and examples
172+
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
173+
- [SECURITY.md](SECURITY.md) - Security policy

‎CODE_OF_CONDUCT.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Project maintainers are responsible for clarifying and enforcing our standards
42+
of acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Project maintainers have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the project maintainers responsible for enforcement through
63+
GitHub's issue reporting system or by contacting the repository maintainers
64+
directly.
65+
66+
All complaints will be reviewed and investigated promptly and fairly.
67+
68+
All project maintainers are obligated to respect the privacy and security of the
69+
reporter of any incident.
70+
71+
## Enforcement Guidelines
72+
73+
Project maintainers will follow these Community Impact Guidelines in determining
74+
the consequences for any action they deem in violation of this Code of Conduct:
75+
76+
### 1. Correction
77+
78+
**Community Impact**: Use of inappropriate language or other behavior deemed
79+
unprofessional or unwelcome in the community.
80+
81+
**Consequence**: A private, written warning from project maintainers, providing
82+
clarity around the nature of the violation and an explanation of why the
83+
behavior was inappropriate. A public apology may be requested.
84+
85+
### 2. Warning
86+
87+
**Community Impact**: A violation through a single incident or series of
88+
actions.
89+
90+
**Consequence**: A warning with consequences for continued behavior. No
91+
interaction with the people involved, including unsolicited interaction with
92+
those enforcing the Code of Conduct, for a specified period of time. This
93+
includes avoiding interactions in community spaces as well as external channels
94+
like social media. Violating these terms may lead to a temporary or permanent
95+
ban.
96+
97+
### 3. Temporary Ban
98+
99+
**Community Impact**: A serious violation of community standards, including
100+
sustained inappropriate behavior.
101+
102+
**Consequence**: A temporary ban from any sort of interaction or public
103+
communication with the community for a specified period of time. No public or
104+
private interaction with the people involved, including unsolicited interaction
105+
with those enforcing the Code of Conduct, is allowed during this period.
106+
Violating these terms may lead to a permanent ban.
107+
108+
### 4. Permanent Ban
109+
110+
**Community Impact**: Demonstrating a pattern of violation of community
111+
standards, including sustained inappropriate behavior, harassment of an
112+
individual, or aggression toward or disparagement of classes of individuals.
113+
114+
**Consequence**: A permanent ban from any sort of public interaction within the
115+
project community.
116+
117+
## Attribution
118+
119+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
120+
version 2.1, available at
121+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
122+
123+
Community Impact Guidelines were inspired by
124+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
125+
126+
For answers to common questions about this code of conduct, see the FAQ at
127+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
128+
[https://www.contributor-covenant.org/translations][translations].
129+
130+
[homepage]: https://www.contributor-covenant.org
131+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
132+
[Mozilla CoC]: https://github.com/mozilla/diversity
133+
[FAQ]: https://www.contributor-covenant.org/faq
134+
[translations]: https://www.contributor-covenant.org/translations

0 commit comments

Comments
 (0)