feat(web): add exec hook task and batched apidocs ingestion

[PrzemyslawKlys]

Summary

• add exec pipeline task as a stable extensibility hook for custom tooling/generators
• add multi-library API docs ingestion via apidocs step inputs / entries batches (CSharp + PowerShell)
• update pipeline cache behavior:
  • exec is non-cacheable
  • apidocs batch outputs are discovered from nested inputs
  • nested input path fingerprints are included for cache invalidation
• update pipeline schema and docs for new contracts
• add tests:
  • WebPipelineRunnerExecTaskTests
  • WebPipelineRunnerApiDocsBatchTests

Why

• reduces per-site script glue and makes extension points first-class
• enables easier Hugo/Jekyll/DocFX-like multi-library docs pipelines with one step
• directly helps HtmlForgeX, IntelligenceX, and CodeGlyphX consolidate mixed C# + PowerShell docs flows

Validation

• dotnet test .\PowerForge.Tests\PowerForge.Tests.csproj -c Release --filter "FullyQualifiedName~WebPipelineRunnerExecTaskTests|FullyQualifiedName~WebPipelineRunnerApiDocsBatchTests"
• dotnet test .\PSPublishModule.sln -c Release

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[claude]

Pull Request Review

This PR adds two significant extensibility features to PowerForge's web pipeline system: exec task and batched apidocs. Overall, this is a well-implemented feature addition with good test coverage and documentation.

Strengths

• Clean separation of concerns with new functionality properly isolated
• Follows established codebase patterns for process execution
• Good error handling with proper exception wrapping, timeout handling, and graceful cleanup
• Multiple aliases for flexibility matching existing conventions
• Two new test classes cover both features with meaningful scenarios
• Comprehensive documentation in PowerForge.Web.Pipeline.md with clear examples
• Schema properly updated with descriptions
• Correctly marks exec as non-cacheable (critical for commands with side effects)
• Smart fingerprinting for batched inputs in cache invalidation

Observations and Suggestions

1. Process Handling (Low Priority)

According to .NET docs, when using asynchronous output/error redirection, you should call the parameterless WaitForExit() after the timed version to ensure all output is flushed. This prevents a subtle race condition that could cause output truncation.

Current code (line 85):
var finished = process.WaitForExit(Math.Max(1, timeoutSeconds) * 1000);

Suggested:

var finished = process.WaitForExit(Math.Max(1, timeoutSeconds) * 1000);
if (finished) {
    process.WaitForExit(); // Ensure async output/error streams complete
}

2. Security Documentation (Low Priority)

Consider adding a note in documentation that pipeline JSON files should be treated as trusted code (similar to Makefiles, Dockerfiles). The exec task is intentionally powerful as an extensibility hook.

The implementation is already secure: UseShellExecute = false prevents shell injection, and ArgumentList.Add() is used appropriately.

3. Test Coverage (Low Priority)

Consider adding tests for:

• Actual timeout scenario (command that exceeds timeout)
• Working directory verification
• Both string args and array argsList
• Batch failure handling

Security Review

• Command execution is intentional (extensibility hook by design)
• UseShellExecute = false prevents shell injection
• Timeout protection prevents runaway processes
• Working directory validation exists
• No SQL injection, XSS, or typical web vulnerabilities

Final Verdict

This PR is ready to merge with minor optional improvements noted above.

The implementation is:

• Well-tested
• Well-documented
• Follows repository conventions (per CONTRIBUTING.md)
• Properly handles edge cases
• Cache behavior is correct
• Schema is properly updated

The WaitForExit pattern suggestion is the only technical improvement worth considering before merge, but it is a subtle edge case.

Great work on this feature!

Review by Claude Code