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

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

# 비교를 위해 user scope 쪽도 본다
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