From a4c04b20653e9d224324bba733f275b06be9fe14 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Mar 2026 14:11:37 +0000
Subject: [PATCH 1/2] Initial plan


From 0dfff6471e57d76bd03601dd3f49fcac04efb2bf Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 13 Mar 2026 14:36:00 +0000
Subject: [PATCH 2/2] Fix multi-line descriptions not correctly indented in
 README generation

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
---
 features/scaffold-package-readme.feature | 43 ++++++++++++++++++++++++
 src/ScaffoldPackageCommand.php           |  8 +++--
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/features/scaffold-package-readme.feature b/features/scaffold-package-readme.feature
index 513f28f..e2c9f44 100644
--- a/features/scaffold-package-readme.feature
+++ b/features/scaffold-package-readme.feature
@@ -386,3 +386,46 @@ Feature: Scaffold a README.md file for an existing package
       """
       **Alias:** `cpt`
       """
+
+  Scenario: README correctly indents multi-paragraph parameter descriptions
+    Given an empty directory
+    And a foo/command.php file:
+      """
+      <?php
+      /**
+       * Multi-paragraph test command.
+       */
+      class Multi_Para_Test_Command {
+          /**
+           * Test command with a multi-paragraph parameter description.
+           *
+           * ## OPTIONS
+           *
+           * [<file>]
+           * : Read content from <file>. If this value is present, the
+           *     `--content` argument will be ignored.
+           *
+           *   Passing `-` will cause content to
+           *   be read from STDIN.
+           *
+           * @when before_wp_load
+           */
+          public function __invoke( $args, $assoc_args ) {}
+      }
+      WP_CLI::add_command( 'multi-para-test', 'Multi_Para_Test_Command' );
+      """
+    And a foo/composer.json file:
+      """
+      {
+          "name": "wp-cli/multi-para-test",
+          "description": "Test",
+          "extra": {
+              "commands": ["multi-para-test"]
+          }
+      }
+      """
+
+    When I run `wp --require=foo/command.php scaffold package-readme foo`
+    Then the foo/README.md file should exist
+    And the contents of the foo/README.md file should match /\t\t.*Read content from/
+    And the contents of the foo/README.md file should match /\t\t.*Passing/
diff --git a/src/ScaffoldPackageCommand.php b/src/ScaffoldPackageCommand.php
index 5e18743..cedfee4 100644
--- a/src/ScaffoldPackageCommand.php
+++ b/src/ScaffoldPackageCommand.php
@@ -365,7 +365,7 @@ public function package_readme( $args, $assoc_args ) {
 				$longdesc = (string) preg_replace( '/##\s(.+)/', '**$1**', $longdesc );
 
 				// definition lists
-				$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n|$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );
+				$longdesc = preg_replace_callback( '/([^\n]+)\n: (.+?)(\n\n(?=\S)|\n*$)/s', [ __CLASS__, 'rewrap_param_desc' ], $longdesc );
 
 				$command_data = [
 					'name'      => "wp {$command}",
@@ -777,14 +777,16 @@ public function package_tests( $args, $assoc_args ) {
 
 	private static function rewrap_param_desc( $matches ) {
 		$param = $matches[1];
-		$desc  = self::indent( "\t\t", $matches[2] );
+		$desc  = self::indent( "\t\t", rtrim( $matches[2] ) );
 		return "\t$param\n$desc\n\n";
 	}
 
 	private static function indent( $whitespace, $text ) {
 		$lines = explode( "\n", $text );
 		foreach ( $lines as &$line ) {
-			$line = $whitespace . $line;
+			if ( '' !== $line ) {
+				$line = $whitespace . $line;
+			}
 		}
 		return implode( "\n", $lines );
 	}