Skip to content

Flatten shell command execution API - #4255

Merged
thomhurst merged 1 commit into
mainfrom
issue-4213-shell-run
Aug 28, 2026
Merged

Flatten shell command execution API#4255
thomhurst merged 1 commit into
mainfrom
issue-4213-shell-run

Conversation

@thomhurst

@thomhurst thomhurst commented Aug 28, 2026

Copy link
Copy Markdown
Owner

Summary

  • expose command execution directly as IShellContext.RunAsync
  • add raw tool/argument overloads, including the cancellation-token golden path
  • make CommandLineToolOptions(string tool) concrete and remove GenericCommandLineToolOptions
  • migrate current code, tests, examples, and architecture docs while preserving v3 history

Validation

  • ModularPipelines.Tests.slnf Release build
  • Git, Node, Testing, analyzers, documentation snippets, and Trim/AOT smoke builds
  • ShellContext 4/4; telemetry 19/19; cancellation 22/22
  • Git 13/13; ModuleTester 25/25; documentation snippets 4/4
  • CommandExtensions 4/4; CommandLineBuilder 89/89
  • targeted whitespace verification across affected projects

Closes #4213

Summary by CodeRabbit

  • New Features

    • Added a streamlined shell API for running command-line tools directly with tool names, arguments, options, and cancellation support.
    • Simplified command configuration with direct construction of command-line tool options.
  • Documentation

    • Updated architecture, custom command, requirement, and exception examples to reflect the streamlined command execution API.
  • Tests

    • Added coverage for shell execution overloads and updated existing command execution tests.

Expose the common command primitive directly on IShellContext and remove the redundant generic options wrapper.\n\nRefs #4213
@coderabbitai

coderabbitai Bot commented Aug 28, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 091378ab-ad8d-4070-bfa5-36d38dff9908

📥 Commits

Reviewing files that changed from the base of the PR and between 1db5364 and 6cc65cb.

📒 Files selected for processing (33)
  • docs/architecture/interface-hierarchy.md
  • docs/docs/how-to/custom-commands.md
  • src/ModularPipelines.Analyzers/ModularPipelines.Analyzers.Test/ModularPipelinesAnalyzersAsyncModulesUnitTests.cs
  • src/ModularPipelines.Cmd/Cmd.cs
  • src/ModularPipelines.Git/GitCommandRunner.cs
  • src/ModularPipelines.Git/GitInformation.cs
  • src/ModularPipelines.Git/GitVersioning.cs
  • src/ModularPipelines.Node/Node.cs
  • src/ModularPipelines.Node/Nvm.cs
  • src/ModularPipelines/Context/Bash.cs
  • src/ModularPipelines/Context/Domains/IShellContext.cs
  • src/ModularPipelines/Context/Domains/Implementations/ShellContext.cs
  • src/ModularPipelines/Context/FileInstaller.cs
  • src/ModularPipelines/Context/PredefinedInstallers.cs
  • src/ModularPipelines/Exceptions/CommandException.cs
  • src/ModularPipelines/Extensions/CommandExtensions.cs
  • src/ModularPipelines/Options/CommandLineToolOptions.cs
  • src/ModularPipelines/Options/GenericCommandLineToolOptions.cs
  • src/ModularPipelines/Requirements/DelegateRequirement.cs
  • src/ModularPipelines/Requirements/PipelineRequirement.cs
  • src/ModularPipelines/Requirements/Require.cs
  • test/ModularPipelines.DocumentationSnippets/CurrentApiSnippets.cs
  • test/ModularPipelines.Git.UnitTests/GitCommandRunnerTests.cs
  • test/ModularPipelines.Git.UnitTests/GitInformationTests.cs
  • test/ModularPipelines.Testing.UnitTests/ModuleTesterTests.cs
  • test/ModularPipelines.TrimAotSmoke/Program.cs
  • test/ModularPipelines.UnitTests/Context/CommandLineBuilderTests.cs
  • test/ModularPipelines.UnitTests/Context/ShellContextTests.cs
  • test/ModularPipelines.UnitTests/Engine/RunReportTests.cs
  • test/ModularPipelines.UnitTests/Execution/EngineCancellationTokenTests.cs
  • test/ModularPipelines.UnitTests/Helpers/CommandTests.cs
  • test/ModularPipelines.UnitTests/Helpers/PredefinedInstallersTests.cs
  • test/ModularPipelines.UnitTests/Tracing/TelemetryIntegrationTests.cs
💤 Files with no reviewable changes (1)
  • src/ModularPipelines/Options/GenericCommandLineToolOptions.cs

Included review availability: Your plan provides up to 4 included reviews per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

The PR replaces nested shell command execution with IShellContext.RunAsync, makes CommandLineToolOptions concrete, removes GenericCommandLineToolOptions, and updates runtime call sites, tests, fixtures, and documentation.

Changes

Shell execution API migration

Layer / File(s) Summary
Shell API and command option contract
src/ModularPipelines/Context/Domains/IShellContext.cs, src/ModularPipelines/Context/Domains/Implementations/ShellContext.cs, src/ModularPipelines/Options/*, src/ModularPipelines/Extensions/CommandExtensions.cs
IShellContext now provides three RunAsync overloads. ShellContext delegates these calls to ICommandContext. CommandLineToolOptions accepts raw tool names, and GenericCommandLineToolOptions is removed.
Runtime command call sites
src/ModularPipelines.Cmd/Cmd.cs, src/ModularPipelines.Git/*, src/ModularPipelines.Node/*, src/ModularPipelines/Context/*
Runtime command execution now uses Shell.RunAsync or CommandLineToolOptions. Existing arguments, execution options, and cancellation tokens remain unchanged.
Test and fixture migration
src/ModularPipelines.Analyzers/..., test/ModularPipelines.Git.UnitTests/*, test/ModularPipelines.Testing.UnitTests/*, test/ModularPipelines.UnitTests/*, test/ModularPipelines.TrimAotSmoke/Program.cs
Tests and source fixtures use the new shell API and option type. New ShellContext tests cover overload delegation, option construction, cancellation handling, and removal of the Command property.
Documentation and API examples
docs/architecture/interface-hierarchy.md, docs/docs/how-to/custom-commands.md, src/ModularPipelines/Requirements/*, src/ModularPipelines/Exceptions/CommandException.cs, test/ModularPipelines.DocumentationSnippets/CurrentApiSnippets.cs
Examples now show direct Shell.RunAsync calls and direct CommandLineToolOptions construction.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 6cc65

This change simplifies the shell command API while preserving existing execution and cancellation controls. No actionable merge-blocking risk remains beyond normal checks and review.

Poem

A rabbit sees commands take flight
Through Shell.RunAsync, neat and light
Old wrappers rest beneath the ground
New options carry tools around
Tests hop after, with green delight

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 19.23% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 78 functions across 30 files. (2 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly describes the primary change: flattening the shell command execution API.
Linked Issues check ✅ Passed The changes satisfy issue #4213. They move execution to IShellContext.RunAsync, add raw tool and argument overloads, add the public CommandLineToolOptions(string tool) constructor, remove GenericComma…
Out of Scope Changes check ✅ Passed The source, test, documentation, and example updates directly support the API flattening described in issue #4213. No unrelated code changes are identified.
Full details: Linked Issues check

Explanation

The changes satisfy issue #4213. They move execution to IShellContext.RunAsync, add raw tool and argument overloads, add the public CommandLineToolOptions(string tool) constructor, remove GenericCommandLineToolOptions, and retain ICommandContext as the internal execution seam.

Full details: Docstring Coverage

Explanation

Docstring coverage is 19.23% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 78 functions across 30 files. (2 skipped: 2 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch issue-4213-shell-run

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@greptile-apps

greptile-apps Bot commented Aug 28, 2026

Copy link
Copy Markdown

Greptile Summary

The PR flattens general command execution onto IShellContext.RunAsync, replaces the generic options wrapper with direct CommandLineToolOptions construction, and migrates production callers, tests, examples, and documentation.

  • Adds options-based and raw tool/argument RunAsync overloads with explicit cancellation-token forwarding.
  • Makes CommandLineToolOptions(string tool) directly constructible and removes GenericCommandLineToolOptions.
  • Updates Git, Node, Cmd, installer, analyzer, documentation, telemetry, cancellation, and trim/AOT call sites.

Confidence Score: 5/5

The PR appears safe to merge, with the flattened API preserving the existing command execution lifecycle and the public surface removals explicitly forming part of the intended migration.

The new shell overloads delegate to the same injected command context and correctly preserve arguments, execution options, cancellation, interception, logging, and secret handling; no actionable defect remains.

Important Files Changed

Filename Overview
src/ModularPipelines/Context/Domains/IShellContext.cs Replaces the nested command property with direct options-based and raw-command execution overloads.
src/ModularPipelines/Context/Domains/Implementations/ShellContext.cs Implements the flattened API by forwarding execution options and cancellation to the existing command service.
src/ModularPipelines/Options/CommandLineToolOptions.cs Makes the options base concrete and adds direct runtime-tool construction while retaining protected construction for typed derived options.
src/ModularPipelines/Options/GenericCommandLineToolOptions.cs Removes the now-redundant generic options wrapper as part of the intentional API migration.
src/ModularPipelines.Git/GitCommandRunner.cs Migrates raw Git execution to the flattened shell API without changing execution settings or cancellation.
src/ModularPipelines.Node/Node.cs Migrates the Node version command to the raw tool-and-arguments overload.
src/ModularPipelines.Node/Nvm.cs Migrates NVM operations to the raw shell overload while preserving command arguments and cancellation.
test/ModularPipelines.UnitTests/Context/ShellContextTests.cs Verifies delegation, raw-options construction, cancellation-token overload behavior, and removal of command nesting.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    M[Module or integration] --> S[IShellContext.RunAsync]
    S --> O[CommandLineToolOptions]
    O --> C[ICommandContext]
    C --> I[Interceptors and secret handling]
    C --> P[Process execution]
    P --> R[CommandResult]
Loading

Reviews (1): Last reviewed commit: "feat(shell): flatten command execution" | Re-trigger Greptile

@thomhurst
thomhurst merged commit db2d62c into main Aug 28, 2026
21 of 22 checks passed
@thomhurst
thomhurst deleted the issue-4213-shell-run branch August 28, 2026 15:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant