clispark 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clispark",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Interactive scaffolding tool for new CLI projects",
   "keywords": [
     "cli",

package/templates/powershell/ARCHITECTURE.md

@@ -0,0 +1,26 @@
+# Architecture
+
+This project is a PowerShell module (`.psd1`/`.psm1`), not a single script — cmdlets get proper
+tab-completion, pipeline support, and discoverability via `Get-Command`.
+
+## Auto-registration
+
+Every `.ps1` file in `Public/` becomes an exported cmdlet automatically — no manual registration
+step. The filename must match the function name inside it (e.g. `Get-Hello.ps1` defines
+`function Get-Hello`).
+
+## Auto-logging and error handling
+
+`Module.psm1` wraps every `Public/` function with a **function-proxy-wrapper** at import time:
+logging (`started`/`completed`/`failed`) and error handling are added automatically, using
+PowerShell's own `System.Management.Automation.ProxyCommand` API — the same mechanism PowerShell's
+own module-remoting proxies use, so pipeline input and all parameter attributes are preserved
+exactly. Cmdlet authors never write their own try/catch or logging calls.
+
+## Testing
+
+[Pester](https://pester.dev/) — one `.Tests.ps1` file per cmdlet in `tests/`.
+
+## Logging
+
+[PSFramework](https://psframework.org/) — see `Logging/Initialize-Logging.ps1`.

package/templates/powershell/Logging/Initialize-Logging.ps1

@@ -0,0 +1,27 @@
+# Logging/Initialize-Logging.ps1 — PSFramework setup, loaded by Module.psm1 before any cmdlet
+# is wrapped. Mirrors the Node/.NET templates' logging principles: redaction, retention, DEBUG
+# streaming, a visible log path on both success and failure.
+
+Import-Module PSFramework -ErrorAction Stop
+
+$logDirectory = Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'clispark-generated' 'Logs'
+if (-not (Test-Path $logDirectory)) {
+    New-Item -ItemType Directory -Path $logDirectory -Force | Out-Null
+}
+
+Set-PSFLoggingProvider -Name 'logfile' -InstanceName 'default' -FilePath (Join-Path $logDirectory 'log-%date%.csv') -Enabled $true
+
+if ($env:DEBUG) {
+    Set-PSFLoggingProvider -Name 'console' -InstanceName 'default' -Enabled $true
+}
+
+# Retention: remove log files older than 14 days, best-effort (matches the Node/.NET templates'
+# LOG_RETENTION_DAYS convention — same default, same "never block the command on a sweep failure").
+try {
+    $cutoff = (Get-Date).AddDays(-14)
+    Get-ChildItem -Path $logDirectory -Filter 'log-*.csv' -ErrorAction SilentlyContinue |
+        Where-Object { $_.LastWriteTime -lt $cutoff } |
+        Remove-Item -ErrorAction SilentlyContinue
+} catch {
+    # Best-effort — a failed sweep must never block the command itself.
+}

package/templates/powershell/Module.psd1

@@ -0,0 +1,15 @@
+@{
+    RootModule        = 'Module.psm1'
+    ModuleVersion     = '0.1.0'
+    GUID              = '00000000-0000-0000-0000-000000000000'
+    Author            = 'Unknown'
+    Description       = 'Scaffolded by clispark.'
+    PowerShellVersion = '7.4'
+    FunctionsToExport = '*'
+    RequiredModules   = @('PSFramework', 'Pester', 'Microsoft.PowerShell.PSResourceGet')
+    PrivateData       = @{
+        PSData = @{
+            Tags = @()
+        }
+    }
+}

package/templates/powershell/Module.psm1

@@ -0,0 +1,70 @@
+# Module.psm1 — loads every cmdlet in Public/ and wraps it with automatic logging and
+# error handling. Cmdlet authors never write their own try/catch or logging calls.
+
+. (Join-Path $PSScriptRoot 'Logging' 'Initialize-Logging.ps1')
+
+$publicFiles = Get-ChildItem -Path (Join-Path $PSScriptRoot 'Public') -Filter '*.ps1'
+$publicFuncNames = $publicFiles.BaseName
+
+foreach ($file in $publicFiles) {
+    . $file.FullName
+    $funcName = $file.BaseName
+
+    # Rename the real implementation FIRST, then build the proxy metadata against the RENAMED
+    # command — the generated begin-block re-resolves the wrapped command by name at call time,
+    # so building metadata from the original name before renaming would make the wrapper recurse
+    # into itself once installed under that same name (verified for real during the design spec).
+    $renamedName = "__orig_$funcName"
+    Rename-Item "Function:\$funcName" $renamedName
+    $renamedCmd = Get-Command $renamedName -CommandType Function
+    $metadata = [System.Management.Automation.CommandMetadata]::new($renamedCmd)
+
+    $paramBlock = [System.Management.Automation.ProxyCommand]::GetParamBlock($metadata)
+    $beginBlock = [System.Management.Automation.ProxyCommand]::GetBegin($metadata)
+    $processBlock = [System.Management.Automation.ProxyCommand]::GetProcess($metadata)
+    $endBlock = [System.Management.Automation.ProxyCommand]::GetEnd($metadata)
+    $cmdletBinding = [System.Management.Automation.ProxyCommand]::GetCmdletBindingAttribute($metadata)
+
+    $wrapperDef = @"
+function $funcName {
+$cmdletBinding
+param(
+$paramBlock
+)
+begin {
+    Write-PSFMessage -Level Verbose -Message "started: $funcName"
+    `$__sw = [System.Diagnostics.Stopwatch]::StartNew()
+    try {
+$beginBlock
+    } catch {
+        Write-PSFMessage -Level Error -Message "failed: $funcName" -ErrorRecord `$_
+        throw
+    }
+}
+process {
+    try {
+$processBlock
+    } catch {
+        Write-PSFMessage -Level Error -Message "failed: $funcName" -ErrorRecord `$_
+        throw
+    }
+}
+end {
+    try {
+$endBlock
+        Write-PSFMessage -Level Verbose -Message "completed: $funcName (`$(`$__sw.ElapsedMilliseconds)ms)"
+    } catch {
+        Write-PSFMessage -Level Error -Message "failed: $funcName" -ErrorRecord `$_
+        throw
+    }
+}
+}
+"@
+
+    Invoke-Expression $wrapperDef
+}
+
+# Export only the real Public/ function names — never `-Function *`, which would also export
+# the renamed __orig_* internals and trigger PowerShell's "unapproved verb" warning on import
+# (verified for real during the design spec).
+Export-ModuleMember -Function $publicFuncNames

package/templates/powershell/Public/Get-Hello.ps1

@@ -0,0 +1,10 @@
+function Get-Hello {
+    [CmdletBinding()]
+    param(
+        [Parameter(Position = 0)]
+        [string]$Name = 'World'
+    )
+    process {
+        Write-Output "Hello, $Name!"
+    }
+}

package/templates/powershell/README.md

@@ -0,0 +1,26 @@
+# {{projectName}}
+
+A PowerShell module scaffolded by [clispark](https://www.npmjs.com/package/clispark).
+
+## Usage
+
+```powershell
+Import-Module ./Module.psd1
+Get-Hello -Name 'World'
+```
+
+## Adding a new cmdlet
+
+Run `clispark add` from this directory, or drop a new `.ps1` file into `Public/` following the
+existing `Get-Hello.ps1` pattern — every function found there is automatically wrapped with
+logging and error handling on module import, no manual try/catch needed.
+
+## Testing
+
+```powershell
+Invoke-Pester ./tests
+```
+
+## Architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md).

package/templates/powershell/gitignore

@@ -0,0 +1,2 @@
+Logs/
+*.log

package/templates/powershell/tests/Get-Hello.Tests.ps1

@@ -0,0 +1,9 @@
+Describe 'Get-Hello' {
+    It 'greets the given name' {
+        Get-Hello -Name 'Pester' | Should -Be 'Hello, Pester!'
+    }
+
+    It 'defaults to World when no name is given' {
+        Get-Hello | Should -Be 'Hello, World!'
+    }
+}