Windows App Reinstall Catalog

This repository contains a PowerShell workflow for capturing a Windows software inventory, converting it into a structured catalog, enriching that catalog with installer metadata, and preparing a reinstall plan.

It is intended for scenarios such as:

• rebuilding a workstation after a clean install
• documenting the applications on a machine before migration or replacement
• tracking which apps can be restored automatically and which still require manual download steps
• backing up a few app-specific settings folders before reinstalling Windows

The workflow centers on catalog/apps.json, a machine-readable catalog that keeps installation state, package candidates, local installer matches, classification data, and manual follow-up notes in one place. That working file is intentionally ignored by Git so local catalog state does not end up in the public repository.

The repository also includes a small Pester test suite for catalog validation and install-plan generation behavior.

What The Repository Does

The scripts in this repository help you:

• create an import-ready installed-programs.csv from an existing Windows machine
• back up a small set of app-specific settings folders before a rebuild
• export the currently installed Windows programs to CSV
• initialize a JSON catalog from that snapshot
• re-scan the machine and mark apps as installed, missing, or ignored
• classify entries so runtimes and system components can be separated from user applications
• look up likely winget package IDs and latest available versions
• discover matching installer files in local folders
• stage installers into a single working directory
• generate a manual-source queue for apps that cannot be resolved automatically
• build an install plan and optionally execute it

Requirements

• Windows
• PowerShell 7 or Windows PowerShell with script execution enabled for local scripts
• winget for package lookup, version refresh, and optional download/install flows
• Pester 5 or newer to run the test suite as written

Run commands from the repository root:

pwsh -File .\scripts\AppReinstall.ps1 -Action Doctor

Repository Layout

Path	Purpose
scripts/	Entry-point scripts for inventory, catalog maintenance, staging, and installation
scripts/lib/AppCatalog.psm1	Shared helper functions used by all scripts
catalog/	Local working catalog directory; apps.json is ignored by Git
docs/	Supporting project notes and evaluation documents
installed-programs.csv	Generic sample source snapshot; replace this with a real export before use
output/	Generated reports, queues, logs, and staged installers
tests/	Pester tests covering catalog validation and install-plan behavior

output/ is ignored by Git except for a placeholder, and catalog/apps.json is also ignored, so generated reports and local catalog state do not need to be committed.

Quick Start

The recommended path now uses a single workflow wrapper instead of requiring the script-by-script sequence.

1. On the source machine, capture the installed-program inventory

pwsh -File .\scripts\AppReinstall.ps1 -Action Capture

This writes installed-programs.csv in the repository root.

If you want a timestamped backup pack instead, including the app inventory and reference exports:

pwsh -File .\scripts\AppReinstall.ps1 -Action Capture -CaptureMode BackupPack

To include the small settings-backup allowlist in the same capture run:

pwsh -File .\scripts\AppReinstall.ps1 -Action Capture -CaptureMode BackupPack -IncludeSettingsBackup

2. Run the preflight checks

pwsh -File .\scripts\AppReinstall.ps1 -Action Doctor

This validates the Windows host, PowerShell runtime, winget, and the expected working files. A machine-readable report is written to output/preflight-report.json.

To validate the current catalog and install queue structure without changing state:

pwsh -File .\scripts\AppReinstall.ps1 -Action Validate

This writes output/validation-report.json.

3. Prepare the reinstall workspace

pwsh -File .\scripts\AppReinstall.ps1 -Action Prepare

This runs the current recommended preparation pipeline:

• initialize the catalog if it does not exist yet
• sync the catalog against the current machine
• classify apps and apply ignore recommendations
• resolve winget package IDs and latest versions
• search common folders for installers
• stage installers into staged-installers/
• build output/install-queue.json
• refresh output/manual-source-queue.json

Additional reports are also written during prepare, including output/sync-report.json, output/classification-report.json, output/winget-report.json, output/latest-version-report.json, and output/installer-report.json.

To skip winget downloads during staging:

pwsh -File .\scripts\AppReinstall.ps1 -Action Prepare -SkipWingetDownload

To add manual-reference downloads when a trusted manual URL is already recorded in the catalog:

pwsh -File .\scripts\AppReinstall.ps1 -Action Prepare -DownloadFromManualReferences

To search additional installer folders during discovery:

pwsh -File .\scripts\AppReinstall.ps1 -Action Prepare -SearchRoot C:\Installers,$env:USERPROFILE\Downloads

4. Build and review the install plan

pwsh -File .\scripts\AppReinstall.ps1 -Action Plan

This writes the current plan to output/install-plan.json without executing anything.

To prefer direct winget install commands in the plan for apps that already have a wingetId:

pwsh -File .\scripts\AppReinstall.ps1 -Action Plan -UseWingetWhenAvailable

To allow .exe installers without recorded silent arguments:

pwsh -File .\scripts\AppReinstall.ps1 -Action Plan -AllowExeWithoutArgs

5. Execute when ready

pwsh -File .\scripts\AppReinstall.ps1 -Action Execute

To review a checklist first and deselect apps you do not want to process:

pwsh -File .\scripts\AppReinstall.ps1 -Action Execute -InteractiveChecklist

-UseWingetWhenAvailable and -AllowExeWithoutArgs are also available during -Action Execute.

Checklist controls:

• Up/Down arrows: move cursor
• Space: tick/untick highlighted app
• A: select all
• N: select none
• D or Enter: done
• C or Esc: cancel

Wrapper Actions

AppReinstall.ps1 exposes the full action set below:

• Doctor validates the Windows host, PowerShell runtime, winget, key paths, and queue/catalog health
• Validate checks the current catalog and install queue JSON structure without changing workflow state
• Capture exports installed-programs.csv or builds a timestamped backup pack
• Initialize creates catalog/apps.json directly from installed-programs.csv
• Status re-syncs the catalog and writes output/sync-report.json
• Prepare runs the recommended end-to-end preparation pipeline
• Plan builds output/install-plan.json
• Execute runs the prepared queue and writes output/install-log.json

Detailed Script Workflow

1. On the existing machine, create a backup pack

pwsh -File .\scripts\backup-app-list.ps1
pwsh -File .\scripts\backup-app-settings.ps1

backup-app-list.ps1 creates an import-ready installed-programs.csv inside a timestamped backup folder, along with supporting reference files such as startup items, shortcuts, taskbar pins, and a reinstall checklist.

2. Copy the exported CSV into the repository root

Replace the sample installed-programs.csv in this repository with the one generated by backup-app-list.ps1.

If you are running everything on the same machine and only need the app list, you can also generate the CSV directly:

pwsh -File .\scripts\Get-InstalledPrograms.ps1 -Format Csv -OutputPath .\installed-programs.csv

3. Build the catalog

pwsh -File .\scripts\Initialize-AppCatalog.ps1

This creates catalog/apps.json from the CSV snapshot.

4. Sync the catalog against the current machine

pwsh -File .\scripts\Sync-AppCatalog.ps1 -View Summary
pwsh -File .\scripts\Sync-AppCatalog.ps1 -View Missing

5. Classify entries

pwsh -File .\scripts\Classify-AppCatalog.ps1 -ApplyIgnoreRecommendations

This helps remove obvious runtimes, SDK fragments, and system-managed components from the reinstall target list.

6. Resolve package IDs and latest versions

pwsh -File .\scripts\Resolve-WingetPackages.ps1 -MaxApps 20
pwsh -File .\scripts\Update-LatestAppVersions.ps1 -MaxApps 20

7. Search local folders for installers

pwsh -File .\scripts\Find-AppInstallers.ps1 -SearchRoot C:\Installers,$env:USERPROFILE\Downloads

8. Stage installers into a working folder

pwsh -File .\scripts\Prepare-AppInstallers.ps1 -DownloadWithWinget

9. Review apps that still need manual acquisition

pwsh -File .\scripts\Get-ManualSourceQueue.ps1 -Format Table -UpdateCatalog

If the catalog already contains trusted installer.manualReferenceUrl values and you want to try downloading them into the stage folder:

pwsh -File .\scripts\Download-ManualReferenceInstallers.ps1

10. Build an install plan

pwsh -File .\scripts\Install-PreparedApps.ps1 -Mode Plan

Review the generated plan before any execution step.

11. Execute when ready

pwsh -File .\scripts\Install-PreparedApps.ps1 -Mode Execute

To review a checklist first and deselect apps you do not want to process:

pwsh -File .\scripts\Install-PreparedApps.ps1 -Mode Execute -InteractiveChecklist

Checklist controls:

• Up/Down arrows: move cursor
• Space: tick/untick highlighted app
• A: select all
• N: select none
• D or Enter: done
• C or Esc: cancel

Script Reference

Script	Purpose
AppReinstall.ps1	Guided workflow wrapper that exposes Doctor, Validate, Capture, Initialize, Status, Prepare, Plan, and Execute
backup-app-list.ps1	Creates a timestamped backup pack from an existing machine, including the import-ready installed-programs.csv used by this repo
backup-app-settings.ps1	Copies a small set of app settings folders and color profiles into a timestamped backup folder
Get-InstalledPrograms.ps1	Reads installed-program data from the local machine and outputs table, JSON, or CSV
Initialize-AppCatalog.ps1	Creates catalog/apps.json from installed-programs.csv
Sync-AppCatalog.ps1	Re-checks the machine and updates each app status
Classify-AppCatalog.ps1	Assigns buckets such as application, runtime, sdk, driver, browser, or developer-tool
Resolve-WingetPackages.ps1	Finds likely winget package candidates and stores the best match
Update-LatestAppVersions.ps1	Refreshes latest.version for apps that already have a wingetId
Find-AppInstallers.ps1	Searches local folders for likely installer files
Prepare-AppInstallers.ps1	Copies or downloads installers from local paths and winget into staged-installers/ and writes output/install-queue.json
Get-ManualSourceQueue.ps1	Produces a queue of unresolved apps that still need vendor, Microsoft, OEM, or archive lookup
Download-ManualReferenceInstallers.ps1	Attempts to download installers from cataloged manual reference URLs into staged-installers/ and writes output/manual-download-queue.json
Set-AppStatus.ps1	Manually overrides one catalog entry
Install-PreparedApps.ps1	Generates an install plan and can run supported installers

Catalog Model

Each app entry in catalog/apps.json includes fields such as:

• name, publisher, expectedVersion
• desired and status
• detection.* for last-seen metadata and match names
• classification.* for bucket, recommendation, and rationale
• latest.* for current package version information
• installer.* for local candidates, selected installer path, winget metadata, manual-source hints, staging path, and readiness
• notes for any manual annotations

This structure is designed to keep all reinstall-related decisions close to the application record they affect.

Because catalog/apps.json is ignored by Git, this catalog is treated as local working state rather than a shared repository artifact.

Reports And Generated Files

The scripts can generate artifacts such as:

• output/preflight-report.json
• output/sync-report.json
• output/winget-report.json
• output/latest-version-report.json
• output/classification-report.json
• output/installer-report.json
• output/manual-source-queue.json
• output/manual-download-queue.json
• output/install-queue.json
• output/install-plan.json
• output/install-log.json
• output/validation-report.json
• staged-installers/

These files are intended as working data, not long-term source files.

Tests

The repository includes Pester tests under tests/.

Run them from the repository root:

Invoke-Pester .\tests

The checked-in tests use modern Should -Be assertions, so use Pester 5 or newer rather than the older Windows PowerShell inbox Pester 3.x module.

Current coverage is targeted rather than comprehensive. The checked-in tests validate catalog structure handling and install-plan behavior for ready MSI items and unsupported EXE silent-install cases.

Safety Notes

• Prefer Install-PreparedApps.ps1 -Mode Plan before any execution.
• EXE installers may require explicit silent arguments in installer.installArgs before they are safe to run unattended.
• Review winget matches and local installer candidates before trusting them as final.
• Device drivers, OEM utilities, and licensed software often need vendor-specific handling even when they appear in the catalog.

Privacy And Publishing Notes

This workflow operates on machine-derived data. Files such as installed-programs.csv, catalog/apps.json, generated reports, and staged installer paths can reveal:

• installed software inventory
• usernames and local file paths
• internal tooling names
• vendor portals or licensed software usage

The tracked installed-programs.csv in this repository is only a generic sample. Replace it with a real export for actual use, and do not commit your machine-specific replacement back to a public repository.

If you use this repository publicly, treat generated files and real inventory exports as environment-specific data and sanitize or exclude them before publishing.

Additional Docs

• docs/project-evaluation.md documents the current project scope, strengths, weaknesses, and verification limits for this checkout

License

MIT

Limitations

• The repository is Windows-focused.
• winget matching is heuristic and may need manual correction.
• Automatic execution currently covers msi packages, winget install, and exe installers when silent arguments are known.
• Some applications will always remain manual because they are licensed, OEM-specific, legacy, or not available from a trusted package source.