Merge pull request #51 from Extra-Chill/feat-worktree-bootstrap

feat(workspace): bootstrap worktrees by default (closes #50)

Author: chubes4

inc/Abilities/WorkspaceAbilities.php

@@ -706,7 +706,7 @@ private function registerAbilities(): void {
 				'datamachine/workspace-worktree-add',
 				array(
 					'label'               => 'Add Workspace Worktree',
-					'description'         => 'Create a git worktree for a branch under `<repo>@<branch-slug>`. Branches are created off the supplied `from` ref (default `origin/HEAD`) when they do not yet exist locally. When `inject_context` is true (default), the originating site\'s agent memory is snapshotted into `.claude/CLAUDE.local.md` and `.opencode/AGENTS.local.md` and added to the worktree\'s per-checkout `info/exclude`.',
+					'description'         => 'Create a git worktree for a branch under `<repo>@<branch-slug>`. Branches are created off the supplied `from` ref (default `origin/HEAD`) when they do not yet exist locally. When `inject_context` is true (default), the originating site\'s agent memory is snapshotted into `.claude/CLAUDE.local.md` and `.opencode/AGENTS.local.md` and added to the worktree\'s per-checkout `info/exclude`. When `bootstrap` is true (default), submodule init + package-manager install + composer install run after creation so the worktree is immediately test/build-ready; set false to create a bare checkout.',
 					'category'            => 'datamachine-code-workspace',
 					'input_schema'        => array(
 						'type'       => 'object',
@@ -727,6 +727,10 @@ private function registerAbilities(): void {
 								'type'        => 'boolean',
 								'description' => 'Inject the originating site\'s agent context (MEMORY.md, USER.md, RULES.md) into the new worktree. Default true. Set false to create a bare worktree.',
 							),
+							'bootstrap'      => array(
+								'type'        => 'boolean',
+								'description' => 'Run detected bootstrap steps (submodule init, package-manager install, composer install) after creating the worktree. Default true. Steps are skipped gracefully when their trigger file or tool is missing. Set false for a bare checkout (e.g. when only reading code).',
+							),
 						),
 						'required'   => array( 'repo', 'branch' ),
 					),
@@ -747,6 +751,10 @@ private function registerAbilities(): void {
 							),
 							'context_exclude_path' => array( 'type' => 'string' ),
 							'context_skip_reason' => array( 'type' => 'string' ),
+							'bootstrap'           => array(
+								'type'        => 'object',
+								'description' => 'Present only when bootstrap=true. Contains success/ran_any booleans and a steps array.',
+							),
 						),
 					),
 					'execute_callback'    => array( self::class, 'worktreeAdd' ),
@@ -1181,11 +1189,14 @@ public static function worktreeAdd( array $input ): array|\WP_Error {
 		$workspace = new Workspace();
 		// Default inject_context=true; only false when explicitly provided.
 		$inject_context = array_key_exists( 'inject_context', $input ) ? (bool) $input['inject_context'] : true;
+		// Default bootstrap=true; only false when explicitly provided.
+		$bootstrap = array_key_exists( 'bootstrap', $input ) ? (bool) $input['bootstrap'] : true;
 		return $workspace->worktree_add(
 			$input['repo'] ?? '',
 			$input['branch'] ?? '',
 			$input['from'] ?? null,
-			$inject_context
+			$inject_context,
+			$bootstrap
 		);
 	}
 

inc/Cli/Commands/WorkspaceCommand.php

@@ -907,6 +907,19 @@ private function renderGitOperationResult( string $operation, array $result, arr
 	 *   paths to the repository's `info/exclude`. The ability-level input
 	 *   is `inject_context=false`; this flag is the CLI shorthand.
 	 *
+	 * [--skip-bootstrap]
+	 * : Skip the default bootstrap pass (applies to `add` only). By default,
+	 *   `worktree add` runs detected setup so the checkout is immediately
+	 *   test/build-ready:
+	 *     - git submodule update --init --recursive (if .gitmodules)
+	 *     - pnpm/bun/yarn/npm install (based on lockfile)
+	 *     - composer install --no-interaction (if composer.lock)
+	 *   Each step is skipped gracefully when its trigger file or tool is
+	 *   missing. Pass `--skip-bootstrap` to create a bare checkout for pure
+	 *   read use (faster, no deps installed). The ability-level input is
+	 *   `bootstrap=false`; this flag is the CLI shorthand (matches the
+	 *   existing `--skip-context-injection` convention).
+	 *
 	 * [--force]
 	 * : Force-remove a worktree even if it is dirty (applies to `remove` and
 	 *   `cleanup`). Does NOT override the unpushed-commits safety in cleanup.
@@ -960,6 +973,9 @@ private function renderGitOperationResult( string $operation, array $result, arr
 	 *     # Create a worktree without injecting site-agent context
 	 *     wp datamachine workspace worktree add data-machine fix/foo --skip-context-injection
 	 *
+	 *     # Create a bare worktree (skip the default bootstrap pass)
+	 *     wp datamachine workspace worktree add data-machine fix/foo --skip-bootstrap
+	 *
 	 *     # Re-read the originating site's agent memory into an existing worktree
 	 *     wp datamachine workspace worktree refresh-context data-machine@fix-foo
 	 *
@@ -999,7 +1015,7 @@ public function worktree( array $args, array $assoc_args ): void {
 		switch ( $operation ) {
 			case 'add':
 				if ( empty( $args[1] ) || empty( $args[2] ) ) {
-					WP_CLI::error( 'Usage: worktree add <repo> <branch> [--from=<ref>] [--skip-context-injection]' );
+					WP_CLI::error( 'Usage: worktree add <repo> <branch> [--from=<ref>] [--skip-context-injection] [--skip-bootstrap]' );
 					return;
 				}
 				$input['repo']   = $args[1];
@@ -1009,6 +1025,8 @@ public function worktree( array $args, array $assoc_args ): void {
 				}
 				// --skip-context-injection disables the default-on injection step.
 				$input['inject_context'] = empty( $assoc_args['skip-context-injection'] );
+				// --skip-bootstrap disables the default-on bootstrap step.
+				$input['bootstrap'] = empty( $assoc_args['skip-bootstrap'] );
 				break;
 
 			case 'refresh-context':
@@ -1159,6 +1177,17 @@ private function renderWorktreeResult( string $operation, array $result, array $
 						WP_CLI::log( sprintf( 'Context: not injected (%s)', $reason ) );
 					}
 				}
+				if ( isset( $result['bootstrap'] ) && is_array( $result['bootstrap'] ) ) {
+					$bs      = $result['bootstrap'];
+					$ok      = ! empty( $bs['success'] );
+					$ran_any = ! empty( $bs['ran_any'] );
+					$label   = $ok ? ( $ran_any ? 'Bootstrap: ok' : 'Bootstrap: nothing to do' ) : 'Bootstrap: one or more steps FAILED';
+					WP_CLI::log( $label );
+					WP_CLI::log( \DataMachineCode\Workspace\WorktreeBootstrapper::format( $bs ) );
+					if ( ! $ok ) {
+						WP_CLI::warning( 'Worktree was created but bootstrap had failures. Re-run the failing step manually, or remove and retry.' );
+					}
+				}
 				return;
 
 			case 'refresh-context':

inc/Workspace/Workspace.php

@@ -861,13 +861,24 @@ public function git_diff( string $name, ?string $from = null, ?string $to = null
 	 * absent the worktree is still created successfully; injection silently
 	 * skips.
 	 *
+	 * When `$bootstrap` is true (default), a bootstrap pass runs after the
+	 * worktree is created: `git submodule update --init --recursive` if
+	 * `.gitmodules` is present, a package-manager install if a lockfile is
+	 * present (pnpm/bun/yarn/npm), and `composer install` if `composer.lock`
+	 * is present. Steps are independent and each one is skipped gracefully
+	 * when its tool is unavailable. A failing step is surfaced in the result
+	 * but does not roll back the worktree — the checkout exists either way.
+	 * Pass `$bootstrap = false` (or `--no-bootstrap` on the CLI) for a bare
+	 * checkout when you only need to read code on that branch.
+	 *
 	 * @param string      $repo           Primary repo name (no @-suffix).
 	 * @param string      $branch         Branch to check out (e.g. "fix/foo-bar").
 	 * @param string|null $from           Base ref when creating the branch.
 	 * @param bool        $inject_context Whether to inject site-agent context (default true).
-	 * @return array{success: bool, handle: string, path: string, branch: string, slug: string, created_branch: bool, message: string, context_injected?: bool, context_files?: string[], context_skip_reason?: string}|\WP_Error
+	 * @param bool        $bootstrap      Whether to run submodule/package/composer install after creation (default true).
+	 * @return array{success: bool, handle: string, path: string, branch: string, slug: string, created_branch: bool, message: string, context_injected?: bool, context_files?: string[], context_skip_reason?: string, bootstrap?: array}|\WP_Error
 	 */
-	public function worktree_add( string $repo, string $branch, ?string $from = null, bool $inject_context = true ): array|\WP_Error {
+	public function worktree_add( string $repo, string $branch, ?string $from = null, bool $inject_context = true, bool $bootstrap = true ): array|\WP_Error {
 		$repo   = $this->sanitize_name( $repo );
 		$branch = trim( $branch );
 
@@ -929,29 +940,29 @@ public function worktree_add( string $repo, string $branch, ?string $from = null
 		if ( ! $inject_context ) {
 			$response['context_injected']    = false;
 			$response['context_skip_reason'] = 'inject_context flag disabled';
-			return $response;
-		}
-
-		$payload = WorktreeContextInjector::build_payload();
-		if ( null === $payload ) {
-			$response['context_injected']    = false;
-			$response['context_skip_reason'] = 'agent memory layer unavailable';
-			return $response;
-		}
-
-		$injection = WorktreeContextInjector::inject( $wt_path, $payload );
-		if ( is_wp_error( $injection ) ) {
-			$response['context_injected']    = false;
-			$response['context_skip_reason'] = 'inject failed: ' . $injection->get_error_message();
-			return $response;
+		} else {
+			$payload = WorktreeContextInjector::build_payload();
+			if ( null === $payload ) {
+				$response['context_injected']    = false;
+				$response['context_skip_reason'] = 'agent memory layer unavailable';
+			} else {
+				$injection = WorktreeContextInjector::inject( $wt_path, $payload );
+				if ( is_wp_error( $injection ) ) {
+					$response['context_injected']    = false;
+					$response['context_skip_reason'] = 'inject failed: ' . $injection->get_error_message();
+				} else {
+					WorktreeContextInjector::store_metadata( $wt_handle, $payload );
+					$response['context_injected'] = true;
+					$response['context_files']    = $injection['written'];
+					if ( ! empty( $injection['exclude_path'] ) ) {
+						$response['context_exclude_path'] = $injection['exclude_path'];
+					}
+				}
+			}
 		}
 
-		WorktreeContextInjector::store_metadata( $wt_handle, $payload );
-
-		$response['context_injected'] = true;
-		$response['context_files']    = $injection['written'];
-		if ( ! empty( $injection['exclude_path'] ) ) {
-			$response['context_exclude_path'] = $injection['exclude_path'];
+		if ( $bootstrap ) {
+			$response['bootstrap'] = WorktreeBootstrapper::bootstrap( $wt_path );
 		}
 
 		return $response;