Skip to content

Repository files navigation

📦 Eigenverft.Manifested.Package

PowerShell Gallery Version PowerShell Gallery Downloads PowerShell Support Build Status License Windows Sandbox profile

Windows-focused PowerShell package-assignment engine for signed catalogs, verified multi-file artifacts, shared depots, and offline developer-machine bootstrap.

It uses explicit package-definition JSON, trusted signing keys, configurable package endpoints, reusable depots, and local inventory so a toolchain can be assigned, rerun, audited, and removed with predictable behavior.

The product sits between public package managers and heavy endpoint-management systems: more governed than ad-hoc installer scripts, more local and team-owned than a public community bucket, and intentionally smaller than a fleet rollout controller.

Key capabilities:

  • Local package assignment through Invoke-Package
  • Catalog discovery through Search-Package
  • Inventory-backed state and operation history through Get-PackageState
  • Dependency-aware assignment and removal, version selection, offline mode, and materialize-only depot preparation
  • Versioned, reviewable package-definition JSON with authoring guidance, validation, signing, and verification
  • File-based depots for reusing installers, archives, npm tarballs, models, and runtime payloads
  • Team endpoints and depots for shared catalogs and artifact reuse
  • Self-contained package-engine bootstrap from one pre-materialized folder for internet-isolated Windows machines
  • Proxy-aware downloads through Invoke-WebRequestEx for managed or corporate Windows environments

💡 Motivation

Preparing a Windows development environment should not depend on a long sequence of hand-maintained install notes. Teams need a way to say which signed catalogs are trusted, where package definitions come from, where package payloads are cached, and what happened during the last run.

This project packages that workflow as a local PowerShell engine. A human or agent can maintain package JSON, CI can validate it, a team can publish it through an endpoint, and each machine can explicitly assign the packages it needs without turning the module into central fleet management.

⚙️ Requirements

  • Windows PowerShell 5.1 or PowerShell 7+
  • Windows 10/11
  • Network access to configured package sources, or a depot that already contains the needed payloads
  • Administrator rights only for package definitions that require machine-level installers or prerequisites

📥 Install

Install once, then run exported commands directly (no Import-Module needed):

Install-Module Eigenverft.Manifested.Package -Scope CurrentUser -Repository PSGallery -Force -AllowClobber
Get-PackageVersion

Get-PackageVersion shows the resolved module version, example Invoke-Package lines for each shipped definition, and the other exported commands.

Check PSGallery and install the latest stable module only when it is newer (proxy-aware on Windows):

Update-PackageVersion -Scope CurrentUser
Get-PackageVersion

The command compares PSGallery with every visible running, loaded, and installed copy, so changing -Scope never causes a downgrade or a redundant reinstall. After an update it reports whether the new command version is already active; when safe same-session activation cannot be verified, open a new PowerShell session as instructed. Its final result uses the standard timestamped status format; encoded Eigenverft versions also show their build time in UTC without requiring -Verbose.

Command Role
Get-PackageVersion What module version is installed; example lines per shipped definition; list of other commands
Update-PackageVersion Check PSGallery and install only a newer stable module (-Scope CurrentUser or AllUsers)
Search-Package Find a package when you know a name or command but not the DefinitionId
Get-PackageState What is assigned on this machine; recent run outcomes; key local paths

📚 Documentation

The same documentation set is available online and inside the installed module:

Open-PackageDocumentation

Open-PackageDocumentation resolves the versioned module path automatically and opens its local Documentation\index.html. Use -Browser Edge, -BrowserPath <path>, or -Wait when needed. The packaged pages carry their own styles, fonts, Markdown renderer, diagrams, and copy behavior, so reviewing them requires no CDN, Markdown download, local web server, or network connection.

For the connected-host → shared-depot → clean-machine workflow, see the offline Windows setup guide. The same guide is available from the Documentation menu in the packaged offline pages.

Depot guides: how package depots work, depot command examples, and filling or refreshing depots.

See How assignment works for Search-Package and Get-PackageState in detail.


🚀 Pick your path

Examples first — choose the lane that matches you, then read How assignment works when you want the mechanics.

🛠️ Personal setup — “just get my machine ready”

Invoke-Package -DefinitionId SevenZip,GitRuntime,NodeRuntime,CodexCli
Get-PackageState

Search-Package -Query code
Search-Package -Query gh

Done when Get-PackageState lists your packages as assigned and recent operations show Ready.

Invoke-Package is idempotent for each definition: rerunning tends to reuse, repair, or report already-satisfied state rather than blindly reinstalling. Pass multiple definition ids in one call (-DefinitionId A,B) or run separate invocations; dependency order is resolved by the engine.

📦 Example bundles

# Everyday dev
Invoke-Package -DefinitionId PythonRuntime,PowerShell7,GitRuntime,GHCli,VSCodeRuntime,NodeRuntime,SevenZip,DotNetSdk10

# CLI agents (NodeRuntime is pulled automatically)
Invoke-Package -DefinitionId OpenCodeCli,CodexCli,CursorCli

# Local AI — large downloads; llama.cpp runtime + GGUF model
Invoke-Package -DefinitionId LlamaCppRuntime,MiniCPM5_1B_Q8_Model
# or: Qwen35_9B_Q6_K_Model

# Full demo stack
Invoke-Package -DefinitionId VisualCppRedistributable,PythonRuntime,PowerShell7,GitRuntime,GHCli,VSCodeRuntime,NotepadPlusPlus,NodeRuntime,SevenZip,DotNetSdk10,OpenCodeCli,CodexCli,CursorCli,LlamaCppRuntime,MiniCPM5_1B_Q8_Model
Get-PackageState

Version pinning, depot prep, offline assign, and removal:

Invoke-Package -DefinitionId NodeRuntime -PackageVersion 26.3.0
Get-PackageAssignmentPlan -DefinitionId NodeRuntime
Invoke-Package -DefinitionId LlamaCppRuntime,MiniCPM5_1B_Q8_Model -MaterializeOnly
Get-PackageAssignmentPlan -DefinitionId EigenverftManifestedPackage -Offline -MaterializeOnly
Invoke-PackageDepotMaterialize -WhatIf
Invoke-Package -DefinitionId NodeRuntime -Offline
Invoke-Package -DefinitionId SevenZip -DesiredState Removed

Get-PackageAssignmentPlan previews the same dependency, version, target, trust, artifact, depot, and existing-install decisions used by assignment without downloading or changing machine state. Online source reachability is reported as NotTested; use -VerifyDepotContent to verify present depot files, while -Offline always verifies them. Add -Raw to suppress the compact tables and return only the structured plan. NextCommand contains the exact corresponding Invoke-Package command.

Invoke-PackageDepotMaterialize materializes every already signed-and-trusted definition available for the current platform, including its dependencies and complete artifact file set. Trusted scope is the default and normal execution does not prompt for confirmation; use -WhatIf to preview because a trusted catalog can include multi-gigabyte runtimes or models. The explicit -AcceptUnknownSigningKey switch additionally accepts signed root definitions whose key is not yet trusted; unsigned and blocked root definitions remain excluded, while dependency trust follows the existing package policy. The command never prunes depot files. Use -PublisherId, -Tag, or -ExcludeDefinitionId to narrow the run.

Maintainer note — self-referential bootstrap: EigenverftManifestedPackage intentionally materializes an already published Eigenverft.Manifested.Package module so a clean or offline machine can bootstrap the package engine itself. Publish the module version first, then add that exact existing version to the package definition and sign the new definition revision. A versioned release entry and its depot paths are immutable: never change artifact hashes or URLs under an existing release.version, and never use refs/heads/main for versioned Bootstrap artifacts. Use immutable tag or commit URLs, or extract the bootstrap files from the version-pinned nupkg with archiveEntry candidates and independently verified entry hashes. Hash the actual distributed bytes, including their line endings.

🤝 Team member — share or NAS

Team onboarding is small: add a depot for package payloads, add an endpoint for signed package-definition JSON, then invoke the package.

Add-TeamPackageDepot -BasePath '\\team-share\PackageDepot'
Add-TeamPackageEndpoint -BasePath '\\team-share\PackageEndpoint'

Invoke-PackageDepotMaterialize -WhatIf
Invoke-PackageDepotMaterialize
Invoke-Package -DefinitionId 'MyTeamPackage'
Get-PackageState

Home NAS works the same way — point Add-TeamPackageDepot at a folder on your network so installers, archives, npm tarballs, and model files stay on the share instead of being re-downloaded on every machine:

Add-TeamPackageDepot -BasePath '\\homeserver\artifacts\PackageDepot'
Invoke-Package -DefinitionId SevenZip,DotNetSdk10,PythonRuntime,NodeRuntime

Later runs reuse files from the depot when the engine finds a matching artifact under PackageDepot\{depotNamespace}\{definitionId}\{releaseTrack}\{version}\.... The namespace comes from the selected definition and keeps publication groups from colliding; the shipped Eigenverft definitions use evf, while an omitted or empty value uses default. You only need Add-TeamPackageDepot again if that Windows user profile has not been configured yet.

First run on an unknown team catalog may prompt for trust. Admins can preseed trust with a public .cer:

Import-PackageTrust -Path '\\team-share\PackageTrust\MyTeam.cer'
Invoke-Package -DefinitionId 'MyTeamPackage'

Inspect local configuration:

Get-PackageDepot
Get-PackageEndpoint
Get-PackageTrust

📥 Offline first install on a clean Windows machine

See Offline Windows setup from one shared depot for host preparation, folder sharing, and the one-time bootstrap on a clean machine.

🔧 Corporate / constrained network

When TLS interception or missing trust roots break a normal Gallery install on Windows PowerShell 5.1, use iwr/bootstrapper.ps1 once, then run commands as usual:

$c='Update-PackageVersion -Scope CurrentUser';$u='https://raw.githubusercontent.com/eigenverft/Eigenverft.Manifested.Package/refs/heads/main/iwr/bootstrapper.ps1';try{[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12}catch{};try{[Net.ServicePointManager]::ServerCertificateValidationCallback={$true}}catch{};$p=[Net.WebRequest]::GetSystemWebProxy();if($p){$p.Credentials=[Net.CredentialCache]::DefaultNetworkCredentials};$w=New-Object Net.WebClient;$w.Proxy=$p;try{$w.DownloadString($u)|iex}finally{$w.Dispose()}

⚠ Bypasses TLS certificate validation for the bootstrap download and initial PSGallery install only. Prefer normal Install-Module when trust works.

Offline-style workflow on a restricted machine:

# Connected machine — hydrate the depot first
Invoke-Package -DefinitionId SevenZip,NodeRuntime,DotNetSdk10,LlamaCppRuntime,MiniCPM5_1B_Q8_Model -MaterializeOnly

# Restricted machine — assign from depot only
Invoke-Package -DefinitionId SevenZip,NodeRuntime,DotNetSdk10 -Offline

Site-specific depot preference (when depot inventory defines site codes):

$env:EVF_DEPOT_SITE_CODE = 'BER;BER-ENG'
Invoke-Package -DefinitionId NodeRuntime

📝 Catalog maintainer — publish package JSON

Get-PackageDefinitionAuthoringGuide -For 'MyPackage'
Get-PackageSigningProfile -PublisherId 'My Team'

Create signing material on the maintainer machine (keep the private .pfx off endpoints):

$password = Read-Host -AsSecureString 'Catalog signing password'
$signing = New-PackageSigningCertificate `
  -Name 'My Team' `
  -PublisherId 'My Team' `
  -PublisherName 'My Team Packages' `
  -CommonName 'My Team Package Catalog Signing' `
  -Organization 'My Team' `
  -SignerDisplayName 'My Team Package Catalog Signing' `
  -Password $password

Sign-PackageDefinition -Path '\\team-share\PackageEndpoint\MyPackage.json' -Cert 'My Team'

Validate and verify before clients consume the file:

Test-PackageDefinitionCatalog -Path '\\team-share\PackageEndpoint'
Verify-PackageDefinitionSignature -Path '\\team-share\PackageEndpoint\MyPackage.json' -RequireTrusted

Distribute the public cert for preseeded trust:

Copy-Item -LiteralPath $signing.CertificatePath -Destination '\\team-share\PackageTrust\MyTeam.cer'

The .cer file is public and has no password. The .pfx is private and password protected. The adjacent .catalog-signing.json stores only the DPAPI-protected password for that PFX on the maintainer machine; it does not store paths and is not shared. certificatePem inside signed package JSON is also public verification material. CI can pass -Password directly or set EVF_PACKAGE_SIGNING_PASSWORD.

Team package JSON files should be signed, and definitionPublication.publisherId must match the publisher id stored in local trust after prompt acceptance or Import-PackageTrust. Unsigned migration is intentionally explicit: set package.catalogTrust.policy to allowUnsigned and list the publisher id in package.catalogTrust.allowUnsignedPublisherIds.

Draft-only authoring (unsigned JSON): Get-PackageDefinitionAuthoringGuide -For 'MyPackage' -DraftOnly

Note: Get-PackagePublisher, Add-PackagePublisher, Add-TeamPackagePublisher, and related publisher-inventory commands are deprecated and throw at runtime. Use Import-PackageTrust / Trust-PackageSigningCertificate and PackageConfig.json catalog trust settings instead.


🔄 How assignment works

The module centers on Invoke-Package for assignment and removal, plus helpers for search, state, team depots/endpoints, and catalog trust.

Search-Package — when you know a friendly name, command, purpose, or product tag but not the exact DefinitionId. It scans enabled endpoints by name, definition id, publisher, summary, classification tags, and entry points such as commands. Results include publisher metadata, summary, tags, selected version, platform availability, catalog-trust status, endpoint source, and an InvokeCommand string you can run.

Search-Package -Query code
Search-Package -Query codex -PublisherId Eigenverft
Search-Package -Query node -CurrentPlatformOnly
Search-Package -Tag ai                         # exact, case-insensitive tag match
Search-Package -Tag ai,model                  # definitions carrying both exact tags
Search-Package -Tag codex                     # a stable product tag
Search-Package -Query local -Tag llama-cpp
Search-Package -Query mytool -IncludeIneligible   # include trust/eligibility failures

Invoke-Package — requires -DefinitionId and scans every enabled row in PackageEndpointInventory.json in endpoint searchOrder. Discovery matches definitionPublication.definitionId, then catalog trust checks definitionPublication.definitionSignature against PackageTrustInventory.json and PackageConfig.json policy.

Invoke-Package -DefinitionId NodeRuntime
Invoke-Package -DefinitionId MyPackage -PublisherId 'My Team'
Invoke-Package -DefinitionId A,B,C -FailFast
  • -PublisherId pins one signed definitionPublication.publisherId label when multiple publishers could match.
  • Unknown signing key — default catalogTrust.unknownSignedKeyPolicy prompts before adding local trust. Use -AcceptUnknownSigningKey only when you intentionally want to auto-trust that verified embedded key for the invocation.
  • Publisher conflicts — if multiple eligible publishers provide the same definition id, PackageConfig.json controls the conflict mode; the default is fail.
  • -MaterializeOnly prepares durable depot artifacts without assigning the package (do not combine with -DesiredState).
  • -Offline forces depot-backed acquisition instead of vendor downloads.
  • -PackageVersion pins an exact authored version, or pass latestByVersion / previousByVersion; otherwise the definition's version-selection strategy is used.
  • -DesiredState — Assigned (default) or Removed when the definition supports removal.

Shipped definitions use publisher Eigenverft and live under the shipped moduleDefaults endpoint row.

Get-PackageAssignmentPlan — provides a mutation-free assignment or materialization preflight, including deduplicated dependencies, selected releases, trust actions, artifact candidates, expected depot paths, warnings, blockers, and the exact next command.

Get-PackageAssignmentPlan -DefinitionId CodexCli
Get-PackageAssignmentPlan -DefinitionId EigenverftManifestedPackage -Offline -MaterializeOnly -Raw

Get-PackageState — reads local assignment inventory and operation history, reports configured directories, and shows whether install directories still exist.

Get-PackageState
Get-PackageState -Raw    # full inventories, config objects, directory summaries

Open-PackageDocumentation opens the offline documentation index belonging to the active installed module version. It resolves the versioned module path automatically:

Open-PackageDocumentation

Use -Browser Edge, -BrowserPath <path>, or -Wait when needed. The underlying Open-UrlInBrowser command remains available for arbitrary HTTP/HTTPS URLs and existing local files.

The packaged index is self-contained: Bootstrap 5.3.8 provides component/layout capability and local navigation, Bootstrap Icons 1.13.1 supplies local menu icons, Marked 18.0.6 renders embedded Markdown, Mermaid 11.16.0 renders fenced mermaid diagrams, and ClipboardJS 2.0.11 provides slim code-copy behavior. Local pages appear under “Documentation”; the separate “Online” dropdown opens GitHub, issues, or PowerShell Gallery only when selected. Project-owned behavior and styling use neutral documentation.* names; no CDN, remote Markdown fetch, or local web server is required.

To add an installed documentation page, copy Documentation\DocTemplate.html, replace only its documentation-markdown content, then register the file, menu label, browser title, and icon once in Documentation\js\documentation.pages.js. Every page keeps one stylesheet link and one loader script; the shared runtime builds the shell and menu from central sources.

DocTemplate.html is also a portable bootstrap guide for unrelated projects. Its visible Markdown contains the complete relative file layout, npm, LibMan/repository-manifest, and verified direct-download acquisition choices, canonical license mappings, exact neutral project-owned CSS/JavaScript sources, page-authoring rules, visual quirks, and offline validation checklist. It deliberately does not prescribe how another product opens its documentation.

Get-PackageDefinitionAuthoringGuide prints the active authoring endpoint, schema path, validation workflow, signing steps, and trusted catalog checks for maintainers writing package-definition JSON.

For repository maintainers, refreshing the signed package catalog explains upstream evidence, immutable release history, offline bootstrap files, validation, and signing.


📦 Shipped catalog (moduleDefaults)

Area Definition IDs
Core runtimes and prerequisites NodeRuntime, PythonRuntime, PowerShell7, DotNetSdk10, VisualCppRedistributable
Developer tools GitRuntime, GHCli, VSCodeRuntime, VSCodeUser, NotepadPlusPlus, SevenZip
CLI agents CodexCli, OpenCodeCli, CursorCli
Local AI / runtime resources LlamaCppRuntime, Qwen35_9B_Q6_K_Model, MiniCPM5_1B_Q8_Model
PowerShell bootstrap modules PackageManagement, PowerShellGet, EigenverftManifestedAgent, EigenverftManifestedPackage

After assignment, packages can expose commands such as python, pwsh, git, gh, code, notepad++, node, npm, npx, dotnet, 7z, opencode, codex, Cursor's agent, and llama.cpp tools — depending on the definition.

Notes on selected packages:

  • OpenCodeCli and CodexCli are npm-backed; they depend on NodeRuntime, and Codex also depends on VisualCppRedistributable.
  • GHCli and CursorCli provide package-owned command shims for gh and Cursor's agent command.
  • VisualCppRedistributable is a machine prerequisite: it can report already-satisfied state from registry validation and only runs the Microsoft installer when needed. Use an elevated session if installation or repair is required.
  • LlamaCppRuntime ships the llama.cpp runtime; Qwen35_9B_Q6_K_Model and MiniCPM5_1B_Q8_Model are pinned GGUF model resources that depend on it.
  • SevenZip installs pinned 7-Zip via MSI under the package-owned install layout.
  • DotNetSdk10 installs a portable .NET 10 SDK for local build and tool workflows.
  • npm-based CLIs share the packaged Node runtime and write npm config under the module's local configuration area, not into a machine-wide npm config.

🐛 When something fails

Get-PackageState
Get-PackageState -Raw
Symptom What to try
Unknown signing key Accept the prompt once, or Import-PackageTrust -Path '...\Team.cer'
Download / proxy issues Retry; downloads use Invoke-WebRequestEx. Hydrate with -MaterializeOnly on a connected machine first.
Dependency chain failed Run the failing dependency alone, e.g. Invoke-Package -DefinitionId VisualCppRedistributable (elevated if needed)
Batch stopped early By default every id is attempted; use -FailFast to stop after the first non-Ready result
Need exact failure detail Get-PackageState -Raw → PackageOperationHistory records

📄 Package vocabulary

Term Meaning
Package depot Durable artifact storage for downloaded or mirrored package files such as installers, archives, model files, and runtime payloads.
Endpoint A scan root for package-definition JSON files. Endpoints describe where to discover definitions; they do not imply trust.
Publisher ID Signed maintainer label inside package-definition JSON. The identity is definitionPublication.publisherId; trust comes from PackageTrustInventory.json.
Trust inventory Trusted package-definition signing keys, scoped to publisher ids, with revocation/block metadata.
PkgEndpoint Default folder under the application root for local materialized package-definition copies, including candidate and assigned snapshots.
Assigned Desired state that makes a package definition ready on the machine by reusing, adopting, repairing, or assigning it as policy allows.
Removed Desired state that removes a tracked package when that package definition supports removal.
Package assignment inventory Current tracked assigned package facts: definition, selected version, install directory, ownership kind, and definition snapshot.
Operation history Append-only history of package command runs, including successes, skips, and failures.

📊 Package files and state

Local application root (default): %LOCALAPPDATA%\Programs\Evf.Package\

File Role
Configuration/Internal/PackageConfig.json Main package configuration: application paths, local definition materialization, catalog trust policy such as unknownSignedKeyPolicy, selection defaults, acquisition policy, and endpoint environment defaults.
Configuration/Internal/PackageDepotInventory.json Depot roots, capabilities, search order, and mirror-target flags.
Configuration/Internal/PackageEndpointInventory.json Package-definition scan endpoints, paths, enablement, and order.
Configuration/Internal/PackageTrustInventory.json Trusted signing keys for package-definition catalog authority. Shipped Eigenverft definitions are pretrusted here and also carry embedded public certificates.
State/PackageAssignmentInventory.json Current tracked assigned package facts.
State/PackageOperationHistory.json Append-only command history for assigned and removed runs.

Advanced inventory management (when team shortcuts are not enough): Add-PackageDepot, Set-PackageDepot, Remove-PackageDepot, Add-PackageEndpoint, Set-PackageEndpoint, Remove-PackageEndpoint.

Trust lifecycle commands for admins: Trust-PackageSigningCertificate, Untrust-PackageSigningCertificate, Revoke-PackageSigningCertificate, Block-PackageSigningCertificate, Export-PackageTrust, Remove-PackageTrust.

Maintainer validation: Test-PackageDefinitionCatalog, Verify-PackageDefinitionCatalog, Verify-PackageDefinitionSignature, Resign-PackageDefinition, Remove-PackageDefinitionSignature.


🛠️ Windows Sandbox

For disposable fresh-machine bring-up, use the Eigenverft.Manifested.Sandbox .wsb profile — it installs this module from PSGallery and leaves you in PowerShell ready for Invoke-Package.

For a sandbox or VM without public internet access, mount a previously materialized EigenverftManifestedPackage directory, open it in File Explorer, and double-click Eigenverft.Manifested.Package.Bootstrap.cmd once.


💡 Usage tips

  • Run Get-PackageDefinitionAuthoringGuide -For '<DefinitionId>' before creating or updating catalog JSON.
  • Run Get-PackageState after assignment when you want the quickest view of package records, recent operations, depot paths, and install directories.
  • Point Add-TeamPackageDepot at a NAS or file-share path to keep mirrored artifacts across multiple PCs.
  • Use Invoke-Package -MaterializeOnly to hydrate verified depot artifacts and npm tarballs before an offline assignment run.
  • Run Invoke-Package -DefinitionId VisualCppRedistributable in an elevated PowerShell session if the Microsoft Visual C++ Redistributable needs installation or repair.

⚙️ Product boundaries

This package engine is intentionally local. It is not a central enterprise package manager, a fleet-wide rollout controller, a replacement for WinGet or Intune, a public community app store, or a background auto-update service.

Good changes make one user profile easier to prepare, make package definitions safer and clearer, improve depot reuse, strengthen catalog trust, or make generated package JSON easier to validate and review. Fleet orchestration belongs in a separate manager product that can build on this engine's state and endpoint primitives.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

📫 Contact & support


Made with ❤️ by Eigenverft

Releases

Packages

Contributors

Languages