Add an execution engine for manifest-declared Installation Instructions (PreInstallSteps/PostInstallSteps)

[undead2146]

Problem

ContentManifest.InstallationInstructions (PreInstallSteps / PostInstallSteps) exists as a per-manifest, publisher-agnostic hook for installation-time actions, but nothing in the codebase executes it. ContentManifestBuilder.AddPreInstallStep / AddPostInstallStep are the only writers; there is no reader anywhere in the pipeline.

It is also not reliably carried through delivery today:

• CommunityOutpostDeliverer, GitHubManifestFactory, SuperHackersManifestFactory, and CommunityOutpostManifestFactory forward the full InstallationInstructions object.
• HttpContentDeliverer and FileSystemDeliverer only forward WorkspaceStrategy via WithInstallationInstructions(workspaceStrategy), silently dropping any Pre/PostInstallSteps set upstream.

Raised in #336: GeneralsOnline's 060526_QFE1 portable needs a one-time step after extraction (run EasyAntiCheat_EOS_Setup.exe if not already installed) before the content is usable. That need is generic — any publisher may eventually need to run an installer, remove a stale file, or rename an extracted artifact once, at acquisition time — not GeneralsOnline-specific.

Why a generic executor needs care, not just wiring

InstallationStep today is Name + free-form Command + free-form Arguments + WorkingDirectory + RequiresElevation. Executing that as-is means any deliverer — including GitHub-sourced releases and other third-party providers — can declare an elevated, arbitrary command in manifest data. That is a real trust-boundary gap, not a hypothetical one, and it should not be closed by simply adding a generic foreach (var step in instructions.PostInstallSteps) Process.Start(...).

Proposed approach

• Replace (or extend) InstallationStep's free-form Command/Arguments with a closed, typed Kind (e.g. RunVerifiedInstaller, RemoveFile, RenameFile), each with its own structured parameters, so the executor is auditable rather than "run anything."
• Restrict any file a step references (installer, target file) to a path that resolves inside the manifest's own Files list (content-addressable, hash-verified) and inside the delivered/workspace directory — the same containment check GameLauncher already applies to the main executable path.
• Fix HttpContentDeliverer / FileSystemDeliverer to forward Pre/PostInstallSteps, not just WorkspaceStrategy.
• Add an InstallationInstructionsService (or similar) invoked once per content acquisition, after a deliverer finishes producing files, that enumerates and executes a manifest's PostInstallSteps.
• Decide, and gate behind an allowlist if needed, which publishers are trusted to declare executable steps at all until this has had a security pass — see the Security & Integrity Validation milestone.

Acceptance criteria

• A manifest's PostInstallSteps survive every delivery path unchanged, including HttpContentDeliverer and FileSystemDeliverer.
• A generic service executes typed, closed-kind steps only; there is no path from manifest data to an arbitrary shell command.
• GeneralsOnlineManifestFactory can declare "run EasyAntiCheat_EOS_Setup.exe if not installed" as a PostInstallStep and have it actually execute once, at acquisition time.

Explicitly out of scope

• Per-launch verification. Once content is in CAS, later launches and other profiles reuse it without re-running the deliverer, so a one-time acquisition-time step can never be the sole gate for something whose state can drift outside GenHub (e.g. EAC being uninstalled externally). That is a distinct, always-on check and is tracked as a compiled IGameLaunchPrerequisite in GeneralsOnline Easy Anti-Cheat update breaks launch: wrong executable, missing EAC install step #336, not here.

Related

• GeneralsOnline Easy Anti-Cheat update breaks launch: wrong executable, missing EAC install step #336 — GeneralsOnline EAC breakage; motivating case for this issue, and where the per-launch counterpart (IGameLaunchPrerequisite / GeneralsOnlineEacLaunchPrerequisite) is tracked.

[coderabbitai]

Coding Plan

Summary

• Convert InstallationStep from a free-form command into a closed Kind-based discriminated model so the executor can only perform an auditable, enumerated set of operations.
• Fix HttpContentDeliverer/FileSystemDeliverer (and GeneralsOnline's manifest rebuild) to forward the full InstallationInstructions object so declared steps survive every delivery path.
• Add a single IInstallationInstructionsService, hooked into BaseContentProvider.PrepareContentAsync, that validates each step's target against the manifest Files list (containment + hash) and a publisher allowlist before executing, guaranteeing one-time acquisition-time execution.
• Declare the GeneralsOnline EAC installer as a RunVerifiedInstaller post-install step to validate the mechanism against the motivating case.

Design Choices

Design Choice 1: Should InstallationStep be replaced with a typed model or extended alongside the free-form fields?

Options Considered:

1. Replace the free-form Command/Arguments with a required Kind + per-kind structured fields, removing the arbitrary-command surface entirely.
2. Keep Command/Arguments and add Kind as an additive field, ignoring free-form fields at execution time.

Chosen Option: 1

Rationale: The ticket explicitly wants "no path from manifest data to an arbitrary shell command," and the absence of call sites means there is nothing to migrate, so leaving the free-form fields would only preserve the gap.

Design Choice 2: How should RequiresElevation be honored for RunVerifiedInstaller given no elevation infrastructure exists?

Options Considered:

1. Introduce a minimal Windows-only elevated launch path (ProcessStartInfo { UseShellExecute = true, Verb = "runas" }) inside the executor, treating non-Windows elevation as unsupported/failed for now.
2. Ignore RequiresElevation entirely and always launch non-elevated.

Chosen Option: 1

Rationale: It satisfies the concrete EAC case on the primary platform while keeping the surface small; a full cross-platform elevation abstraction is deferred as it is not required by the acceptance criteria.

Design Choice 3: How is "run EasyAntiCheat_EOS_Setup.exe if not already installed" made idempotent?

Options Considered:

1. Rely on acquisition-time = once semantics plus the installer's own idempotency (EAC setup is safe to re-run), with no additional state tracking in the engine.
2. Add a persisted "step already executed" marker/state store consulted before each run.

Chosen Option: 1

Rationale: Per the ticket, per-launch/drift detection is explicitly out of scope (tracked in #336 as IGameLaunchPrerequisite), so the engine only guarantees one-time acquisition-time execution and does not own long-lived installed-state tracking.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Typed, auditable installation-step model

This phase redesigns the data model so a step declares a closed Kind with structured, per-kind parameters instead of a free-form command, and updates the builder/interface so the fluent API can no longer emit arbitrary commands. This is the foundation that makes the executor auditable.

Task 1: Introduce the InstallationStepKind enum

Define the closed set of executable step types.

• Add a new enum under GenHub/GenHub.Core/Models/Enums/ named InstallationStepKind with members for the supported operations (e.g. RunVerifiedInstaller, RemoveFile, RenameFile) plus an Unknown = 0 sentinel.
• Follow the folder's conventions: file-scoped namespace GenHub.Core.Models.Enums;, a type-level <summary>, and a per-member <summary> describing each kind's behavior, mirroring ContentSourceType.cs.

Task 2: Redesign InstallationStep as a discriminated model

Replace the free-form command surface with typed, per-kind fields.

• Rework GenHub/GenHub.Core/Models/Manifest/InstallationStep.cs to carry a Kind discriminator plus nullable per-kind payload properties: a TargetRelativePath (the file the step acts on, expected to exist in ContentManifest.Files), a DestinationRelativePath (for RenameFile), an optional constrained Arguments list (for RunVerifiedInstaller), and the retained Name/RequiresElevation.
• Remove the free-form Command field (and WorkingDirectory if it becomes unused) so there is no arbitrary-command channel.
• Document each optional property with the "only used when Kind is X" convention used by ManifestFile's PatchSourceFile/PackageInfo, and apply JsonIgnore(WhenWritingNull) consistent with existing manifest models.
• InstallationInstructions.cs keeps PreInstallSteps/PostInstallSteps/WorkspaceStrategy/DownloadHash; only the element shape changes.

Task 3: Update the builder API to typed steps and stop clobbering instructions

Align the fluent builder with the typed model and remove the data-loss overwrite.

• Update AddPreInstallStep/AddPostInstallStep signatures in IContentManifestBuilder.cs and their implementations in ContentManifestBuilder.cs to accept a Kind plus the structured parameters instead of a free-form command string.
• Add a builder path that preserves an entire InstallationInstructions object (either a new overload of WithInstallationInstructions accepting the full object, or by having the existing WorkspaceStrategy-only overload merge rather than replace), so callers no longer silently discard Pre/PostInstallSteps.
• Verify the passthrough/clone sites (CommunityOutpostManifestFactory, CommunityOutpostDeliverer, SuperHackersManifestFactory) still compile against the new element shape.

🤖 Prompt for AI agents

Implement Phase 1: redesign the installation-step data model into a closed,
typed Kind-based model, and update the builder API accordingly.

- Add a new enum `InstallationStepKind` under `GenHub/GenHub.Core/Models/Enums/`
with members for supported operations (`RunVerifiedInstaller`, `RemoveFile`,
`RenameFile`) plus an `Unknown = 0` sentinel. Use file-scoped `namespace
GenHub.Core.Models.Enums;`, a type-level `<summary>`, and per-member `<summary>`
docs, mirroring the style of `ContentSourceType.cs`.

- Rework `GenHub/GenHub.Core/Models/Manifest/InstallationStep.cs` to replace the
free-form `Command`/`Arguments` fields with a `Kind` discriminator plus nullable
per-kind payload properties: `TargetRelativePath` (file the step acts on,
expected to exist in `ContentManifest.Files`), `DestinationRelativePath` (for
`RenameFile`), an optional constrained `Arguments` list (for
`RunVerifiedInstaller`), and retained `Name`/`RequiresElevation`. Remove the
free-form `Command` field (and `WorkingDirectory` if unused) so there's no
arbitrary-command channel. Document each optional property with the "only used
when Kind is X" convention used by `ManifestFile`'s
`PatchSourceFile`/`PackageInfo`, and apply `JsonIgnore(WhenWritingNull)`
consistent with existing manifest models. Keep `InstallationInstructions.cs`'s
`PreInstallSteps`/`PostInstallSteps`/`WorkspaceStrategy`/`DownloadHash`
unchanged — only the element shape changes.

- Update `AddPreInstallStep`/`AddPostInstallStep` signatures in
`IContentManifestBuilder.cs` and their implementations in
`ContentManifestBuilder.cs` to accept a `Kind` plus structured parameters
instead of a free-form command string. Add a builder path that preserves an
entire `InstallationInstructions` object — either a new overload of
`WithInstallationInstructions` accepting the full object, or by having the
existing `WorkspaceStrategy`-only overload merge rather than replace — so
callers no longer silently discard `Pre/PostInstallSteps`.

- Verify that passthrough/clone sites (`CommunityOutpostManifestFactory`,
`CommunityOutpostDeliverer`, `SuperHackersManifestFactory`) still compile
against the new element shape.

Phase 2: Preserve installation steps across every delivery path

This phase closes the delivery gap so steps set upstream are never dropped, satisfying the "survive every delivery path unchanged" acceptance criterion.

Task 1: Forward full instructions in HTTP and FileSystem deliverers

Stop the WorkspaceStrategy-only forwarding that discards steps.

• In FileSystemDeliverer.cs and HttpContentDeliverer.cs, replace the WithInstallationInstructions(packageManifest.InstallationInstructions.WorkspaceStrategy) calls with propagation of the entire InstallationInstructions object onto the delivered manifest, mirroring CommunityOutpostDeliverer's direct-assignment pattern (or the new full-object builder overload from Task 1.3).

Task 2: Ensure GeneralsOnline preserves instructions through its manifest rebuild

GeneralsOnline currently omits InstallationInstructions when it reconstructs manifests.

• In GeneralsOnlineManifestFactory.cs, ensure the ContentManifest rebuilt inside UpdateManifestsWithExtractedFiles (and the variant/mappack constructors) carries InstallationInstructions forward rather than defaulting to an empty object, so steps declared in Phase 4 survive.

🤖 Prompt for AI agents

Implement Phase 2: fix delivery paths so declared installation steps are never
dropped when manifests pass through deliverers.

- In `FileSystemDeliverer.cs` and `HttpContentDeliverer.cs`, replace the
`WithInstallationInstructions(packageManifest.InstallationInstructions.WorkspaceStrategy)`
calls with propagation of the entire `InstallationInstructions` object onto the
delivered manifest. Mirror `CommunityOutpostDeliverer`'s direct-assignment
pattern (or use the new full-object builder overload introduced in Phase 1, Task
1.3) so the whole object — including `PreInstallSteps`/`PostInstallSteps` — is
preserved rather than overwritten.

- In `GeneralsOnlineManifestFactory.cs`, ensure the `ContentManifest` rebuilt
inside `UpdateManifestsWithExtractedFiles` (and the variant/mappack
constructors) carries `InstallationInstructions` forward rather than defaulting
to an empty object, so that steps declared later (Phase 4) survive the rebuild.

Phase 3: Installation instructions execution engine

This phase adds the reader/executor: a single service invoked once per acquisition that validates and runs typed steps against the delivered directory, with containment, hash verification, and a publisher trust gate.

Task 1: Add a shared path-containment helper

Provide a single, safe containment check for the executor (and future reuse).

• Add an IsPathContainedIn(candidatePath, containerDirectory) helper to GenHub/GenHub.Core/Helpers/PathHelper.cs, using the safer Path.GetFullPath + trailing-separator StartsWith(OrdinalIgnoreCase) variant from ContentValidator to avoid sibling-prefix false positives.

Task 2: Define and implement IInstallationInstructionsService

Create the typed executor following existing validator/service conventions.

• Add IInstallationInstructionsService under GenHub.Core/Interfaces/Content/ (or a Manifest interfaces folder) exposing an async method that takes the manifest, the delivered/working directory, optional progress, and a cancellation token, returning an OperationResult<T> (execution summary) using the standard CreateSuccess/CreateFailure factories.
• Implement it under GenHub/GenHub/Features/Content/Services/ (or Features/Manifest/), following ContentValidator's conventions (primary-constructor DI, guard clauses, ILogger debug/error logging, progress reporting).
• For each PostInstallStep, resolve TargetRelativePath/DestinationRelativePath against manifest.Files (must be a declared entry), verify containment inside the delivered directory via the Task 3.1 helper, and hash-verify the referenced file against its ManifestFile.Hash using IFileOperationsService.VerifyFileHashAsync.
• Dispatch on Kind with a switch that fails (NotSupported) on unknown kinds; implement RemoveFile/RenameFile as filesystem operations and RunVerifiedInstaller via a ProcessStartInfo launch mirroring GameProcessManager (validated arguments only, honoring RequiresElevation per Assumption 2), awaiting completion and mapping exit codes/Win32Exception/InvalidOperationException to CreateFailure results.
• Gate RunVerifiedInstaller (and any executable step) behind a publisher allowlist: only manifests whose Publisher is on a trusted list may declare executable steps; reject (fail the step) otherwise, per the ticket's trust-boundary requirement.

Task 3: Register the service and hook it into the acquisition pipeline

Ensure the executor runs exactly once per acquisition for all providers.

• Register IInstallationInstructionsService as a singleton in ContentPipelineModule.cs (alongside IContentValidator in AddSharedComponents/AddCoreServices).
• Inject it into BaseContentProvider's primary constructor (mirroring IContentValidator) and invoke it in PrepareContentAsync immediately after PrepareContentInternalAsync succeeds and before/around the file-validation step, passing result.Data and the working directory. Update the concrete providers' constructors to forward the new dependency to base(...).
• This location guarantees "once, at acquisition time" semantics since it is only reachable via AcquireContentAsync, which callers gate on manifest-pool presence.

🤖 Prompt for AI agents

Implement Phase 3: build the installation-instructions execution engine that
reads and runs typed post-install steps once per content acquisition.

- Add an `IsPathContainedIn(candidatePath, containerDirectory)` helper to
`GenHub/GenHub.Core/Helpers/PathHelper.cs`, using the safer `Path.GetFullPath` +
trailing-separator `StartsWith(OrdinalIgnoreCase)` variant from
`ContentValidator` to avoid sibling-prefix false positives.

- Define `IInstallationInstructionsService` under
`GenHub.Core/Interfaces/Content/` (or a `Manifest` interfaces folder), exposing
an async method that takes the manifest, the delivered/working directory,
optional progress, and a cancellation token, returning an `OperationResult<T>`
(execution summary) using the standard `CreateSuccess`/`CreateFailure`
factories.

- Implement the service under `GenHub/GenHub/Features/Content/Services/` (or
`Features/Manifest/`), following `ContentValidator`'s conventions:
primary-constructor DI, guard clauses, `ILogger` debug/error logging, and
progress reporting.

- For each `PostInstallStep`: resolve
`TargetRelativePath`/`DestinationRelativePath` against `manifest.Files` (must be
a declared entry), verify containment inside the delivered directory using the
new `PathHelper` helper, and hash-verify the referenced file against its
`ManifestFile.Hash` using `IFileOperationsService.VerifyFileHashAsync`.

- Dispatch execution on `Kind` via a `switch` statement that fails with
`NotSupported` on unknown kinds. Implement `RemoveFile`/`RenameFile` as
filesystem operations. Implement `RunVerifiedInstaller` via a `ProcessStartInfo`
launch mirroring `GameProcessManager` conventions, using only validated
arguments, honoring `RequiresElevation` (Windows-only elevated launch via
`UseShellExecute = true, Verb = "runas"`, per the elevation assumption),
awaiting completion, and mapping exit
codes/`Win32Exception`/`InvalidOperationException` to `CreateFailure` results.

- Gate `RunVerifiedInstaller` (and any executable step) behind a publisher
allowlist: only manifests whose `Publisher` is on a trusted list may declare
executable steps; otherwise reject/fail the step, satisfying the trust-boundary
requirement.

- Register `IInstallationInstructionsService` as a singleton in
`ContentPipelineModule.cs` alongside `IContentValidator` (in
`AddSharedComponents`/`AddCoreServices`).

- Inject the service into `BaseContentProvider`'s primary constructor (mirroring
`IContentValidator`) and invoke it inside `PrepareContentAsync` immediately
after `PrepareContentInternalAsync` succeeds and before/around the
file-validation step, passing `result.Data` and the working directory. Update
concrete providers' constructors to forward the new dependency to `base(...)`.
This ensures the engine runs exactly once per acquisition, since this code path
is only reachable via `AcquireContentAsync`.

Phase 4: GeneralsOnline EAC post-install step

This phase exercises the new mechanism end-to-end for the motivating case.

Declare the EAC setup step in the GeneralsOnline manifest

Add the concrete PostInstallStep so it executes at acquisition.

• In GeneralsOnlineManifestFactory.cs, add a RunVerifiedInstaller PostInstallStep targeting EasyAntiCheat_EOS_Setup.exe (which already falls through as a workspace ManifestFile), setting RequiresElevation as appropriate, on the client-variant manifests.
• Ensure the GeneralsOnline Publisher is added to the executor's trusted allowlist (Task 3.2) so the step is permitted to run.

🤖 Prompt for AI agents

Implement Phase 4: wire up the GeneralsOnline EAC installer as the first real
usage of the new post-install execution mechanism.

- In `GeneralsOnlineManifestFactory.cs`, add a `RunVerifiedInstaller`
`PostInstallStep` targeting `EasyAntiCheat_EOS_Setup.exe` (which already falls
through as a workspace `ManifestFile`), setting `RequiresElevation` as
appropriate, on the client-variant manifests.

- Ensure the GeneralsOnline `Publisher` value is added to the executor's trusted
publisher allowlist (established in Phase 3) so this executable step is
permitted to run.

Research

Content flows through IContentOrchestrator.AcquireContentAsync → IContentProvider.PrepareContentAsync (centralized in BaseContentProvider) → concrete PrepareContentInternalAsync (which invokes an IContentDeliverer) → CAS/manifest-pool storage.

ContentManifest.InstallationInstructions (with PreInstallSteps/PostInstallSteps as List<InstallationStep>) is populated by ContentManifestBuilder and various factories but is never read or executed anywhere.

InstallationStep is a free-form Command/Arguments/WorkingDirectory/RequiresElevation shape with no Kind discriminator and no link to ManifestFile. AddPreInstallStep/AddPostInstallStep have zero call sites today.

HttpContentDeliverer/FileSystemDeliverer call WithInstallationInstructions(WorkspaceStrategy), which overwrites the whole instructions object and drops steps; CommunityOutpostDeliverer/SuperHackersManifestFactory/CommunityOutpostManifestFactory correctly forward the full object.

Process launching conventions live in GameProcessManager/GameLauncher (no elevation implemented anywhere).

Path-containment checks are inlined in several places (GameLauncher, ContentValidator, ContentStorageService) with no shared helper; hash verification against ManifestFile.Hash is available via IFileOperationsService.VerifyFileHashAsync.

Results follow the OperationResult<T>/ResultBase CreateSuccess/CreateFailure convention; enums live under GenHub.Core/Models/Enums with per-member XML docs, and ManifestFile+ContentSourceType is the established "closed Kind + nullable per-kind payload" precedent.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: redesign the installation-step data model into a closed,
typed Kind-based model, and update the builder API accordingly.

- Add a new enum `InstallationStepKind` under `GenHub/GenHub.Core/Models/Enums/`
with members for supported operations (`RunVerifiedInstaller`, `RemoveFile`,
`RenameFile`) plus an `Unknown = 0` sentinel. Use file-scoped `namespace
GenHub.Core.Models.Enums;`, a type-level `<summary>`, and per-member `<summary>`
docs, mirroring the style of `ContentSourceType.cs`.

- Rework `GenHub/GenHub.Core/Models/Manifest/InstallationStep.cs` to replace the
free-form `Command`/`Arguments` fields with a `Kind` discriminator plus nullable
per-kind payload properties: `TargetRelativePath` (file the step acts on,
expected to exist in `ContentManifest.Files`), `DestinationRelativePath` (for
`RenameFile`), an optional constrained `Arguments` list (for
`RunVerifiedInstaller`), and retained `Name`/`RequiresElevation`. Remove the
free-form `Command` field (and `WorkingDirectory` if unused) so there's no
arbitrary-command channel. Document each optional property with the "only used
when Kind is X" convention used by `ManifestFile`'s
`PatchSourceFile`/`PackageInfo`, and apply `JsonIgnore(WhenWritingNull)`
consistent with existing manifest models. Keep `InstallationInstructions.cs`'s
`PreInstallSteps`/`PostInstallSteps`/`WorkspaceStrategy`/`DownloadHash`
unchanged — only the element shape changes.

- Update `AddPreInstallStep`/`AddPostInstallStep` signatures in
`IContentManifestBuilder.cs` and their implementations in
`ContentManifestBuilder.cs` to accept a `Kind` plus structured parameters
instead of a free-form command string. Add a builder path that preserves an
entire `InstallationInstructions` object — either a new overload of
`WithInstallationInstructions` accepting the full object, or by having the
existing `WorkspaceStrategy`-only overload merge rather than replace — so
callers no longer silently discard `Pre/PostInstallSteps`.

- Verify that passthrough/clone sites (`CommunityOutpostManifestFactory`,
`CommunityOutpostDeliverer`, `SuperHackersManifestFactory`) still compile
against the new element shape.
===============================================================================

Task: 2

Implement Phase 2: fix delivery paths so declared installation steps are never
dropped when manifests pass through deliverers.

- In `FileSystemDeliverer.cs` and `HttpContentDeliverer.cs`, replace the
`WithInstallationInstructions(packageManifest.InstallationInstructions.WorkspaceStrategy)`
calls with propagation of the entire `InstallationInstructions` object onto the
delivered manifest. Mirror `CommunityOutpostDeliverer`'s direct-assignment
pattern (or use the new full-object builder overload introduced in Phase 1, Task
1.3) so the whole object — including `PreInstallSteps`/`PostInstallSteps` — is
preserved rather than overwritten.

- In `GeneralsOnlineManifestFactory.cs`, ensure the `ContentManifest` rebuilt
inside `UpdateManifestsWithExtractedFiles` (and the variant/mappack
constructors) carries `InstallationInstructions` forward rather than defaulting
to an empty object, so that steps declared later (Phase 4) survive the rebuild.
===============================================================================

Task: 3

Implement Phase 3: build the installation-instructions execution engine that
reads and runs typed post-install steps once per content acquisition.

- Add an `IsPathContainedIn(candidatePath, containerDirectory)` helper to
`GenHub/GenHub.Core/Helpers/PathHelper.cs`, using the safer `Path.GetFullPath` +
trailing-separator `StartsWith(OrdinalIgnoreCase)` variant from
`ContentValidator` to avoid sibling-prefix false positives.

- Define `IInstallationInstructionsService` under
`GenHub.Core/Interfaces/Content/` (or a `Manifest` interfaces folder), exposing
an async method that takes the manifest, the delivered/working directory,
optional progress, and a cancellation token, returning an `OperationResult<T>`
(execution summary) using the standard `CreateSuccess`/`CreateFailure`
factories.

- Implement the service under `GenHub/GenHub/Features/Content/Services/` (or
`Features/Manifest/`), following `ContentValidator`'s conventions:
primary-constructor DI, guard clauses, `ILogger` debug/error logging, and
progress reporting.

- For each `PostInstallStep`: resolve
`TargetRelativePath`/`DestinationRelativePath` against `manifest.Files` (must be
a declared entry), verify containment inside the delivered directory using the
new `PathHelper` helper, and hash-verify the referenced file against its
`ManifestFile.Hash` using `IFileOperationsService.VerifyFileHashAsync`.

- Dispatch execution on `Kind` via a `switch` statement that fails with
`NotSupported` on unknown kinds. Implement `RemoveFile`/`RenameFile` as
filesystem operations. Implement `RunVerifiedInstaller` via a `ProcessStartInfo`
launch mirroring `GameProcessManager` conventions, using only validated
arguments, honoring `RequiresElevation` (Windows-only elevated launch via
`UseShellExecute = true, Verb = "runas"`, per the elevation assumption),
awaiting completion, and mapping exit
codes/`Win32Exception`/`InvalidOperationException` to `CreateFailure` results.

- Gate `RunVerifiedInstaller` (and any executable step) behind a publisher
allowlist: only manifests whose `Publisher` is on a trusted list may declare
executable steps; otherwise reject/fail the step, satisfying the trust-boundary
requirement.

- Register `IInstallationInstructionsService` as a singleton in
`ContentPipelineModule.cs` alongside `IContentValidator` (in
`AddSharedComponents`/`AddCoreServices`).

- Inject the service into `BaseContentProvider`'s primary constructor (mirroring
`IContentValidator`) and invoke it inside `PrepareContentAsync` immediately
after `PrepareContentInternalAsync` succeeds and before/around the
file-validation step, passing `result.Data` and the working directory. Update
concrete providers' constructors to forward the new dependency to `base(...)`.
This ensures the engine runs exactly once per acquisition, since this code path
is only reachable via `AcquireContentAsync`.
===============================================================================

Task: 4

Implement Phase 4: wire up the GeneralsOnline EAC installer as the first real
usage of the new post-install execution mechanism.

- In `GeneralsOnlineManifestFactory.cs`, add a `RunVerifiedInstaller`
`PostInstallStep` targeting `EasyAntiCheat_EOS_Setup.exe` (which already falls
through as a workspace `ManifestFile`), setting `RequiresElevation` as
appropriate, on the client-variant manifests.

- Ensure the GeneralsOnline `Publisher` value is added to the executor's trusted
publisher allowlist (established in Phase 3) so this executable step is
permitted to run.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#328 - feat(platform): make paths, manifests, and Unix workspaces platform-aware [merged]
#329 - feat(macos): add native host, installation detection, and CI [merged]
#332 - feat(launching): launch the native BGFX client against retail archives [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!