winget + PowerShell로 PC 키팅을 자동화하기 ── 절차서를 실행 가능하게 만들기

# ID를 정확히 지정해서 설치한다(-e 는 완전 일치, --id 는 ID 지정)
#   --silent                     : UI를 표시하지 않음
#   --accept-package-agreements  : 패키지 사용 조건에 동의
#   --accept-source-agreements   : 소스 사용 조건에 동의
#   --scope machine               : 전체 사용자용으로 설치(대응 패키지만)
# 줄바꿈 백틱은 줄 끝에 둔다. 뒤에 주석을 쓰면 줄바꿈으로 인식되지 않는다
winget install --id Google.Chrome -e --silent `
    --accept-package-agreements --accept-source-agreements --scope machine

# ID를 조회한다
winget search "Visual Studio Code"
winget show --id Microsoft.VisualStudioCode

# 머신 스코프의 설치 프로그램이 있는지 확인한다
winget show --id Google.Chrome -e --scope machine

# 비교를 위해 사용자 스코프 쪽도 확인해 둔다
winget show --id Google.Chrome -e --scope user

# 표준 PC에서 설치된 패키지 목록을 JSON으로 내보낸다
winget export --output D:\kitting\apps.json --include-versions

# 새 PC에서 복원한다
winget import --import-file D:\kitting\apps.json `
    --accept-package-agreements --accept-source-agreements --ignore-unavailable

# 적용 전에 내용을 확인한다(무엇이 실행되는지 표시)
winget configure show --file D:\kitting\kitting.winget

# 적용한다
winget configure --file D:\kitting\kitting.winget --accept-configuration-agreements

#Requires -RunAsAdministrator
[CmdletBinding()]
param(
    [string] $ConfigPath = "$PSScriptRoot\kitting.config.json"
)

$ErrorActionPreference = 'Stop'
# 5.1의 Get-Content는 BOM이 없으면 ANSI 코드 페이지로 읽는다.
# UTF-8 JSON을 일본어 환경에서 읽으면 깨지므로 명시적으로 지정한다
$config = Get-Content $ConfigPath -Raw -Encoding utf8 | ConvertFrom-Json
$rebootRequired  = $false
$rebootInitiated = $false
$log    = "C:\ProgramData\KsKitting\kitting_$(Get-Date -f yyyyMMdd_HHmmss).log"
$null   = New-Item -Path (Split-Path $log) -ItemType Directory -Force

# 후술하는 사용자 단위 단계는 별도 프로세스로 동작하므로, 설정을
# 모든 사용자가 읽을 수 있는 위치로 배포해 둔다.
# 배포물을 이 위치에 두고 그대로 실행하면 복사 원본과 대상이 같은 파일이 된다.
# Copy-Item은 자기 자신으로의 복사를 오류로 처리하므로, $ErrorActionPreference = 'Stop'
# 아래에서는 키팅이 시작되기 전에 스크립트째 멈춰 버린다
$sharedConfig = 'C:\ProgramData\KsKitting\kitting.config.json'
$sourceFull   = (Resolve-Path $ConfigPath).ProviderPath
$sharedFull   = if (Test-Path $sharedConfig) { (Resolve-Path $sharedConfig).ProviderPath } else { '' }
if (-not [string]::Equals($sourceFull, $sharedFull, 'OrdinalIgnoreCase')) {
    Copy-Item $ConfigPath $sharedConfig -Force
}
Start-Transcript -Path $log -Append

try {
    # --- 1. 표준 폴더 ------------------------------------------------
    foreach ($dir in $config.folders) {
        if (-not (Test-Path $dir)) {
            $null = New-Item -Path $dir -ItemType Directory
            Write-Verbose "생성: $dir"
        }
    }

    # --- 2. 사내 표준 레지스트리 설정 --------------------------------------
    foreach ($reg in $config.registry) {
        if (-not (Test-Path $reg.key)) { $null = New-Item -Path $reg.key -Force }
        $item   = Get-Item -Path $reg.key
        $exists = $item.GetValueNames() -contains $reg.name

        # 값뿐 아니라 "타입"도 비교한다. REG_SZ의 "1"과 DWORD의 1은
        # PowerShell의 비교에서는 같다고 판정되어, 실제로는 적용되지 않은 설정을
        # "적용 완료"로 오판할 수 있다
        $sameValue = $exists -and $item.GetValue($reg.name) -eq $reg.value
        $sameKind  = $exists -and $item.GetValueKind($reg.name).ToString() -eq $reg.type

        if (-not ($sameValue -and $sameKind)) {
            Set-ItemProperty -Path $reg.key -Name $reg.name -Value $reg.value -Type $reg.type
            Write-Verbose "설정: $($reg.key)\$($reg.name) = $($reg.value) ($($reg.type))"
        }
    }

    # --- 3. Windows 기능 --------------------------------------------------
    foreach ($feature in $config.windowsFeatures) {
        $state = Get-WindowsOptionalFeature -Online -FeatureName $feature
        if ($state.State -ne 'Enabled') {
            # -NoRestart로 재부팅을 억제한 경우, 필요 여부는 반환값의 RestartNeeded에 나타난다.
            # 이를 파악해 두지 않으면 "재부팅이 필요한데 0으로 종료"하게 된다
            $result = Enable-WindowsOptionalFeature -Online -FeatureName $feature -NoRestart
            if ($result.RestartNeeded) { $rebootRequired = $true }
        }
    }

    # --- 4. winget 패키지 ----------------------------------------------
    # winget의 종료 코드는 "이미 설치됨"에서도 0 이외가 될 수 있고,
    # 반대로 0이어도 실제로는 설치되지 않은 경우가 있다. 성공 여부는 상태 조회로 판단한다.
    # --scope를 붙이지 않으면 관리자 자신의 사용자 단위 설치를 잡아내어
    # "machine으로 설치됨"으로 오판할 수 있다
    function Test-KsWingetPackage {
        param([string] $Id, [string] $Scope)
        $arguments = @('list', '--id', $Id, '--exact', '--accept-source-agreements')
        if ($Scope) { $arguments += @('--scope', $Scope) }
        $null = winget @arguments 2>&1
        return ($LASTEXITCODE -eq 0)
    }

    foreach ($package in $config.wingetPackages) {
        if (Test-KsWingetPackage -Id $package.id -Scope $package.scope) { continue }

        # 줄바꿈 백틱은 줄 끝에 둔다. 뒤에 주석을 쓰면 줄바꿈으로 인식되지 않는다
        winget install --id $package.id -e --silent `
            --accept-package-agreements --accept-source-agreements `
            --scope $package.scope
        $wingetExit = $LASTEXITCODE

        # 여기서 경고만 표시하고 진행하면, 필수 앱이 설치되지 않은 단말을
        # 배포 도구가 "키팅 성공"으로 기록해 버린다
        if (-not (Test-KsWingetPackage -Id $package.id -Scope $package.scope)) {
            throw "$($package.id) 도입에 실패했습니다 (winget ExitCode=$wingetExit)"
        }
    }

    # --- 5. 사내 앱(공유 폴더의 설치 프로그램을 사일런트 실행) ----
    # 설치된 목록은 32bit/64bit 양쪽 뷰를 명시해서 연다.
    # 32bit PowerShell이 64bit Windows에서 동작하면(Intune 구성에 따라 발생할 수 있음),
    # WOW64 리디렉션으로 HKLM:\SOFTWARE\...가 32bit 뷰를 가리켜
    # 64bit 앱을 "미설치"로 오판해 매번 다시 설치해 버린다
    $installedApps = foreach ($view in 'Registry64', 'Registry32') {
        $baseKey = [Microsoft.Win32.RegistryKey]::OpenBaseKey('LocalMachine', $view)
        try {
            $uninstall = $baseKey.OpenSubKey('SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall')
            if (-not $uninstall) { continue }
            try {
                foreach ($name in $uninstall.GetSubKeyNames()) {
                    $appKey = $uninstall.OpenSubKey($name)
                    if (-not $appKey) { continue }
                    try {
                        $displayName = $appKey.GetValue('DisplayName')
                        if ($displayName) {
                            [pscustomobject]@{
                                DisplayName    = [string] $displayName
                                DisplayVersion = [string] $appKey.GetValue('DisplayVersion')
                            }
                        }
                    }
                    finally { $appKey.Dispose() }
                }
            }
            finally { $uninstall.Dispose() }
        }
        finally { $baseKey.Dispose() }
    }

    foreach ($app in $config.internalApps) {
        $installed = $installedApps | Where-Object DisplayName -eq $app.displayName

        # DisplayName의 일치만으로 "설치됨"이라고 판단하지 않는다. 오래된 버전이 설치된 채로
        # 새 버전이 설치되지 않아, 재실행해도 설정 파일의 상태로 수렴하지 않게 된다.
        # 설정에 version이 있으면 그 버전 이상이 설치되어 있는지까지 확인한다
        $upToDate = if ($app.version) {
            $wanted = [version] $app.version
            [bool]($installed | Where-Object {
                $cur = $_.DisplayVersion -as [version]   # 버전 형식이 아닌 표기는 대상에서 제외
                $cur -and $cur -ge $wanted
            })
        } else {
            [bool] $installed
        }
        if ($upToDate) { continue }

        # Start-Process의 -ArgumentList는 배열을 공백으로 연결해 한 줄의 명령줄로 만들기 때문에,
        # 공백을 포함한 값은 설정 파일 쪽에서 따옴표로 감싸 두어야 한다
        # 예: '/quiet /norestart INSTALLDIR="C:\Program Files\KsApp"'
        # .msi는 실행 파일이 아니므로, 그대로 Start-Process에 전달하면
        # "유효한 애플리케이션이 아닙니다"로 실패한다. msiexec를 경유해서 실행한다
        if ([System.IO.Path]::GetExtension($app.installer) -eq '.msi') {
            $msiArgs = @('/i', "`"$($app.installer)`"") + $app.arguments
            $proc = Start-Process -FilePath 'msiexec.exe' -ArgumentList $msiArgs -Wait -PassThru -NoNewWindow
        }
        else {
            $proc = Start-Process -FilePath $app.installer -ArgumentList $app.arguments -Wait -PassThru -NoNewWindow
        }
        # Windows Installer의 종료 코드는 "0만이 성공"이 아니다.
        # 3010과 1641은 모두 성공이며, 재부팅 취급만 다르다
        switch ($proc.ExitCode) {
            0    { }                                   # 성공
            3010 { $rebootRequired = $true }           # 성공. 재부팅 필요(ERROR_SUCCESS_REBOOT_REQUIRED)
            1641 { $rebootInitiated = $true }          # 성공. 설치 프로그램이 재부팅을 시작함
            default {
                throw "$($app.displayName) 설치에 실패했습니다 (ExitCode=$($proc.ExitCode))"
            }
        }
        # 재부팅이 시작되었다면, 이후의 설치는 실행해도 중단된다
        if ($rebootInitiated) { break }
    }

    if ($rebootInitiated) {
        # 1641은 "성공. 다만 재부팅을 이미 시작함". 0을 반환하면 배포 도구는
        # "완료되었는데 멋대로 재부팅했다"고 취급하므로, 그대로 전달한다
        Write-Host '설치 프로그램이 재부팅을 시작했습니다. 재부팅 후 다시 실행해 주세요' -ForegroundColor Yellow
        exit 1641
    }

    if ($rebootRequired) {
        # 3010을 그대로 반환하면 Intune이나 배포 도구 쪽이 "성공. 재부팅 필요"로 해석해
        # 재부팅 스케줄링과 보고를 수행할 수 있다. 여기서 0을 반환하면 재부팅이 잊혀진다
        Write-Host '키팅 완료(재부팅 필요)' -ForegroundColor Yellow
        exit 3010
    }

    Write-Host '키팅 완료' -ForegroundColor Green
    exit 0
}
catch {
    Write-Warning "실패: $($_.Exception.Message)"
    Write-Warning $_.InvocationInfo.PositionMessage
    exit 1
}
finally {
    Stop-Transcript
}

# 사용자 단위 설정(비승격으로, 이용자의 로그온 시 실행한다. 등록 방법은 후술)

# 관리자 스크립트와는 별도 프로세스이므로 $config는 이어받지 않는다.
# 관리자 단계에서 ProgramData로 배포해 둔 설정을 다시 읽는다
$configPath = 'C:\ProgramData\KsKitting\kitting.config.json'
if (-not (Test-Path $configPath)) {
    Write-Warning "설정 파일을 찾을 수 없습니다: $configPath"
    exit 1
}
$config = Get-Content $configPath -Raw -Encoding utf8 | ConvertFrom-Json

# 사용자 단위 레지스트리 설정(HideFileExt 등. HKLM에 써도 효과가 없음)
foreach ($reg in $config.userRegistry) {
    if (-not (Test-Path $reg.key)) { $null = New-Item -Path $reg.key -Force }

    $item   = Get-Item -Path $reg.key
    $exists = $item.GetValueNames() -contains $reg.name
    $same   = $exists -and
              $item.GetValue($reg.name) -eq $reg.value -and
              $item.GetValueKind($reg.name).ToString() -eq $reg.type

    if (-not $same) {
        Set-ItemProperty -Path $reg.key -Name $reg.name -Value $reg.value -Type $reg.type
    }
}

# 네트워크 드라이브
foreach ($drive in $config.drives) {
    $local    = "$($drive.letter):"
    $existing = Get-SmbMapping -LocalPath $local -ErrorAction SilentlyContinue
    if ($existing) {
        # "할당이 있는가"만으로 판단하면, 공유 이전 등으로 설정을 바꿔도
        # 오래된 할당이 남은 채 "성공"으로 보고되어 버린다. 연결 대상까지 비교한다
        if ($existing.RemotePath.TrimEnd('\') -eq $drive.path.TrimEnd('\')) { continue }
        Remove-SmbMapping -LocalPath $local -Force
    }
    New-SmbMapping -LocalPath $local -RemotePath $drive.path -Persistent $true
}

# 공유 프린터 연결도 사용자 단위다. 관리자나 SYSTEM으로 실행하면
# 그 계정에만 연결이 만들어지고, 이용자에게는 보이지 않는다
foreach ($printer in $config.printers) {
    if (-not (Get-Printer -Name $printer.name -ErrorAction SilentlyContinue)) {
        Add-Printer -ConnectionName $printer.connection
    }
}

# 사용자 단계 스크립트를 모든 사용자가 읽을 수 있는 위치에 배치한다
$userScript = 'C:\ProgramData\KsKitting\Invoke-KsUserKitting.ps1'
Copy-Item "$PSScriptRoot\Invoke-KsUserKitting.ps1" $userScript -Force

# HKLM의 Run은 로그온한 이용자의 권한(비승격)으로 실행된다.
# HKCU에 쓰려고 해도, 관리자/SYSTEM으로 동작하는 이상 쓰이는 것은
# "관리자 자신의 HKCU"이며, 이제부터 사용할 직원의 HKCU가 아니다
$runKey  = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Run'
$command = 'powershell.exe -NoProfile -ExecutionPolicy Bypass ' +
           "-WindowStyle Hidden -File `"$userScript`""
Set-ItemProperty -Path $runKey -Name 'KsUserKitting' -Value $command

# 모든 사용자가 읽을 수 있는 위치에 배치한다(방법 1과 동일)
$userScript = 'C:\ProgramData\KsKitting\Invoke-KsUserKitting.ps1'
New-Item -ItemType Directory -Path (Split-Path $userScript) -Force | Out-Null
Copy-Item -Path '.\Invoke-KsUserKitting.ps1' -Destination $userScript -Force

$action = New-ScheduledTaskAction -Execute 'powershell.exe' `
    -Argument "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$userScript`""

$trigger = New-ScheduledTaskTrigger -AtLogOn

# BUILTIN\Users(S-1-5-32-545)를 지정하면 로그온한 본인의 권한으로 실행된다.
# RunLevel Limited가 "승격하지 않음"의 지정이다. 여기를 Highest로 하면
# 승격된 세션에서 실행되어 드라이브 할당이 이용자에게 보이지 않게 된다
$principal = New-ScheduledTaskPrincipal -GroupId 'S-1-5-32-545' -RunLevel Limited

Register-ScheduledTask -TaskName 'KsUserKitting' `
    -Action $action -Trigger $trigger -Principal $principal -Force

Install-Module -Name Microsoft.WinGet.Client -Scope AllUsers -Force

# 이미 설치되어 있는지 확인한 뒤 설치한다(멱등)
foreach ($id in 'Google.Chrome', 'Microsoft.VisualStudioCode', '7zip.7zip') {
    if (Get-WinGetPackage -Id $id -ErrorAction SilentlyContinue) {
        Write-Verbose "설치됨: $id"
        continue
    }
    Install-WinGetPackage -Id $id -Mode Silent -Scope System
}

# 구문 분석 + 정적 분석(Windows가 아니어도 실행 가능)
./Invoke-SampleTests.ps1