diff --git a/PSProjectStatus.psd1 b/PSProjectStatus.psd1 index d4516a9..beedc60 100644 --- a/PSProjectStatus.psd1 +++ b/PSProjectStatus.psd1 @@ -2,7 +2,7 @@ @{ RootModule = 'PSProjectStatus.psm1' - ModuleVersion = '0.10.1' + ModuleVersion = '0.11.0' CompatiblePSEditions = 'Desktop', 'Core' GUID = 'ec249544-dc4e-4e24-aae8-4281ec84f54d' Author = 'Jeff Hicks' @@ -11,9 +11,10 @@ Description = 'A set of PowerShell tools for tracking module development status. The module uses a JSON file to create a custom object with information about your module. You can use this internally to track the status of your module including a simple to-do tracker. This module was first described at https://jdhitsolutions.com/blog/powershell/8960/introducing-psprojectstatus/' PowerShellVersion = '5.1' TypesToProcess = @('types\psprojectstatus.types.ps1xml') - FormatsToProcess = @('formats\psprojectstatus.format.ps1xml') + FormatsToProcess = @('formats\psprojectstatus.format.ps1xml','.\formats\psprojecttask.format.ps1xml') FunctionsToExport = 'Get-PSProjectStatus', 'New-PSProjectStatus', 'Set-PSProjectStatus', 'Update-PSProjectStatus', - 'Get-PSProjectGitStatus','Get-PSProjectReport' + 'Get-PSProjectGitStatus','Get-PSProjectReport','Get-PSProjectTask','New-PSProjectTask', + 'Remove-PSProjectTask' AliasesToExport = 'gpstat', 'npstat', 'spstat', 'gitstat' PrivateData = @{ PSData = @{ @@ -23,7 +24,7 @@ # IconUri = '' ReleaseNotes = 'https://github.com/jdhitsolutions/PSProjectStatus/blob/main/changelog.md' RequireLicenseAcceptance = $false - } # End of PSData hashtable - } # End of PrivateData hashtable + } + } } diff --git a/PSProjectStatus.psm1 b/PSProjectStatus.psm1 index bd24219..cbee03a 100644 --- a/PSProjectStatus.psm1 +++ b/PSProjectStatus.psm1 @@ -50,7 +50,7 @@ Class PSProject { [Version]$ProjectVersion = (Test-ModuleManifest ".\$(Split-Path $pwd -Leaf).psd1" -ErrorAction SilentlyContinue).version [string]$GitBranch = '' #using .NET classes to ensure compatibility with non-Windows platforms - [string]$UpdateUser = "$([system.environment]::UserDomainName)\$([System.Environment]::Username)" + [string]$UpdateUser = "$([System.Environment]::UserDomainName)\$([System.Environment]::Username)" [string]$Computername = [System.Environment]::MachineName [PSProjectRemote[]]$RemoteRepository = @() [string]$Comment = 'none' @@ -71,7 +71,7 @@ Class PSProject { $this.ProjectVersion = (Test-ModuleManifest ".\$(Split-Path $pwd -Leaf).psd1" -ErrorAction SilentlyContinue).version } [void]RefreshUser() { - $this.UpdateUser = "$([system.environment]::UserDomainName)\$([System.Environment]::Username)" + $this.UpdateUser = "$([System.Environment]::UserDomainName)\$([System.Environment]::Username)" } [void]RefreshComputer() { $this.Computername = [System.Environment]::MachineName @@ -86,7 +86,7 @@ Class PSProject { $RemoteName = $split[0] $Url = $split[1] $Mode = $split[2].replace('(', '').Replace(')', '') - $repos += [PSProjectRemote]::new($remotename, $url, $mode) + $repos += [PSProjectRemote]::new($RemoteName, $url, $mode) } #foreach $this.RemoteRepository = $repos } #if remotes found @@ -102,6 +102,34 @@ Class PSProject { } } +<# +Consider expanding the schema to add a structured task object, +with commands to add, set, complete, and remove. +This would be a major breaking change + +[DateTime]$Created +[DateTime]$DueDate +[String]$AssignedTo +[Int32]$Progress +[Boolean]$Completed + +#> + +Class PSProjectTask { + [string]$ProjectName + [string]$Path + [string]$TaskDescription + [version]$ProjectVersion + [int]$TaskID + + PSProjectTask ($TaskDescription, $Path, $ProjectName, $ProjectVersion) { + $this.ProjectName = $ProjectName + $this.Path = $Path + $this.TaskDescription = $TaskDescription + $this.ProjectVersion = $ProjectVersion + } +} + #endregion #region add a VSCode/PowerShell ISE extension to the project @@ -151,7 +179,7 @@ if ($host.name -eq 'visual studio code host') { 8 { $status = 'UnitTesting' } 9 { $status = 'AcceptanceTesting' } 10 { $status = 'Other' } - 11 {$status = 'Archive'} + 11 { $status = 'Archive' } } if ($status) { @@ -214,7 +242,7 @@ if ($host.name -match 'ISE') { 8 { $status = 'UnitTesting' } 9 { $status = 'AcceptanceTesting' } 10 { $status = 'Other' } - 11 { $status = 'Archive'} + 11 { $status = 'Archive' } } if ($status) { diff --git a/README.md b/README.md index 8a0afbd..624d4f8 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![PSGallery Version](https://img.shields.io/powershellgallery/v/PSProjectStatus.png?style=for-the-badge&label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/PSProjectStatus/) [![PSGallery Downloads](https://img.shields.io/powershellgallery/dt/PSProjectStatus.png?style=for-the-badge&label=Downloads)](https://www.powershellgallery.com/packages/PSProjectStatus/) -This PowerShell module is designed to make it easier to manage your projects and modules. It provides a snapshot overview of the project's status. You can use this to quickly determine when you last worked on a module and what high-level tasks remain. Status information is stored in a JSON file that resides in the module's root directory. If you have initialized *git* for the module, the status will include the current branch. +This PowerShell module is designed to make it easier to manage your projects and modules. It provides a snapshot overview of the project's status. You can use this to quickly determine when you last worked on a module and what high-level tasks remain. Status information is stored in a JSON file that resides in the module's root directory. If you have initialized *git* for the module, the project status will include the current branch. ## Installation @@ -12,11 +12,12 @@ Install this module from the PowerShell Gallery. Install-Module PSProjectStatus ``` -This module should work in Windows PowerShell and PowerShell 7. +This module should work in Windows PowerShell 5.1 and PowerShell 7. ## Class-Based -The status is based on a private class-based definition. The classes are used to construct the JSON file which in turn is used to create a `PSProject` object and update its properties. +The project status is based on a private class-based definition. The PowerShell classes are used to construct the JSON file which in turn is used to create a `PSProject` object and update its properties. + ```powershell Class PSProjectRemote { @@ -29,7 +30,7 @@ Class PSProjectRemote { $this.url = $url $this.mode = $mode } - #allow an empty remote setting + #allow an empty remote setting PSProjectRemote() { $this.Name = '' $this.url = '' @@ -45,7 +46,7 @@ Class PSProject { [Version]$ProjectVersion = (Test-ModuleManifest ".\$(Split-Path $pwd -Leaf).psd1" -ErrorAction SilentlyContinue).version [string]$GitBranch = '' #using .NET classes to ensure compatibility with non-Windows platforms - [string]$UpdateUser = "$([system.environment]::UserDomainName)\$([System.Environment]::Username)" + [string]$UpdateUser = "$([System.Environment]::UserDomainName)\$([System.Environment]::Username)" [string]$Computername = [System.Environment]::MachineName [PSProjectRemote[]]$RemoteRepository = @() [string]$Comment = 'none' @@ -66,7 +67,7 @@ Class PSProject { $this.ProjectVersion = (Test-ModuleManifest ".\$(Split-Path $pwd -Leaf).psd1" -ErrorAction SilentlyContinue).version } [void]RefreshUser() { - $this.UpdateUser = "$([system.environment]::UserDomainName)\$([System.Environment]::Username)" + $this.UpdateUser = "$([System.Environment]::UserDomainName)\$([System.Environment]::Username)" } [void]RefreshComputer() { $this.Computername = [System.Environment]::MachineName @@ -81,7 +82,7 @@ Class PSProject { $RemoteName = $split[0] $Url = $split[1] $Mode = $split[2].replace('(', '').Replace(')', '') - $repos += [PSProjectRemote]::new($remotename, $url, $mode) + $repos += [PSProjectRemote]::new($RemoteName, $url, $mode) } #foreach $this.RemoteRepository = $repos } #if remotes found @@ -95,8 +96,7 @@ Class PSProject { $this.RefreshRemoteRepository() $this.Save() } -} -``` +}``` The class includes a status enumeration. @@ -115,9 +115,9 @@ enum PSProjectStatus { } ``` -At this time it is not possible to include a user-defined status. It is hoped that you can find something appropriate from the current status list. +At this time it is not possible to include a user-defined project status. It is hoped that you can find something appropriate from the current status list. -The `Age` ScriptProperty and `VersionInfo` property set are added to the object as type extensions. +The `Age` ScriptProperty and `VersionInfo` property sets are added to the object as type extensions. ```xml @@ -163,7 +163,7 @@ To create a project status file, navigate to the module root and run [New-PSProj You can update properties when you create the project status. ```powershell -New-PSProjectStatus -LastUpdate (Get-Item .\*.psd1).lastwritetime -Status Updating -tasks "update help" +New-PSProjectStatus -LastUpdate (Get-Item .\*.psd1).LastWriteTime -Status Updating -tasks "update help" ``` ![new custom project status](images/new-psprojectstatus2.png) @@ -188,7 +188,7 @@ The command will create `psproject.json` in the root folder. } ``` -Note that the update time is formatted as a UTC string. The Project version will be pulled from the module manifest if found. You can set this to a different value manually in the JSON file or by running `Set-PSProjectStatus`. +Note that the update time is formatted as a UTC string. The project version will be pulled from the module manifest if found. You can set this to a different value manually in the JSON file or by running `Set-PSProjectStatus`. > If you are using *git* with your module you may want to add `psproject.json` to your `.gitignore` file. @@ -196,7 +196,7 @@ Note that the update time is formatted as a UTC string. The Project version will The easiest way to view a project status is by using [Get-PSProjectStatus](docs/New-PSProjectStatus.md). -```dos +```powershell PS C:\scripts\PSCalendar> Get-PSProjectStatus @@ -207,11 +207,11 @@ LastUpdate Status Tasks GitBranch 3/3/2022 10:24:49 AM Patching {Update help docu... 2.9.0 12.07:07 ``` -If the host supports ANSI, a status of `Stable` will be displayed in Green. `Development` will be shown in Red and `Updating` in Yellow. +If the PowerShell host supports ANSI, a status of `Stable` will be displayed in Green. `Development` will be shown in Red and `Updating` in Yellow. The module has a default list view. -```dos +```powershell PS C:\scripts\PSCalendar> Get-PSProjectStatus | Format-List @@ -254,7 +254,7 @@ Archive = 10 Or use the [Set-PSProjectStatus](docs/Set-PSProjectStatus.md) function. -```dos +```powershell PS C:\scripts\PSHelpDesk> Set-PSProjectStatus -LastUpdate (Get-Date) -Status Development -Tasks "add printer status function","revise user password function" -Concatenate @@ -277,7 +277,7 @@ The commands in this module assume you are most likely using `git` for source co The PSProject class has been updated since the first version of this module was released. You can use the object's methods to refresh some properties. Here is an example of an incomplete status. -```dos +```powershell PS C:\Scripts\WingetTools> Get-PSProjectStatus | Select-Object * Name : WingetTools @@ -317,6 +317,36 @@ $p.save() ![refresh a project status]As an alternative can use the `RefreshAll()` method which will invoke all the refresh methods __and__ save the file. +## Project Tasks + +This module is intended to be a _simple_ project management tool. You can use it to track tasks or to-do items. These are added to the `Tasks` property as an array of strings. You can manually add them to the JSON file or use the `Set-PSProjectStatus` function. + +```powershell +C:\Scripts\PSProjectStatus> Set-PSProjectStatus -Tasks "Update missing online help links" -Concatenate + + Name: PSProjectStatus [C:\Scripts\PSProjectStatus] + +LastUpdate Status Tasks GitBranch Age +---------- ------ ----- --------- --- +12/22/2023 9:08:30 AM Updating {Consider a schema … 0.11.0 00.00:00 +``` + +Or you can use the task-related commands. + +![Get-PSProjectTask](images/get-psprojecttask.png) + +If the PowerShell host supports it, you should get ANSI formatting. The task ID is automatically generated for each item and displayed in square brackets. + +You can also add a task. + +![New-PSProjectTask](images/new-psprojecttask.png) + +You can manually remove items from the JSON file or use the `Remove-PSProjectTask` function. You will need to know the task id. + +```powershell +Remove-PSProjectTask -TaskID 4 +``` + ## Project Management If you have many projects, you can use this module to manage all of them. @@ -327,7 +357,7 @@ Get-ChildItem -Path c:\scripts -Directory | Get-PSProjectStatus -WarningAction S ![list projects](images/list-projects.png) -You will want to suppress Warning messages. If you are running PowerShell 7 and have the ConsoleGuiTools module installed, you can run a script like this: +You will want to suppress Warning messages. If you are running PowerShell 7 and have the `Microsoft.PowerShell.ConsoleGuiTools` module installed, you can run a script like this: ```powershell #requires -version 7.2 @@ -340,7 +370,8 @@ Import-Module PSProjectStatus -Force $all = Get-ChildItem -Path C:\scripts -Directory | Get-PSProjectStatus -WarningAction SilentlyContinue $all | Sort-Object Status, LastUpdate | -Select-Object Path, Status, @{Name = "Tasks"; Expression = { $_.Tasks -join ',' } }, +Select-Object Path, Status, +@{Name = "Tasks"; Expression = { $_.Tasks -join ',' } }, GitBranch, LastUpdate | Out-ConsoleGridView -Title "PSProject Management" -OutputMode Single | ForEach-Object { code $_.path } @@ -356,7 +387,7 @@ You can select a single project, press Enter, and open the folder in VS Code. Yo Beginning with version `0.10.0` you can use `Get-PSProjectReport` to simplify project management. -You can get all projects. +You can get all of your projects. ```powershell Get-PSProjectReport c:\scripts @@ -389,11 +420,11 @@ LastUpdate Status Tasks GitBranch Age ## Removing Project Status -If no you longer want to track the project status for a given folder, all you have to do is delete the associated JSON file. As an alternative, you may want to set a status of `Archive`. +If no you longer want to track the project status for a given folder, simply delete the associated JSON file. As an alternative, you can set the status to `Archive`. -## Editor Integrations +## Editor Integration -If you import this module into your PowerShell editor, either Visual Studio Code or the PowerShell ISE, the module will add an update function called `Update-PSProjectStatus`. You can run the command from the integrated terminal or use the appropriate shortcut. The command will the status based on user input, update the `LastUpdate` time to the current date and time, update the project version from the module manifest (if found), and update the git branch if found. +If you import this module into your PowerShell editor, either Visual Studio Code or the PowerShell ISE, the module will add an update function called `Update-PSProjectStatus`. You can run the command from the integrated terminal or use the appropriate shortcut (see below). The command will the status based on user input, update the `LastUpdate` time to the current date and time, update the project version from the module manifest (if found), and update the git branch if found. You need to make sure your terminal or console window is set to your project's root directory. @@ -423,7 +454,7 @@ The menu will loop and display until you enter a valid number or press Enter wit ### JSON Schema -A public JSON [schema file](https://raw.githubusercontent.com/jdhitsolutions/PSProjectStatus/main/psproject.schema.json) was published with v0.8.0. If you edit the `psproject.json` file in VSCode, you should get tab completion for many of the settings. If you have a configuration file created with an earlier version of the module, run `Set-PSProjectStatus` with any parameter. This will insert the schema reference into the JSON file. Then you can edit the file in VSCode. +A public JSON [schema file](https://raw.githubusercontent.com/jdhitsolutions/PSProjectStatus/main/psproject.schema.json) was published with `v0.8.0`. If you edit the `psproject.json` file in VSCode, you should get tab completion for many of the settings. If you have a configuration file created with an earlier version of the module, run `Set-PSProjectStatus` with any parameter. This will insert the schema reference into the JSON file. Then you can edit the file in VSCode. ## Road Map @@ -433,8 +464,8 @@ These are a few things I'm considering or have been suggested. + priority + project type + tags -+ Extend the module to integrate into a SQLite database file. ++ Extend the module to integrate into a SQLite database file. Although I would want this to work cross-platform. + Editor integration to manage project tasks. -+ A WPF form to display the project status and make it easier to edit tasks. ++ A WPF or TUI form to display the project status and make it easier to edit tasks. If you have any suggestions on how to extend this module or tips to others on how you are using it, please feel free to use the [Discussions](https://github.com/jdhitsolutions/PSProjectStatus/discussions) section of this module's GitHub repository. diff --git a/changelog.md b/changelog.md index 701fa6d..dfc5eaa 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,25 @@ # Changelog for PSProjectStatus +## v0.11.0 + +### Fixed + +- Removed hard-coded path reference in `Get-PSProjectReport`. ([Issue #9](https://github.com/jdhitsolutions/PSProjectStatus/issues/9)) + +### Changed + +- Updated `README.md`. +- Updated `Set-PSProjectStatus` to use the current date time as the default for the `LastUpdate` parameter. __This is a potential breaking change.__ +- Updated `New-PSProjectStatus`to not overwrite an existing file if found. Added a `-Force` parameter. +- Updated Verbose output in all commands. +- Help updates + +### Added + +- Added command `Get-PSProjectTask` which is based on a new class definition. +- Added custom format file `psprojecttask.format.ps1xml` +- Added commands `New-PSProjectTask` and `Remove-PSProjectTask`. + ## v0.10.1 ### Fixed @@ -95,7 +115,7 @@ - Update `README.md` - Updated private data in the module manifest. - Added parameter alias `add` to `Concatenate` in `Set-PSProjectStatus`. -- Added parameter alias `fullname` to `Path` in `Get-PSProjectStatus`. +- Added parameter alias `FullName` to `Path` in `Get-PSProjectStatus`. ## v0.2.0 diff --git a/docs/Get-PSProjectStatus.md b/docs/Get-PSProjectStatus.md index 1e9c678..e62f17c 100644 --- a/docs/Get-PSProjectStatus.md +++ b/docs/Get-PSProjectStatus.md @@ -13,7 +13,7 @@ Get project status. ## SYNTAX -```yaml +``` Get-PSProjectStatus [[-Path] ] [] ``` @@ -83,7 +83,7 @@ Use the default List view. This makes it easier to view the tasks. ### Example 4 ```powershell -PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object versioninfo,age +PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object VersionInfo,age Name : PSProjectStatus Status : Updating @@ -115,7 +115,6 @@ Accept wildcard characters: False ``` ### CommonParameters - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/docs/Get-PSProjectTask.md b/docs/Get-PSProjectTask.md new file mode 100644 index 0000000..cf4742c --- /dev/null +++ b/docs/Get-PSProjectTask.md @@ -0,0 +1,103 @@ +--- +external help file: PSProjectStatus-help.xml +Module Name: PSProjectStatus +online version: +schema: 2.0.0 +--- + +# Get-PSProjectTask + +## SYNOPSIS + +List project tasks + +## SYNTAX + +``` +Get-PSProjectTask [[-Path] ] [-TaskID ] [] +``` + +## DESCRIPTION + +List defined tasks in the PSProject file. You will get a warning if no tasks are defined. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\PSWorkItem> Get-PSProjectTask + + Name: PSWorkItem [C:\PSWorkItem] + + Show overdue value in table in red [1] + Pester tests [2] + Show tooltip help in TUI [3] + Add option in TUI to filter table by days [4] +``` + +Display tasks. If you run this in the console of VSCode, you should get ANSI formatted output. The number in brackets is the TaskID. + +### Example 2 + +```powershell +PS C:\PSWorkItem> Get-PSProjectTask -TaskID 2 + + Name: PSWorkItem [C:\PSWorkItem] + + Pester tests [2] +``` + +Get a task by ID number. + +## PARAMETERS + +### -Path +Enter the parent path to the psproject.json file, e.g. +c:\scripts\mymodule. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: FullName + +Required: False +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -TaskID +Get a task by its ID number + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: ID + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### psProjectTask + +## NOTES + +## RELATED LINKS + +[New-PSProjectTask](New-PSProjectTask.md) + +[Remove-PSProjectTask](Remove-PSProjectTask.md) diff --git a/docs/New-PSProjectStatus.md b/docs/New-PSProjectStatus.md index 7316e03..d6c97de 100644 --- a/docs/New-PSProjectStatus.md +++ b/docs/New-PSProjectStatus.md @@ -13,26 +13,45 @@ Create a new PSProjectStatus. ## SYNTAX -```yaml -New-PSProjectStatus [[-Name] ] [-Path ] [-LastUpdate ] [-Tasks ] [-Status ] [-ProjectVersion ] [-Comment ] [-WhatIf] [-Confirm] [] +``` +New-PSProjectStatus [[-Name] ] [-Path ] +[-LastUpdate ] [-Tasks ] [-Status ] +[-ProjectVersion ] [-Comment ] [-Force] [-WhatIf] [-Confirm] +[] ``` ## DESCRIPTION Create a new PSProject file. Ideally, you will run this command in the module root directory. The module manifest, if found, will be used for the Project Version. If a git branch is detected, it will automatically be used. +The command will not overwrite an existing PSProjectStatus file. If you want to overwrite an existing file, use the -Force parameter. + ## EXAMPLES ### Example 1 ```powershell -PS C:\Scripts\PSScriptingInventory> New-PSProjectStatus -LastUpdate (Get-Item .\PSScriptingInventory.psd1).lastwritetime -Status Stable -Comment "Script module" +PS C:\Projects\Contoso> New-PSProjectStatus + + Name: Contoso [C:\Projects\Contoso] + +LastUpdate Status Tasks GitBranch Age +---------- ------ ----- --------- --- +12/22/2023 8:35:55 AM Development {} main 00.00:00 +``` + +Create a new project status using default values. + +### Example 2 + +```powershell +PS C:\Scripts\PSScriptingInventory> New-PSProjectStatus -LastUpdate (Get-Item .\PSScriptingInventory.psd1).LastWriteTime -Status Stable -Comment "Script module" Name: PSScriptingInventory [C:\scripts\PSScriptingInventory] -LastUpdate Status Tasks GitBranch Age ----------- ------ ----- --------- --- -6/19/2020 8:42:04 AM Stable main 634.01:13 +LastUpdate Status Tasks GitBranch Age +---------- ------ ----- --------- --- +6/19/2020 8:42:04 AM Stable {} main 634.01:13 ``` Create a new project status. PSDrive references will be converted to filesystem paths. The Age property is automatically calculated from the LastUpdate value. @@ -185,8 +204,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### CommonParameters +### -Force +Overwrite an existing PSProjectStatus file. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/docs/New-PSProjectTask.md b/docs/New-PSProjectTask.md new file mode 100644 index 0000000..e4683e3 --- /dev/null +++ b/docs/New-PSProjectTask.md @@ -0,0 +1,160 @@ +--- +external help file: PSProjectStatus-help.xml +Module Name: PSProjectStatus +online version: +schema: 2.0.0 +--- + +# New-PSProjectTask + +## SYNOPSIS + +Create a new task in the PSProject file. + +## SYNTAX + +```yaml +New-PSProjectTask [-TaskDescription] [-Path ] [-PassThru] [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +You can add tasks directly in the PSProject file, or you can use this function. Specify a task description and it will be added to the PSProject file. The task ID is assigned automatically. + +You can also use Set-PSProjectTask set tasks. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\Scripts\PSProjectStatus> New-PSProjectTask -TaskDescription "Update README" +``` + +Add a new task. + +### Example 2 + +```powershell +C:\Scripts\PSProjectStatus> New-PSProjectTask -TaskDescription "Pester tests" -PassThru + + Name: PSProjectStatus [C:\Scripts\PSProjectStatus] + + Pester tests [7] +``` + +## PARAMETERS + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru + +Display the new task. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Enter the parent path to the psproject.json file, e.g. +c:\scripts\mymodule. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: FullName + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TaskDescription +Enter the task description. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### None + +### psProjectTask + +## NOTES + +## RELATED LINKS + +[Get-PSProjectTask](Get-PSProjectTask.md) + +[Remove-PSProjectTask](Remove-PSProjectTask.md) diff --git a/docs/Remove-PSProjectTask.md b/docs/Remove-PSProjectTask.md new file mode 100644 index 0000000..2862487 --- /dev/null +++ b/docs/Remove-PSProjectTask.md @@ -0,0 +1,115 @@ +--- +external help file: PSProjectStatus-help.xml +Module Name: PSProjectStatus +online version: +schema: 2.0.0 +--- + +# Remove-PSProjectTask + +## SYNOPSIS + +Remove a task from the PSProject file. + +## SYNTAX + +``` +Remove-PSProjectTask [-TaskID] [-Path ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +You can manually remove tasks from the PSProject file, or you can use this function. Specify a task ID and it will be removed from the PSProject file. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\scripts\PSProjectStatus> Remove-PSProjectTask -TaskID 4,2 +``` + +Remove tasks 4 and 2 from the PSProject file. + +## PARAMETERS + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Enter the parent path to the psproject.json file, e.g. +c:\scripts\mymodule. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: FullName + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TaskID +Enter the task ID + +```yaml +Type: Int32[] +Parameter Sets: (All) +Aliases: ID + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### [Int] + +## OUTPUTS + +### None + +## NOTES + +## RELATED LINKS + +[New-PSProjectTask](New-PSProjectTask.md) + +[Get-PSProjectTask](Get-PSProjectTask.md) \ No newline at end of file diff --git a/docs/Set-PSProjectStatus.md b/docs/Set-PSProjectStatus.md index 8c15137..a43fbb0 100644 --- a/docs/Set-PSProjectStatus.md +++ b/docs/Set-PSProjectStatus.md @@ -27,16 +27,16 @@ Manually copy the value into the JSON file. The Status value is an integer indicating a private enumeration value. -Development = 0 -Updating = 1 -Stable = 2 -AlphaTesting = 3 -BetaTesting = 4 -ReleaseCandidate = 5 -Patching = 6 -UnitTesting = 7 -AcceptanceTesting = 8 -Other = 9 +- Development = 0 +- Updating = 1 +- Stable = 2 +- AlphaTesting = 3 +- BetaTesting = 4 +- ReleaseCandidate = 5 +- Patching = 6 +- UnitTesting = 7 +- AcceptanceTesting = 8 +- Other = 9 Enter one of these string values. If you edit the file in VSCode, it should detect the JSON schema and provide completion values. @@ -45,13 +45,13 @@ Enter one of these string values. If you edit the file in VSCode, it should dete ### Example 1 ```powershell -PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -LastUpdate (Get-Date) -Status Development -comment (git tag -l | Select-Object -last 1) +PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -Status Development -comment (git tag -l | Select-Object -last 1) Name: PSProjectStatus [C:\scripts\PSProjectStatus] LastUpdate Status Tasks GitBranch Age ---------- ------ ----- --------- --- -3/15/2022 10:09:05 AM Develo.. {help docs, readm… 0.2.0 00.00:00 +3/15/2023 10:09:05 AM Develo.. {help docs, readm… 0.2.0 00.00:00 ``` Update the project status using the current date and time. Set the Status property to Development and use the last git tag as a comment. @@ -59,7 +59,7 @@ Update the project status using the current date and time. Set the Status proper ### Example 2 ```powershell -PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -LastUpdate (Get-Date) -Status Development -Tasks "github" -Concatenate | Format-List +PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -Status Development -Tasks "github" -Concatenate | Format-List Project: PSProjectStatus [C:\scripts\PSProjectStatus] @@ -67,7 +67,7 @@ Version : 0.5.0 Status : Updating Tasks : {help docs, readme, pester tests, resolve project path for json…} GitBranch : 0.5.0 -LastUpdate : 3/23/2022 10:20:26 AM +LastUpdate : 3/23/2023 10:20:26 AM ``` Update the project and add a task. @@ -133,7 +133,7 @@ Aliases: date Required: False Position: 2 -Default value: None +Default value: current date and time Accept pipeline input: False Accept wildcard characters: False ``` @@ -237,7 +237,6 @@ Accept wildcard characters: False ``` ### CommonParameters - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -259,3 +258,5 @@ Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell [New-PSProjectStatus](New-PSProjectStatus.md) [Get-PSProjectStatus](Get-PSProjectStatus.md) + +[New-PSProjectTask](New-PSProjectTask.md) diff --git a/docs/Update-PSProjectStatus.md b/docs/Update-PSProjectStatus.md new file mode 100644 index 0000000..57b78f5 --- /dev/null +++ b/docs/Update-PSProjectStatus.md @@ -0,0 +1,75 @@ +--- +external help file: PSProjectStatus-help.xml +Module Name: PSProjectStatus +online version: +schema: 2.0.0 +--- + +# Update-PSProjectStatus + +## SYNOPSIS +{{ Fill in the Synopsis }} + +## SYNTAX + +``` +Update-PSProjectStatus [[-context] ] [-ProgressAction ] [] +``` + +## DESCRIPTION +{{ Fill in the Description }} + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> {{ Add example code here }} +``` + +{{ Add example description here }} + +## PARAMETERS + +### -context +{{ Fill context Description }} + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object +## NOTES + +## RELATED LINKS diff --git a/en-us/PSProjectStatus-help.xml b/en-us/PSProjectStatus-help.xml index c804d9e..7c13b6f 100644 --- a/en-us/PSProjectStatus-help.xml +++ b/en-us/PSProjectStatus-help.xml @@ -435,7 +435,7 @@ LastUpdate : 3/3/2022 10:24:49 AM -------------------------- Example 4 -------------------------- - PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object versioninfo,age + PS C:\Scripts\PSProjectStatus> Get-PSProjectStatus | Select-Object VersionInfo,age Name : PSProjectStatus Status : Updating @@ -463,6 +463,136 @@ Age : 00:06:06.2337458 + + + Get-PSProjectTask + Get + PSProjectTask + + List project tasks + + + + List defined tasks in the PSProject file. You will get a warning if no tasks are defined. + + + + Get-PSProjectTask + + Path + + Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule. + + String + + String + + + None + + + TaskID + + Get a task by its ID number + + Int32 + + Int32 + + + None + + + + + + Path + + Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule. + + String + + String + + + None + + + TaskID + + Get a task by its ID number + + Int32 + + Int32 + + + None + + + + + + System.String + + + + + + + + + + psProjectTask + + + + + + + + + + + + + + -------------------------- Example 1 -------------------------- + PS C:\PSWorkItem> Get-PSProjectTask + + Name: PSWorkItem [C:\PSWorkItem] + + Show overdue value in table in red [1] + Pester tests [2] + Show tooltip help in TUI [3] + Add option in TUI to filter table by days [4] + + Display tasks. If you run this in the console of VSCode, you should get ANSI formatted output. The number in brackets is the TaskID. + + + + -------------------------- Example 2 -------------------------- + PS C:\PSWorkItem> Get-PSProjectTask -TaskID 2 + + Name: PSWorkItem [C:\PSWorkItem] + + Pester tests [2] + + Get a task by ID number. + + + + + + New-PSProjectTask + + + + Remove-PSProjectTask + + + + New-PSProjectStatus @@ -474,21 +604,588 @@ Age : 00:06:06.2337458 Create a new PSProject file. Ideally, you will run this command in the module root directory. The module manifest, if found, will be used for the Project Version. If a git branch is detected, it will automatically be used. + The command will not overwrite an existing PSProjectStatus file. If you want to overwrite an existing file, use the -Force parameter. + + + + New-PSProjectStatus + + Name + + What is the project name? The default is the current folder name. + + String + + String + + + current folder name + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + LastUpdate + + When was the project last worked on? + + DateTime + + DateTime + + + None + + + Path + + What is the project path? + + String + + String + + + . + + + Status + + What is the project status? Accepted values are Development, Updating, Stable, AlphaTesting, BetaTesting, ReleaseCandidate, Patching, UnitTesting, AcceptanceTesting, and Other. + + + Development + Updating + Stable + AlphaTesting + BetaTesting + ReleaseCandidate + Patching + UnitTesting + AcceptanceTesting + Other + + PSProjectStatus + + PSProjectStatus + + + None + + + Tasks + + What are the remaining tasks? + + String[] + + String[] + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + ProjectVersion + + What is the project version? The default value will be detected from a module manifest if found. + + Version + + Version + + + module version + + + Comment + + Enter an optional comment. This could be git tag, or an indication about the type of project. + + String + + String + + + None + + + Force + + Overwrite an existing PSProjectStatus file. + + + SwitchParameter + + + False + + + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + LastUpdate + + When was the project last worked on? + + DateTime + + DateTime + + + None + + + Name + + What is the project name? The default is the current folder name. + + String + + String + + + current folder name + + + Path + + What is the project path? + + String + + String + + + . + + + Status + + What is the project status? Accepted values are Development, Updating, Stable, AlphaTesting, BetaTesting, ReleaseCandidate, Patching, UnitTesting, AcceptanceTesting, and Other. + + PSProjectStatus + + PSProjectStatus + + + None + + + Tasks + + What are the remaining tasks? + + String[] + + String[] + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + ProjectVersion + + What is the project version? The default value will be detected from a module manifest if found. + + Version + + Version + + + module version + + + Comment + + Enter an optional comment. This could be git tag, or an indication about the type of project. + + String + + String + + + None + + + Force + + Overwrite an existing PSProjectStatus file. + + SwitchParameter + + SwitchParameter + + + False + + + + + + None + + + + + + + + + + PSProject + + + + + + + + + This command has an alias of npstat. + Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ + + + + + -------------------------- Example 1 -------------------------- + PS C:\Projects\Contoso> New-PSProjectStatus + + Name: Contoso [C:\Projects\Contoso] + +LastUpdate Status Tasks GitBranch Age +---------- ------ ----- --------- --- +12/22/2023 8:35:55 AM Development {} main 00.00:00 + + Create a new project status using default values. + + + + -------------------------- Example 2 -------------------------- + PS C:\Scripts\PSScriptingInventory> New-PSProjectStatus -LastUpdate (Get-Item .\PSScriptingInventory.psd1).LastWriteTime -Status Stable -Comment "Script module" + + Name: PSScriptingInventory [C:\scripts\PSScriptingInventory] + +LastUpdate Status Tasks GitBranch Age +---------- ------ ----- --------- --- +6/19/2020 8:42:04 AM Stable {} main 634.01:13 + + Create a new project status. PSDrive references will be converted to filesystem paths. The Age property is automatically calculated from the LastUpdate value. + + + + + + Online Version: + https://bit.ly/3MXO7Ho + + + Get-PSProjectStatus + + + + Set-PSProjectStatus + + + + Get-PSProjectReport + + + + + + + New-PSProjectTask + New + PSProjectTask + + Create a new task in the PSProject file. + + + + You can add tasks directly in the PSProject file, or you can use this function. Specify a task description and it will be added to the PSProject file. The task ID is assigned automatically. + You can also use Set-PSProjectTask set tasks. + + + + New-PSProjectTask + + TaskDescription + + Enter the task description. + + String + + String + + + None + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + PassThru + + Display the new task. + + + SwitchParameter + + + False + + + Path + + Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule. + + String + + String + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + ProgressAction + + {{ Fill ProgressAction Description }} + + ActionPreference + + ActionPreference + + + None + + + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + PassThru + + Display the new task. + + SwitchParameter + + SwitchParameter + + + False + + + Path + + Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule. + + String + + String + + + None + + + TaskDescription + + Enter the task description. + + String + + String + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + ProgressAction + + {{ Fill ProgressAction Description }} + + ActionPreference + + ActionPreference + + + None + + + + + + System.String + + + + + + + + + + None + + + + + + + + psProjectTask + + + + + + + + + + + + + + -------------------------- Example 1 -------------------------- + PS C:\Scripts\PSProjectStatus> New-PSProjectTask -TaskDescription "Update README" + + Add a new task. + + + + -------------------------- Example 2 -------------------------- + C:\Scripts\PSProjectStatus> New-PSProjectTask -TaskDescription "Pester tests" -PassThru + + Name: PSProjectStatus [C:\Scripts\PSProjectStatus] + + Pester tests [7] + + + + + + + + Get-PSProjectTask + + + + Remove-PSProjectTask + + + + + + + Remove-PSProjectTask + Remove + PSProjectTask + + Remove a task from the PSProject file. + + + + You can manually remove tasks from the PSProject file, or you can use this function. Specify a task ID and it will be removed from the PSProject file. - New-PSProjectStatus - - Name + Remove-PSProjectTask + + TaskID - What is the project name? The default is the current folder name. + Enter the task ID - String + Int32[] - String + Int32[] - current folder name + None Confirm @@ -501,64 +1198,16 @@ Age : 00:06:06.2337458 False - - LastUpdate - - When was the project last worked on? - - DateTime - - DateTime - - - None - - + Path - What is the project path? + Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule. String String - . - - - Status - - What is the project status? Accepted values are Development, Updating, Stable, AlphaTesting, BetaTesting, ReleaseCandidate, Patching, UnitTesting, AcceptanceTesting, and Other. - - - Development - Updating - Stable - AlphaTesting - BetaTesting - ReleaseCandidate - Patching - UnitTesting - AcceptanceTesting - Other - - PSProjectStatus - - PSProjectStatus - - - None - - - Tasks - - What are the remaining tasks? - - String[] - - String[] - - None @@ -572,30 +1221,6 @@ Age : 00:06:06.2337458 False - - ProjectVersion - - What is the project version? The default value will be detected from a module manifest if found. - - Version - - Version - - - module version - - - Comment - - Enter an optional comment. This could be git tag, or an indication about the type of project. - - String - - String - - - None - @@ -611,62 +1236,26 @@ Age : 00:06:06.2337458 False - - LastUpdate - - When was the project last worked on? - - DateTime - - DateTime - - - None - - - Name - - What is the project name? The default is the current folder name. - - String - - String - - - current folder name - - + Path - What is the project path? + Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule. String String - . - - - Status - - What is the project status? Accepted values are Development, Updating, Stable, AlphaTesting, BetaTesting, ReleaseCandidate, Patching, UnitTesting, AcceptanceTesting, and Other. - - PSProjectStatus - - PSProjectStatus - - None - - Tasks + + TaskID - What are the remaining tasks? + Enter the task ID - String[] + Int32[] - String[] + Int32[] None @@ -683,35 +1272,11 @@ Age : 00:06:06.2337458 False - - ProjectVersion - - What is the project version? The default value will be detected from a module manifest if found. - - Version - - Version - - - module version - - - Comment - - Enter an optional comment. This could be git tag, or an indication about the type of project. - - String - - String - - - None - - None + [Int] @@ -721,7 +1286,7 @@ Age : 00:06:06.2337458 - PSProject + None @@ -730,40 +1295,25 @@ Age : 00:06:06.2337458 - This command has an alias of npstat. - Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ + -------------------------- Example 1 -------------------------- - PS C:\Scripts\PSScriptingInventory> New-PSProjectStatus -LastUpdate (Get-Item .\PSScriptingInventory.psd1).lastwritetime -Status Stable -Comment "Script module" - - Name: PSScriptingInventory [C:\scripts\PSScriptingInventory] - -LastUpdate Status Tasks GitBranch Age ----------- ------ ----- --------- --- -6/19/2020 8:42:04 AM Stable main 634.01:13 + PS C:\scripts\PSProjectStatus> Remove-PSProjectTask -TaskID 4,2 - Create a new project status. PSDrive references will be converted to filesystem paths. The Age property is automatically calculated from the LastUpdate value. + Remove tasks 4 and 2 from the PSProject file. - Online Version: - https://bit.ly/3MXO7Ho - - - Get-PSProjectStatus - - - - Set-PSProjectStatus + New-PSProjectTask - Get-PSProjectReport + Get-PSProjectTask @@ -782,7 +1332,17 @@ LastUpdate Status Tasks GitBranch Age Get-Date -format o | Set-Clipboard Manually copy the value into the JSON file. The Status value is an integer indicating a private enumeration value. - Development = 0 Updating = 1 Stable = 2 AlphaTesting = 3 BetaTesting = 4 ReleaseCandidate = 5 Patching = 6 UnitTesting = 7 AcceptanceTesting = 8 Other = 9 + - Development = 0 + - Updating = 1 + - Stable = 2 + - AlphaTesting = 3 + - BetaTesting = 4 + - ReleaseCandidate = 5 + - Patching = 6 + - UnitTesting = 7 + - AcceptanceTesting = 8 + - Other = 9 + Enter one of these string values. If you edit the file in VSCode, it should detect the JSON schema and provide completion values. @@ -822,7 +1382,7 @@ LastUpdate Status Tasks GitBranch Age DateTime - None + current date and time Tasks @@ -966,7 +1526,7 @@ LastUpdate Status Tasks GitBranch Age DateTime - None + current date and time Name @@ -1070,20 +1630,20 @@ LastUpdate Status Tasks GitBranch Age -------------------------- Example 1 -------------------------- - PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -LastUpdate (Get-Date) -Status Development -comment (git tag -l | Select-Object -last 1) + PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -Status Development -comment (git tag -l | Select-Object -last 1) Name: PSProjectStatus [C:\scripts\PSProjectStatus] LastUpdate Status Tasks GitBranch Age ---------- ------ ----- --------- --- -3/15/2022 10:09:05 AM Develo.. {help docs, readm… 0.2.0 00.00:00 +3/15/2023 10:09:05 AM Develo.. {help docs, readm… 0.2.0 00.00:00 Update the project status using the current date and time. Set the Status property to Development and use the last git tag as a comment. -------------------------- Example 2 -------------------------- - PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -LastUpdate (Get-Date) -Status Development -Tasks "github" -Concatenate | Format-List + PS C:\Scripts\PSProjectStatus> Set-PSProjectStatus -Status Development -Tasks "github" -Concatenate | Format-List Project: PSProjectStatus [C:\scripts\PSProjectStatus] @@ -1091,7 +1651,7 @@ Version : 0.5.0 Status : Updating Tasks : {help docs, readme, pester tests, resolve project path for json…} GitBranch : 0.5.0 -LastUpdate : 3/23/2022 10:20:26 AM +LastUpdate : 3/23/2023 10:20:26 AM Update the project and add a task. @@ -1110,6 +1670,113 @@ LastUpdate : 3/23/2022 10:20:26 AM Get-PSProjectStatus + + New-PSProjectTask + + + + + Update-PSProjectStatus + Update + PSProjectStatus + + {{ Fill in the Synopsis }} + + + + {{ Fill in the Description }} + + + + Update-PSProjectStatus + + context + + {{ Fill context Description }} + + Object + + Object + + + None + + + ProgressAction + + {{ Fill ProgressAction Description }} + + ActionPreference + + ActionPreference + + + None + + + + + + context + + {{ Fill context Description }} + + Object + + Object + + + None + + + ProgressAction + + {{ Fill ProgressAction Description }} + + ActionPreference + + ActionPreference + + + None + + + + + + None + + + + + + + + + + System.Object + + + + + + + + + + + + + + -------------------------- Example 1 -------------------------- + PS C:\> {{ Add example code here }} + + {{ Add example description here }} + + + + + \ No newline at end of file diff --git a/formats/psprojectstatus.format.ps1xml b/formats/psprojectstatus.format.ps1xml index 1e70523..45b0b81 100644 --- a/formats/psprojectstatus.format.ps1xml +++ b/formats/psprojectstatus.format.ps1xml @@ -57,10 +57,10 @@ https://github.com/jdhitsolutions/PSScriptTools if ($host.name -match 'console|code') { - - if ($_.status -eq 'Development') { - - "$([char]27)[91m$($_.status)$([char]27)[0m" + + if ($_.status -eq 'Development') { + + "$([char]27)[91m$($_.status)$([char]27)[0m" } elseif ($_.status -eq 'Updating') { @@ -68,16 +68,16 @@ https://github.com/jdhitsolutions/PSScriptTools } elseif ($_.status -eq 'Stable') { - "$([char]27)[92m$($_.status)$([char]27)[0m" - } - elseif ($_.status -eq 'Archive') { + "$([char]27)[92m$($_.status)$([char]27)[0m" + } + elseif ($_.status -eq 'Archive') { - "$([char]27)[38;5;214m$($_.status)$([char]27)[0m" - } - else { - $_.status - } - } + "$([char]27)[38;5;214m$($_.status)$([char]27)[0m" + } + else { + $_.status + } + } else { $_.Status } diff --git a/formats/psprojecttask.format.ps1xml b/formats/psprojecttask.format.ps1xml new file mode 100644 index 0000000..26db3a3 --- /dev/null +++ b/formats/psprojecttask.format.ps1xml @@ -0,0 +1,52 @@ + + + + + + default + + PSProjectTask + + + "{0} [{1}]" -f $_.ProjectName,$_.path + + + + + + + + + + 59 + left + + + + + + + + if ($Host.Name -match "console|code") { + + " $([char]9679) $([char]27)[3m$($_.TaskDescription) [$($_.TaskID)]$([char]27)[0" + } + else { + "{0} [{1}]" -f $_.TaskDescription,$_.TaskID + } + + + + + + + + + \ No newline at end of file diff --git a/functions/public/Get-PSProjectGitStatus.ps1 b/functions/public/Get-PSProjectGitStatus.ps1 index 1ab622c..edac084 100644 --- a/functions/public/Get-PSProjectGitStatus.ps1 +++ b/functions/public/Get-PSProjectGitStatus.ps1 @@ -4,6 +4,10 @@ Function Get-PSProjectGitStatus { [OutputType('PSProjectGit')] Param( ) + Write-Verbose "[$((Get-Date).TimeOfDay)] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Using PowerShell Host $($Host.Name)" + if (Test-Path .git) { $remotes = _getRemote | Where-Object { $_.mode -eq 'push' } | @@ -21,4 +25,5 @@ Function Get-PSProjectGitStatus { else { Write-Verbose "You must run this command from the root of a git repository." } + Write-Verbose "[$((Get-Date).TimeOfDay)] Starting $($MyInvocation.MyCommand)" } diff --git a/functions/public/Get-PSProjectReport.ps1 b/functions/public/Get-PSProjectReport.ps1 index 28e1e63..d4e1598 100644 --- a/functions/public/Get-PSProjectReport.ps1 +++ b/functions/public/Get-PSProjectReport.ps1 @@ -35,6 +35,7 @@ Function Get-PSProjectReport { Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Using PowerShell Host $($Host.Name)" } #begin Process { diff --git a/functions/public/Get-PSProjectStatus.ps1 b/functions/public/Get-PSProjectStatus.ps1 index 79a08b7..2b07a95 100644 --- a/functions/public/Get-PSProjectStatus.ps1 +++ b/functions/public/Get-PSProjectStatus.ps1 @@ -14,12 +14,14 @@ Function Get-PSProjectStatus { ) Begin { - Write-Verbose "Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Using PowerShell Host $($Host.Name)" } Process { $json = Join-Path (Convert-Path $path) -ChildPath psproject.json if (Test-Path $json) { - Write-Verbose "Getting project status from $json" + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Getting project status from $json" $in = Get-Content -Path $json | ConvertFrom-Json $psproject = [PSProject]::new() @@ -27,7 +29,7 @@ Function Get-PSProjectStatus { $properties = $psproject.PSObject.properties.name | Where-Object { $_ -ne "Age" } foreach ($property in $properties) { if ($property -eq 'RemoteRepository') { - Write-Verbose "Creating remote repository information" + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Creating remote repository information" $remote = @() foreach ($repo in $in.RemoteRepository) { $remote += [PSProjectRemote]::new($repo.name, $repo.url, $repo.mode) @@ -36,7 +38,7 @@ Function Get-PSProjectStatus { } else { - Write-Verbose "Adding property $property" + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Adding property $property" $psproject.$property = $in.$property } } @@ -51,6 +53,6 @@ Function Get-PSProjectStatus { } #process End { - Write-Verbose "Ending $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" } } diff --git a/functions/public/Get-PSProjectTask.ps1 b/functions/public/Get-PSProjectTask.ps1 new file mode 100644 index 0000000..a4d64f1 --- /dev/null +++ b/functions/public/Get-PSProjectTask.ps1 @@ -0,0 +1,66 @@ +Function Get-PSProjectTask { + [cmdletbinding()] + [OutputType('psProjectTask')] + + Param( + [Parameter( + Position = 0, + ValueFromPipeline, + ValueFromPipelineByPropertyName, + HelpMessage = "Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule.")] + [ValidateScript({ Test-Path $_ })] + [alias("FullName")] + [String]$Path = ".", + [Parameter(HelpMessage = "Get a task by its ID number")] + [ValidateNotNullOrEmpty()] + [alias("ID")] + [int]$TaskID + ) + + Begin { + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Using PowerShell Host $($Host.Name)" + } #begin + + Process { + $cPath = Convert-Path $Path + $json = Join-Path $cPath -ChildPath psproject.json + If (Test-Path -path $json) { + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Processing tasks in $json" + $in = Get-Content -Path $json | ConvertFrom-Json + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Found $($in.tasks.count) tasks" + if ($in.Tasks) { + if ($TaskID -gt 0) { + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Getting Task number $TaskID" + } + #define a project task ID number + $i = 1 + foreach ($task in $in.tasks) { + $taskItem = [PSProjectTask]::New($task,$in.Path, $in.Name, $in.ProjectVersion) + $taskItem.TaskID = $i + if ($TaskID -AND ($TaskID -eq $i)) { + $taskItem + } + ElseIf (-Not $TaskID) { + $taskItem + } + $i++ + } + } + Else { + Write-Warning "[$((Get-Date).TimeOfDay) PROCESS] No tasks found for this project." + } + } + else { + Write-Warning "[$((Get-Date).TimeOfDay) PROCESS] Can't find psproject.json in the specified location $cPath." + } + + } #process + + End { + + Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" + } #end + +} #close Get-PSProjectTask \ No newline at end of file diff --git a/functions/public/New-PSProjectStatus.ps1 b/functions/public/New-PSProjectStatus.ps1 index b59a852..5901a8b 100644 --- a/functions/public/New-PSProjectStatus.ps1 +++ b/functions/public/New-PSProjectStatus.ps1 @@ -29,45 +29,62 @@ Function New-PSProjectStatus { [version]$ProjectVersion, [Parameter(HelpMessage = "Enter an optional comment. This could be git tag, or an indication about the type of project.")] - [String]$Comment + [String]$Comment, + + [Parameter(HelpMessage = "Overwrite an existing PSProjectStatus file.")] + [switch]$Force ) - Write-Verbose "Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Using PowerShell Host $($Host.Name)" $exclude = "Verbose", "WhatIf", "Confirm", "ErrorAction", "Debug", "WarningAction", "WarningVariable", "ErrorVariable","InformationAction", - "InformationVariable" + "InformationVariable","ProgressAction","Force" + + #convert the path to a filesystem path to avoid using PSDrive references + $cPath = Convert-Path $Path + Write-Verbose "[$((Get-Date).TimeOfDay)] Using path $Path" + + #Don't overwrite existing file unless -Force is specified + $json = Join-Path -Path $cPath -ChildPath psproject.json - Write-Verbose "Creating a new instance of the PSProject class" + if ((Test-Path -path $json) -AND (-Not $Force)) { + Write-Warning "An existing project status file was found. You must either delete the file or re-run this command with -Force." + #bail out of the command + Return + } + + Write-Verbose "[$((Get-Date).TimeOfDay)] Creating a new instance of the PSProject class" $new = [psproject]::New() + $new.Path = $cPath $new | Select-Object * | Out-String | Write-Debug - Write-Verbose "Using schema path $jsonSchema" - #convert the path to a filesystem path to avoid using PSDrive references - $new.Path = Convert-Path $Path - Write-Verbose "Using path $Path" + Write-Verbose "[$((Get-Date).TimeOfDay)] Using schema path $jsonSchema" + #set the instance properties using parameter values from this command $PSBoundParameters.GetEnumerator() | Where-Object { $exclude -NotContains $_.key } | ForEach-Object { - Write-Verbose "Setting property $($_.key)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Setting property $($_.key)" $new.$($_.key) = $_.value } Write-Verbose "Testing for .git" If (Test-Path .git) { $branch = git branch --show-current - Write-Verbose "Detected git branch $branch" + Write-Verbose "[$((Get-Date).TimeOfDay)] Detected git branch $branch" $new.GitBranch = $branch #get git remote $new.RemoteRepository = _getRemote } else { - Write-Verbose "No git branch detected" + Write-Verbose "[$((Get-Date).TimeOfDay)] No git branch detected" } if ($PSCmdlet.ShouldProcess($Name)) { $new $new.Save() } - Write-Verbose "Ending $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay)] Ending $($MyInvocation.MyCommand)" } diff --git a/functions/public/New-PSProjectTask.ps1 b/functions/public/New-PSProjectTask.ps1 new file mode 100644 index 0000000..52193d4 --- /dev/null +++ b/functions/public/New-PSProjectTask.ps1 @@ -0,0 +1,52 @@ +Function New-PSProjectTask { + [cmdletbinding(SupportsShouldProcess)] + [OutputType('None','psProjectTask')] + [alias('alias')] + Param( + [Parameter( + Position = 0, + Mandatory, + ValueFromPipeline, + ValueFromPipelineByPropertyName, + HelpMessage = "Enter the task description.")] + [ValidateNotNullOrEmpty()] + [string]$TaskDescription, + [Parameter( + HelpMessage = "Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule.")] + [ValidateScript({ Test-Path $_ })] + [alias("FullName")] + [String]$Path = ".", + [switch]$PassThru + ) + + Begin { + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Using PowerShell Host $($Host.Name)" + } #begin + + Process { + $cPath = Convert-Path $Path + $json = Join-Path $cPath -ChildPath psproject.json + If (Test-Path -path $json) { + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Processing tasks in $json" + $in = Get-Content -Path $json | ConvertFrom-Json + $in.Tasks+=$TaskDescription + $in.LastUpdate = Get-Date + + $in | ConvertTo-Json | Out-File -FilePath $json + if ($PassThru) { + Get-PSProjectTask | where TaskDescription -eq $TaskDescription + } + } + else { + Write-Warning "[$((Get-Date).TimeOfDay) PROCESS] Can't find psproject.json in the specified location $cPath." + } + + } #process + + End { + Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" + } #end + +} #close New-PSProjectStatus \ No newline at end of file diff --git a/functions/public/Remove-PSProjectTask.ps1 b/functions/public/Remove-PSProjectTask.ps1 new file mode 100644 index 0000000..09157d3 --- /dev/null +++ b/functions/public/Remove-PSProjectTask.ps1 @@ -0,0 +1,72 @@ +Function Remove-PSProjectTask { + [cmdletbinding(SupportsShouldProcess)] + [OutputType('None')] + Param( + [Parameter( + Position = 0, + Mandatory, + ValueFromPipelineByPropertyName, + HelpMessage = 'Enter the task ID')] + [ValidateNotNullOrEmpty()] + [Alias('ID')] + [Int[]]$TaskID, + [Parameter( + HelpMessage = 'Enter the parent path to the psproject.json file, e.g. c:\scripts\mymodule.')] + [ValidateScript({ Test-Path $_ })] + [alias('FullName')] + [String]$Path = '.' + ) + + Begin { + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Using PowerShell Host $($Host.Name)" + $cPath = Convert-Path $Path + $json = Join-Path $cPath -ChildPath psproject.json + If (Test-Path -Path $json) { + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Processing tasks in $json" + $in = Get-Content -Path $json | ConvertFrom-Json + } + else { + Write-Warning "[$((Get-Date).TimeOfDay) BEGIN ] Can't find psproject.json in the specified location $cPath." + } + } #begin + + Process { + If ($in) { + foreach ($item in $TaskID) { + $t = Get-PSProjectTask -id $item + if ($t.TaskID -gt 0) { + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Removing task $($t.TaskDescription) [$($t.TaskID)]" + $updated = $in.tasks | Where-Object { $_ -ne $t.TaskDescription } + $in.Tasks = $updated + } + else { + Write-Warning "Could not find a task with an ID of $TaskID" + } + } #foreach item + } #if $in + + } #process + + End { + Write-Verbose "[$((Get-Date).TimeOfDay) END ] Saving changes to $json" + $in.LastUpdate = Get-Date + $in | ConvertTo-Json | Out-File -FilePath $json + Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" + } #end + +} #close New-PSProjectStatus + + + + +Register-ArgumentCompleter -CommandName Remove-PSProjectTask -ParameterName TaskID -ScriptBlock { + param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter) + + #PowerShell code to populate $WordToComplete + Get-PSProjectTask | ForEach-Object { + # completion text,listitem text,result type,Tooltip + [System.Management.Automation.CompletionResult]::new($_.TaskID, $_.TaskID, 'ParameterValue', $_.TaskDescription) + } +} \ No newline at end of file diff --git a/functions/public/Set-PSProjectStatus.ps1 b/functions/public/Set-PSProjectStatus.ps1 index 85bf8df..4c89bf3 100644 --- a/functions/public/Set-PSProjectStatus.ps1 +++ b/functions/public/Set-PSProjectStatus.ps1 @@ -14,7 +14,7 @@ Function Set-PSProjectStatus { [Parameter(HelpMessage = "When was the project last worked on?")] [ValidateNotNullOrEmpty()] [alias("date")] - [DateTime]$LastUpdate, + [DateTime]$LastUpdate = $(Get-Date), [Parameter(HelpMessage = "What are the remaining tasks?")] [string[]]$Tasks, @@ -38,17 +38,27 @@ Function Set-PSProjectStatus { Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Running under PowerShell version $($PSVersionTable.PSVersion)" + Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Using PowerShell Host $($Host.Name)" } #begin Process { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Updating $($InputObject.name)" - $properties = "Name", "Status", "LastUpdate", "ProjectVersion", "Comment" + $properties = "Name", "Status", "ProjectVersion", "Comment" foreach ($property in $properties) { if ($PSBoundParameters.ContainsKey($property)) { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Updating $property" $InputObject.$property = $PSBoundParameters[$property] } } + #11/28/2023 - always update the LastUpdate property -JDH + Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Updating LastUpdate" + if ($PSBoundParameters.ContainsKey("LastUpdate")) { + $InputObject.LastUpdate = $PSBoundParameters["LastUpdate"] + } + else { + $InputObject.LastUpdate = $LastUpdate + } if ($PSBoundParameters.ContainsKey("Tasks")) { if ($Concatenate) { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Appending tasks" diff --git a/images/get-psprojecttask.png b/images/get-psprojecttask.png new file mode 100644 index 0000000..bc49b3f Binary files /dev/null and b/images/get-psprojecttask.png differ diff --git a/images/new-psprojecttask.png b/images/new-psprojecttask.png new file mode 100644 index 0000000..66be259 Binary files /dev/null and b/images/new-psprojecttask.png differ