Skip to content

Commit f7653fd

Browse files
joshuaevanjoshuaevan
authored
Merge pull request #2 from joshuaevan/dev
v1.1.0 - Module conversion, CI, documented commands, and self-update
2 parents ac0dd17 + 6b792bf commit f7653fd

80 files changed

Lines changed: 5604 additions & 489 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: ["**"]
6+
pull_request:
7+
branches: ["**"]
8+
9+
jobs:
10+
test:
11+
runs-on: windows-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Install Pester
16+
shell: pwsh
17+
run: |
18+
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser -SkipPublisherCheck
19+
20+
- name: Run Pester tests
21+
shell: pwsh
22+
run: |
23+
$config = New-PesterConfiguration
24+
$config.Run.Path = './tests'
25+
$config.Run.Exit = $true
26+
$config.TestResult.Enabled = $true
27+
$config.TestResult.OutputPath = 'TestResults.xml'
28+
$config.TestResult.OutputFormat = 'NUnitXml'
29+
$config.Output.Verbosity = 'Detailed'
30+
Invoke-Pester -Configuration $config
31+
32+
- name: Upload test results
33+
if: always()
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: pester-results
37+
path: TestResults.xml

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ secrets/
2626
# Profile backups
2727
*PROFILE_BACKUP*
2828

29+
# Toolkit update stamp
30+
.last-update-check
31+
2932
# OS files
3033
.DS_Store
3134
Thumbs.db

‎CONTRIBUTING.md‎

Lines changed: 79 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -30,83 +30,78 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
3030

3131
1. **Fork the repository**
3232
2. **Create a new branch** from `main`:
33-
```powershell
33+
```powershell
3434
git checkout -b feature/your-feature-name
35-
```
35+
```
3636
3. **Make your changes**:
37-
- Follow the existing code style
38-
- Add comments for complex logic
39-
- Update documentation if needed
37+
- Follow the existing code style
38+
- Add comments for complex logic
39+
- Update documentation if needed
4040
4. **Test your changes**:
41-
- Test on a clean Windows machine if possible
42-
- Ensure backward compatibility
41+
- Test on a clean Windows machine if possible
42+
- Ensure backward compatibility
4343
5. **Commit your changes**:
44-
```powershell
44+
```powershell
4545
git commit -m "Add feature: your feature description"
46-
```
46+
```
4747
6. **Push to your fork**:
48-
```powershell
48+
```powershell
4949
git push origin feature/your-feature-name
50-
```
50+
```
5151
7. **Open a Pull Request** with a clear title and description
5252

5353
## Coding Standards
5454

5555
### PowerShell Script Guidelines
5656

5757
1. **Use meaningful variable names**
58-
```powershell
58+
```powershell
5959
# Good
6060
$serverHostname = "example.com"
61-
61+
6262
# Bad
6363
$s = "example.com"
64-
```
65-
64+
```
6665
2. **Include comment-based help** for all scripts
67-
```powershell
66+
```powershell
6867
<#
6968
.SYNOPSIS
7069
Brief description
71-
70+
7271
.DESCRIPTION
7372
Detailed description
74-
73+
7574
.PARAMETER Name
7675
Parameter description
77-
76+
7877
.EXAMPLE
7978
script.ps1 -Name "test"
8079
#>
81-
```
82-
80+
```
8381
3. **Use approved verbs** for function names
84-
- Get-, Set-, New-, Remove-, Add-, etc.
85-
- Check: `Get-Verb`
86-
82+
- Get-, Set-, New-, Remove-, Add-, etc.
83+
- Check: `Get-Verb`
8784
4. **Handle errors gracefully**
88-
```powershell
85+
```powershell
8986
try {
9087
# Your code
9188
} catch {
9289
Write-Host "Error: $($_.Exception.Message)" -ForegroundColor Red
9390
exit 1
9491
}
95-
```
96-
92+
```
9793
5. **Support common parameters** when appropriate
98-
```powershell
94+
```powershell
9995
[CmdletBinding()]
10096
param(
10197
[Parameter(Mandatory=$true)]
10298
[string]$Name
10399
)
104-
```
105-
100+
```
106101
6. **Provide meaningful output**
107-
- Use colored output for better UX
108-
- Support `-AsJson` for programmatic use where appropriate
109-
- Show progress for long-running operations
102+
- Use colored output for better UX
103+
- Support `-AsJson` for programmatic use where appropriate
104+
- Show progress for long-running operations
110105

111106
### Configuration
112107

@@ -131,9 +126,32 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
131126

132127
## Testing
133128

134-
While we don't have automated tests yet, please:
129+
Tests are written with [Pester 5](https://pester.dev/) in the `tests/` directory. Run the full suite with:
130+
131+
```powershell
132+
.\Invoke-Tests.ps1
133+
```
134+
135+
This installs Pester 5+ if needed and runs all tests with detailed output. Tests also run automatically via GitHub Actions CI on every push and pull request.
136+
137+
When adding new commands, please add corresponding test coverage. Tests should use the Pester 5 `BeforeAll` pattern:
138+
139+
```powershell
140+
BeforeAll {
141+
$repoRoot = Split-Path -Parent (Split-Path -Parent $PSCommandPath)
142+
Import-Module (Join-Path $repoRoot "PowerShellDevToolkit") -Force
143+
}
144+
145+
Describe "Your-Command" {
146+
It "Should do something" {
147+
# test code
148+
}
149+
}
150+
```
151+
152+
Also test manually:
135153

136-
1. **Test your changes manually** on Windows 10 and 11
154+
1. **Test your changes** on Windows 10 and 11
137155
2. **Test with PowerShell 5.1 and 7+**
138156
3. **Test without WSL** (fallback scenarios)
139157
4. **Test with missing dependencies** (graceful degradation)
@@ -142,20 +160,32 @@ While we don't have automated tests yet, please:
142160

143161
```
144162
powershell-dev-toolkit/
145-
├── README.md # Main documentation
146-
├── config.example.json # Configuration template
147-
├── Setup-Environment.ps1 # Setup script
148-
├── Get-ScriptConfig.ps1 # Config loader
149-
├── Connect-SSH.ps1 # SSH scripts
150-
├── Connect-SSHTunnel.ps1
151-
├── Get-*.ps1 # Get/retrieve commands
152-
├── Invoke-*.ps1 # Action commands
153-
├── Start-*.ps1 # Start/launch commands
154-
├── Watch-*.ps1 # Monitor commands
155-
├── New-*.ps1 # Create/generate commands
156-
└── creds/ # Credentials (gitignored)
163+
├── PowerShellDevToolkit/ # The PS module
164+
│ ├── PowerShellDevToolkit.psd1 # Module manifest (version, exports)
165+
│ ├── PowerShellDevToolkit.psm1 # Root module (auto-loader, aliases)
166+
│ ├── Public/ # Exported functions (one per file)
167+
│ │ ├── Connect-SSH.ps1
168+
│ │ ├── Get-GitQuick.ps1
169+
│ │ └── ...
170+
│ └── Private/ # Internal helpers (not exported)
171+
│ └── Get-ScriptConfig.ps1
172+
├── tests/ # Pester tests
173+
├── docs/ # Documentation
174+
├── config.example.json # Configuration template
175+
├── Setup-Environment.ps1 # Bootstrap / installer
176+
├── README.md
177+
├── LICENSE
178+
└── creds/ # Credentials (gitignored)
157179
```
158180

181+
### Adding a new command
182+
183+
1. Create `PowerShellDevToolkit\Public\Verb-Noun.ps1` with a `function Verb-Noun { ... }` wrapper
184+
2. Add the function name to `FunctionsToExport` in `PowerShellDevToolkit.psd1`
185+
3. Optionally add a short alias in `PowerShellDevToolkit.psm1` and `AliasesToExport` in the `.psd1`
186+
4. Add a test file `tests\Verb-Noun.Tests.ps1`
187+
5. Update `Show-Help` in `Public\Show-Help.ps1` with the new command reference
188+
159189
## Commit Messages
160190

161191
Use clear and meaningful commit messages:
@@ -169,6 +199,7 @@ Use clear and meaningful commit messages:
169199
- **chore**: Maintenance tasks
170200

171201
Examples:
202+
172203
```
173204
feat: add support for SQLServer tunneling
174205
fix: resolve credential loading on PowerShell 7
@@ -186,4 +217,4 @@ Be respectful and constructive. We're all here to learn and help each other.
186217

187218
---
188219

189-
Thank you for contributing! 🚀
220+
Thank you for contributing! 🚀

‎Invoke-Tests.ps1‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
#Requires -Version 5.1
2+
<#
3+
.SYNOPSIS
4+
Runs the full Pester test suite for PowerShellDevToolkit.
5+
.DESCRIPTION
6+
Installs Pester 5+ if not present, then runs all tests under .\tests\
7+
with detailed output. Exit code mirrors the Pester result (0 = pass).
8+
.EXAMPLE
9+
.\Invoke-Tests.ps1
10+
#>
11+
12+
$ErrorActionPreference = 'Stop'
13+
14+
if (-not (Get-Module -ListAvailable -Name Pester | Where-Object { $_.Version -ge '5.0' })) {
15+
Write-Host "Pester 5+ not found. Installing from PSGallery..." -ForegroundColor Yellow
16+
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser -SkipPublisherCheck
17+
}
18+
19+
Import-Module Pester -MinimumVersion 5.0.0
20+
21+
$config = New-PesterConfiguration
22+
$config.Run.Path = Join-Path $PSScriptRoot 'tests'
23+
$config.Run.Exit = $true
24+
$config.Output.Verbosity = 'Detailed'
25+
26+
Invoke-Pester -Configuration $config

‎PowerShellDevToolkit/PowerShellDevToolkit.psd1‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
@{
2+
RootModule = 'PowerShellDevToolkit.psm1'
3+
ModuleVersion = '1.2.0'
4+
GUID = '882e07c2-69ad-46e6-aea6-07adb025f6b3'
5+
Author = 'PowerShell Dev Toolkit Contributors'
6+
CompanyName = 'Community'
7+
Copyright = '(c) 2025 PowerShell Dev Toolkit Contributors. All rights reserved.'
8+
Description = 'A comprehensive collection of PowerShell productivity tools for Windows developers. SSH tunneling, project management, AI integration, dev servers, and more.'
9+
10+
PowerShellVersion = '5.1'
11+
12+
FunctionsToExport = @(
13+
# Original commands
14+
'Connect-SSH'
15+
'Connect-SSHTunnel'
16+
'Copy-ToClipboard'
17+
'Find-InProject'
18+
'Get-GitQuick'
19+
'Get-PortProcess'
20+
'Get-ProjectContext'
21+
'Get-ProjectInfo'
22+
'Get-ServiceStatus'
23+
'Invoke-Artisan'
24+
'Invoke-QuickRequest'
25+
'New-AIRules'
26+
'Set-ProjectEnv'
27+
'Show-Help'
28+
'Show-RecentCommands'
29+
'Start-DevServer'
30+
'Watch-LogFile'
31+
# File & editor commands
32+
'Edit-File'
33+
'Edit-Profile'
34+
'Edit-Hosts'
35+
'Use-NppForGit'
36+
'Set-FileTimestamp'
37+
'Open-Item'
38+
# Directory commands
39+
'Get-DirectoryListing'
40+
'New-DirectoryAndEnter'
41+
'Set-TempLocation'
42+
# Utility commands
43+
'Get-CommandLocation'
44+
'Invoke-Elevated'
45+
'Add-Path'
46+
'Invoke-ProfileReload'
47+
# Network commands
48+
'Get-IPAddress'
49+
'Clear-DNSCache'
50+
# Toolkit management
51+
'Update-Toolkit'
52+
'Test-ToolkitUpdate'
53+
)
54+
55+
CmdletsToExport = @()
56+
VariablesToExport = @()
57+
58+
AliasesToExport = @(
59+
# Original aliases
60+
'cssh'
61+
'tunnel'
62+
'tssh'
63+
'gs'
64+
'serve'
65+
'port'
66+
'search'
67+
'tail'
68+
'context'
69+
'proj'
70+
'art'
71+
'http'
72+
'useenv'
73+
'services'
74+
'clip'
75+
'ai-rules'
76+
'rc'
77+
'helpme'
78+
# File & editor aliases
79+
'e'
80+
'npp'
81+
'touch'
82+
'open'
83+
# Directory aliases
84+
'll'
85+
'mkcd'
86+
'temp'
87+
# Utility aliases
88+
'which'
89+
'sudo'
90+
'reload'
91+
'grep'
92+
# Network aliases
93+
'ip'
94+
'Flush-DNS'
95+
)
96+
97+
PrivateData = @{
98+
PSData = @{
99+
Tags = @('Windows', 'Developer', 'Productivity', 'SSH', 'DevTools')
100+
LicenseUri = 'https://github.com/joshuaevan/powershell-dev-toolkit/blob/main/LICENSE'
101+
ProjectUri = 'https://github.com/joshuaevan/powershell-dev-toolkit'
102+
}
103+
}
104+
}

0 commit comments

Comments
 (0)