feat: scaffold postgresql toolkit cli

Author: mudssky

scripts/pwsh/devops/postgresql/.env.example

@@ -0,0 +1,5 @@
+PGHOST=127.0.0.1
+PGPORT=5432
+PGUSER=postgres
+PGPASSWORD=change-me
+PGDATABASE=app

scripts/pwsh/devops/postgresql/README.md

@@ -0,0 +1,16 @@
+# PostgreSQL Toolkit Source
+
+这个目录存放 PostgreSQL PowerShell CLI 的源码、帮助文档源文件和构建脚本。
+
+## Build
+
+```powershell
+pwsh -NoProfile -File ./scripts/pwsh/devops/postgresql/build/Build-PostgresToolkit.ps1
+```
+
+## Commands
+
+- `backup`
+- `restore`
+- `import-csv`
+- `install-tools`

scripts/pwsh/devops/postgresql/commands/help.ps1

@@ -0,0 +1,44 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+<#
+.SYNOPSIS
+    返回 PostgreSQL Toolkit 的帮助文本。
+
+.DESCRIPTION
+    统一生成 CLI 使用说明，后续子命令级帮助也从这里扩展，
+    让控制台帮助与独立帮助文档尽量保持一致。
+
+.PARAMETER CommandName
+    可选的子命令名称；当前最小实现统一返回总览帮助。
+
+.OUTPUTS
+    string
+    返回可直接打印到控制台的帮助文本。
+#>
+function Get-PostgresToolkitHelpText {
+    [CmdletBinding()]
+    param(
+        [string]$CommandName
+    )
+
+    $defaultHelp = @'
+Usage:
+  ./Postgres-Toolkit.ps1 <command> [options]
+
+Commands:
+  backup
+  restore
+  import-csv
+  install-tools
+  help
+
+Examples:
+  ./Postgres-Toolkit.ps1 backup --database app --output ./app.dump --format custom
+  ./Postgres-Toolkit.ps1 restore --input ./app.dump --target-database app_restore --clean
+  ./Postgres-Toolkit.ps1 import-csv --input ./users.csv --table users --header
+  ./Postgres-Toolkit.ps1 install-tools --apply
+'@
+
+    return $defaultHelp.Trim()
+}

scripts/pwsh/devops/postgresql/docs/help.md

@@ -0,0 +1,14 @@
+# Postgres Toolkit Help
+
+## Commands
+
+- `backup`
+- `restore`
+- `import-csv`
+- `install-tools`
+
+## Examples
+
+```powershell
+./Postgres-Toolkit.ps1 backup --database app --output ./app.dump --format custom
+```

scripts/pwsh/devops/postgresql/main.ps1

@@ -0,0 +1,68 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    PostgreSQL 常用备份、恢复、CSV 导入与工具安装命令行工具。
+
+.DESCRIPTION
+    当前入口先负责子命令分发与帮助输出，后续命令实现会逐步挂到这里。
+
+.PARAMETER CommandName
+    要执行的子命令名称，例如 `backup`、`restore`、`help`。
+
+.PARAMETER RawArguments
+    透传给子命令解析器的剩余参数数组。
+#>
+[CmdletBinding(PositionalBinding = $false)]
+param(
+    [Parameter(Position = 0)]
+    [string]$CommandName,
+
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$RawArguments
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+<#
+.SYNOPSIS
+    执行 PostgreSQL Toolkit 的顶层命令分发。
+
+.DESCRIPTION
+    当前最小实现只负责帮助命令与空命令路径，后续再接入具体子命令。
+
+.PARAMETER CommandName
+    顶层命令名。
+
+.PARAMETER RawArguments
+    透传的剩余参数。
+
+.OUTPUTS
+    PSCustomObject
+    返回包含 `ExitCode` 与 `Output` 的标准执行结果。
+#>
+function Invoke-PostgresToolkitCommand {
+    [CmdletBinding()]
+    param(
+        [string]$CommandName,
+        [string[]]$RawArguments
+    )
+
+    if ([string]::IsNullOrWhiteSpace($CommandName) -or $CommandName -eq 'help') {
+        return [PSCustomObject]@{
+            ExitCode = 0
+            Output   = Get-PostgresToolkitHelpText
+        }
+    }
+
+    throw "未知命令: $CommandName"
+}
+
+if ($env:PWSH_TEST_SKIP_POSTGRES_TOOLKIT_MAIN -ne '1') {
+    $result = Invoke-PostgresToolkitCommand -CommandName $CommandName -RawArguments $RawArguments
+    if (-not [string]::IsNullOrWhiteSpace($result.Output)) {
+        Write-Output $result.Output
+    }
+
+    exit $result.ExitCode
+}

tests/PostgresToolkit.Commands.Tests.ps1

@@ -0,0 +1,41 @@
+Set-StrictMode -Version Latest
+
+BeforeAll {
+    $script:RepoRoot = Join-Path $PSScriptRoot '..'
+    $env:PWSH_TEST_SKIP_POSTGRES_TOOLKIT_MAIN = '1'
+
+    foreach ($relativePath in @(
+            'scripts/pwsh/devops/postgresql/core/logging.ps1'
+            'scripts/pwsh/devops/postgresql/core/process.ps1'
+            'scripts/pwsh/devops/postgresql/core/arguments.ps1'
+            'scripts/pwsh/devops/postgresql/core/connection.ps1'
+            'scripts/pwsh/devops/postgresql/core/context.ps1'
+            'scripts/pwsh/devops/postgresql/core/formats.ps1'
+            'scripts/pwsh/devops/postgresql/core/validation.ps1'
+            'scripts/pwsh/devops/postgresql/commands/help.ps1'
+            'scripts/pwsh/devops/postgresql/main.ps1'
+        )) {
+        . (Join-Path $script:RepoRoot $relativePath)
+    }
+}
+
+Describe 'Get-PostgresToolkitHelpText' {
+    It '输出四个核心命令和示例' {
+        $helpText = Get-PostgresToolkitHelpText
+
+        $helpText | Should -Match 'backup'
+        $helpText | Should -Match 'restore'
+        $helpText | Should -Match 'import-csv'
+        $helpText | Should -Match 'install-tools'
+        $helpText | Should -Match 'Postgres-Toolkit.ps1 backup'
+    }
+}
+
+Describe 'Invoke-PostgresToolkitCommand' {
+    It '未传命令时返回帮助文本而不是抛错' {
+        $result = Invoke-PostgresToolkitCommand -CommandName '' -RawArguments @()
+
+        $result.ExitCode | Should -Be 0
+        $result.Output | Should -Match 'Usage'
+    }
+}