Merge pull request #452 from Extra-Chill/fix/gitsync-proposal-branches

fix: support keyed gitsync proposal branches

Author: chubes4

inc/Abilities/GitSyncAbilities.php

@@ -218,7 +218,7 @@ private function registerAbilities(): void {
 				'datamachine/gitsync-submit',
 				array(
 					'label'               => 'Submit GitSync Binding as Pull Request',
-					'description'         => 'Upload changed local files to the sticky proposal branch (gitsync/<slug>) and open or update a PR against the pinned branch.',
+					'description'         => 'Upload changed local files to the sticky proposal branch (gitsync/<slug>) by default, or to a keyed proposal branch (gitsync/<slug>/<proposal-slug>) when proposal is provided, and open or update a PR against the pinned branch.',
 					'category'            => 'datamachine-code-gitsync',
 					'input_schema'        => array(
 						'type'       => 'object',
@@ -231,19 +231,24 @@ private function registerAbilities(): void {
 								'items'       => array( 'type' => 'string' ),
 								'description' => 'Optional explicit list of relative paths. If omitted, every file with a SHA mismatch against upstream (filtered by allowed_paths) is submitted.',
 							),
-							'title'   => array( 'type' => 'string' ),
-							'body'    => array( 'type' => 'string' ),
+							'title'    => array( 'type' => 'string' ),
+							'body'     => array( 'type' => 'string' ),
+							'proposal' => array(
+								'type'        => 'string',
+								'description' => 'Optional proposal key. Omit to reuse gitsync/<slug>; pass a key to use gitsync/<slug>/<proposal-slug>.',
+							),
 						),
 					),
 					'output_schema'       => array(
 						'type'       => 'object',
 						'properties' => array(
-							'success' => array( 'type' => 'boolean' ),
-							'slug'    => array( 'type' => 'string' ),
-							'branch'  => array( 'type' => 'string' ),
-							'commits' => array( 'type' => 'array' ),
-							'pr'      => array( 'type' => 'object' ),
-							'message' => array( 'type' => 'string' ),
+							'success'  => array( 'type' => 'boolean' ),
+							'slug'     => array( 'type' => 'string' ),
+							'proposal' => array( 'type' => array( 'string', 'null' ) ),
+							'branch'   => array( 'type' => 'string' ),
+							'commits'  => array( 'type' => 'array' ),
+							'pr'       => array( 'type' => 'object' ),
+							'message'  => array( 'type' => 'string' ),
 						),
 					),
 					'execute_callback'    => array( self::class, 'submit' ),

inc/Cli/Commands/GitSyncCommand.php

@@ -323,7 +323,8 @@ public function status( array $args, array $assoc_args ): void {
 	 * Submit local edits as a pull request.
 	 *
 	 * Uploads changed files to the sticky proposal branch (gitsync/<slug>)
-	 * and opens or updates a PR against the pinned branch.
+	 * by default, or to an isolated keyed proposal branch when --proposal is
+	 * provided, and opens or updates a PR against the pinned branch.
 	 *
 	 * ## OPTIONS
 	 *
@@ -337,6 +338,10 @@ public function status( array $args, array $assoc_args ): void {
 	 * : Comma-separated list of relative paths to submit. If omitted,
 	 *   every changed file under allowed_paths is included.
 	 *
+	 * [--proposal=<proposal>]
+	 * : Optional proposal key. Omit to reuse the sticky branch gitsync/<slug>;
+	 *   pass a key to use an isolated branch gitsync/<slug>/<proposal-slug>.
+	 *
 	 * [--title=<title>]
 	 * : PR title. Defaults to --message.
 	 *
@@ -367,6 +372,9 @@ public function submit( array $args, array $assoc_args ): void {
 		if ( isset($assoc_args['paths']) && '' !== $assoc_args['paths'] ) {
 			$input['paths'] = array_values(array_filter(array_map('trim', explode(',', (string) $assoc_args['paths']))));
 		}
+		if ( isset($assoc_args['proposal']) ) {
+			$input['proposal'] = (string) $assoc_args['proposal'];
+		}
 		if ( isset($assoc_args['title']) ) {
 			$input['title'] = (string) $assoc_args['title'];
 		}

inc/GitSync/GitSyncProposer.php

@@ -48,7 +48,8 @@ public function __construct( GitSyncRegistry $registry ) {
 	}
 
 	/**
-	 * Submit local edits as a PR on the sticky proposal branch.
+	 * Submit local edits as a PR on the sticky proposal branch, or an
+	 * isolated keyed proposal branch when args.proposal is provided.
 	 *
 	 * @param  GitSyncBinding       $binding
 	 * @param  array<string, mixed> $args    {
@@ -58,6 +59,8 @@ public function __construct( GitSyncRegistry $registry ) {
 	 *                             is included.
 	 * @type   string   $title   PR title. Defaults to $message.
 	 * @type   string   $body    PR body. Defaults to an auto-summary.
+	 * @type   string   $proposal Optional proposal key. When present,
+	 *                             submits to gitsync/<slug>/<proposal-slug>.
 	 * }
 	 * @return array<string, mixed>|\WP_Error
 	 */
@@ -90,7 +93,14 @@ public function submit( GitSyncBinding $binding, array $args ): array|\WP_Error
 			);
 		}
 
+		$proposal       = $this->normalizeProposalKey( (string) ( $args['proposal'] ?? '' ));
+		if ( is_wp_error($proposal) ) {
+			return $proposal;
+		}
 		$feature_branch = self::BRANCH_PREFIX . $binding->slug;
+		if ( null !== $proposal ) {
+			$feature_branch .= '/' . $proposal;
+		}
 
 		// Ensure the feature branch exists and points at the current
 		// pinned-branch HEAD. If it already existed (previous submit),
@@ -150,12 +160,13 @@ public function submit( GitSyncBinding $binding, array $args ): array|\WP_Error
 		$this->registry->save($binding);
 
 		return array(
-			'success' => true,
-			'slug'    => $binding->slug,
-			'branch'  => $feature_branch,
-			'commits' => $commits,
-			'pr'      => $pr,
-			'message' => sprintf('Proposed %d file(s) on "%s" via PR #%d.', count($commits), $binding->slug, (int) ( $pr['number'] ?? 0 )),
+			'success'  => true,
+			'slug'     => $binding->slug,
+			'proposal' => $proposal,
+			'branch'   => $feature_branch,
+			'commits'  => $commits,
+			'pr'       => $pr,
+			'message'  => sprintf('Proposed %d file(s) on "%s" via PR #%d.', count($commits), $binding->slug, (int) ( $pr['number'] ?? 0 )),
 		);
 	}
 
@@ -292,6 +303,23 @@ private function validateMessage( string $message ): true|\WP_Error {
 		return true;
 	}
 
+	private function normalizeProposalKey( string $proposal ): string|null|\WP_Error {
+		$proposal = trim($proposal);
+		if ( '' === $proposal ) {
+			return null;
+		}
+
+		$normalized = strtolower($proposal);
+		$normalized = preg_replace('/[^a-z0-9]+/', '-', $normalized);
+		$normalized = null === $normalized ? '' : trim($normalized, '-');
+
+		if ( '' === $normalized ) {
+			return new \WP_Error('invalid_proposal', 'Proposal key must contain at least one letter or number.', array( 'status' => 400 ));
+		}
+
+		return $normalized;
+	}
+
 	/**
 	 * Assemble the context every write path needs up front:
 	 *   - resolved absolute path under ABSPATH

tests/smoke-gitsync.php

@@ -396,7 +396,7 @@ public static function apiRequest( string $method, string $url, array $body, str
     // Tree for submit's context — same as last pull.
     // (Already mocked above.)
     // Feature branch doesn't exist yet → 404
-    $GLOBALS['__dmc_http_mock']['GET https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/ref/heads/gitsync/wiki'] = array(
+    $GLOBALS['__dmc_http_mock']['GET https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/ref/heads/gitsync%2Fwiki'] = array(
     'response' => array( 'code' => 404 ),
     'body'     => json_encode(array( 'message' => 'Not Found' )),
     );
@@ -420,18 +420,19 @@ public static function apiRequest( string $method, string $url, array $body, str
     $submit = $gs->submit('wiki', array( 'message' => 'update article a content' ));
     $assert(! is_wp_error($submit), 'submit succeeded — ' . ( is_wp_error($submit) ? $submit->get_error_message() : '' ));
     $assert('gitsync/wiki' === ( $submit['branch'] ?? null ), 'feature branch is gitsync/wiki');
+    $assert(null === ( $submit['proposal'] ?? null ), 'default submit has no proposal key');
     $assert(7 === ( $submit['pr']['number'] ?? null ), 'PR #7 opened');
     $assert('opened' === ( $submit['pr']['action'] ?? null ), 'PR reported as opened');
 
     // =========================================================================
     // 8. Submit again — existing branch + PR is updated in place.
     // =========================================================================
     echo "\nSubmit (update existing PR)\n";
-    $GLOBALS['__dmc_http_mock']['GET https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/ref/heads/gitsync/wiki'] = array(
+    $GLOBALS['__dmc_http_mock']['GET https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/ref/heads/gitsync%2Fwiki'] = array(
     'response' => array( 'code' => 200 ),
     'body'     => json_encode(array( 'object' => array( 'sha' => 'feature-old-sha' ) )),
     );
-    $GLOBALS['__dmc_http_mock']['PATCH https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/refs/heads/gitsync/wiki'] = array(
+    $GLOBALS['__dmc_http_mock']['PATCH https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/refs/heads/gitsync%2Fwiki'] = array(
     'response' => array( 'code' => 200 ),
     'body'     => json_encode(array( 'object' => array( 'sha' => 'base-sha-1' ) )),
     );
@@ -453,7 +454,39 @@ public static function apiRequest( string $method, string $url, array $body, str
     $assert('updated' === ( $submit2['pr']['action'] ?? null ), 'PR reported as updated');
 
     // =========================================================================
-    // 9. Submit with nothing changed → nothing_to_submit.
+    // 9. Submit with a proposal key — isolated branch and PR lookup.
+    // =========================================================================
+    echo "\nSubmit (keyed proposal branch)\n";
+    $GLOBALS['__dmc_http_mock']['GET https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/git/ref/heads/gitsync%2Fwiki%2Fscript-modules'] = array(
+    'response' => array( 'code' => 404 ),
+    'body'     => json_encode(array( 'message' => 'Not Found' )),
+    );
+    $GLOBALS['__dmc_http_mock']['GET https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/pulls'] = array(
+    'response' => array( 'code' => 200 ),
+    'body'     => '[]',
+    );
+    $GLOBALS['__dmc_http_mock']['POST https://api.github.com/repos/Automattic/a8c-wiki-woocommerce/pulls'] = array(
+    'response' => array( 'code' => 201 ),
+    'body'     => json_encode(array( 'number' => 8, 'html_url' => 'https://github.com/a/b/pull/8', 'state' => 'open' )),
+    );
+    file_put_contents(ABSPATH . 'content/wiki/articles/a.md', "article a script modules proposal\n");
+    $capture_before_keyed = count($GLOBALS['__dmc_http_capture']);
+    $keyed = $gs->submit('wiki', array( 'message' => 'script modules update', 'proposal' => 'Script Modules' ));
+    $assert(! is_wp_error($keyed), 'keyed submit succeeded — ' . ( is_wp_error($keyed) ? $keyed->get_error_message() : '' ));
+    $assert('script-modules' === ( $keyed['proposal'] ?? null ), 'proposal key normalized to script-modules');
+    $assert('gitsync/wiki/script-modules' === ( $keyed['branch'] ?? null ), 'keyed feature branch includes proposal slug');
+    $assert(8 === ( $keyed['pr']['number'] ?? null ), 'keyed proposal opened separate PR');
+    $keyed_requests = array_slice($GLOBALS['__dmc_http_capture'], $capture_before_keyed);
+    $keyed_pr_body  = null;
+    foreach ( $keyed_requests as $request ) {
+        if ( 'POST' === $request['method'] && str_ends_with($request['url'], '/pulls') ) {
+            $keyed_pr_body = json_decode((string) $request['body'], true);
+        }
+    }
+    $assert('gitsync/wiki/script-modules' === ( $keyed_pr_body['head'] ?? null ), 'keyed PR uses keyed branch head');
+
+    // =========================================================================
+    // 10. Submit with nothing changed → nothing_to_submit.
     // =========================================================================
     echo "\nSubmit (nothing to propose)\n";
     // File's current SHA must match upstream tree's reported SHA.
@@ -473,7 +506,7 @@ public static function apiRequest( string $method, string $url, array $body, str
     $assert(is_wp_error($nothing) && 'nothing_to_submit' === $nothing->get_error_code(), 'submit refuses when nothing changed');
 
     // =========================================================================
-    // 10. Direct push — two-key auth.
+    // 11. Direct push — two-key auth.
     // =========================================================================
     echo "\nPush (two-key auth)\n";
     file_put_contents(ABSPATH . 'content/wiki/articles/a.md', "article a v5 direct\n");
@@ -503,7 +536,7 @@ public static function apiRequest( string $method, string $url, array $body, str
     $assert(1 === count((array) ( $push['commits'] ?? array() )), 'push recorded 1 commit');
 
     // =========================================================================
-    // 11. Status + list + unbind round-trip.
+    // 12. Status + list + unbind round-trip.
     // =========================================================================
     echo "\nStatus + list + unbind\n";
     $st = $gs->status('wiki');
@@ -524,7 +557,7 @@ public static function apiRequest( string $method, string $url, array $body, str
     $assert(! is_dir(ABSPATH . 'content/wiki/'), 'directory removed by purge');
 
     // =========================================================================
-    // 12. Policy validation.
+    // 13. Policy validation.
     // =========================================================================
     echo "\nPolicy validation\n";
     $gs->bind(array( 'slug' => 'p', 'local_path' => '/content/p/', 'remote_url' => 'https://github.com/Automattic/a8c-wiki-woocommerce' ));