feat: add first-class theme support for slic here and slic run

README.md

@@ -118,9 +118,41 @@ slic here
 
 ![slic here](docs/images/slic-here.gif)
 
-#### 2. WordPress Directory
+#### 2. Themes Directory
 
-The second option is to navigate to the root of your site (likely where `wp-config.php` lives) and run the `slic here`
+If you are developing a **theme**, run `slic here` from your themes directory. `slic` will detect that it is pointed at a themes directory and correctly:
+
+- Mount the directory as `wp-content/themes/` in the Docker stack so your theme is available to WordPress as a real theme.
+- Keep a separate plugins directory (`SLIC_PLUGINS_DIR`) so dependencies like WooCommerce install into `wp-content/plugins/` and not into your themes directory.
+- Run Codeception from within the correct `wp-content/themes/<theme>` path inside the container.
+
+Example:
+
+```bash
+# Change to your themes directory
+cd /path/to/your/wp-content/themes
+
+slic here
+slic use my-theme
+slic run wpunit
+```
+
+> **WPLoader suite config:** When testing a theme, activate it via the WPLoader `theme:` key rather than listing it under `plugins`/`activatePlugins`. WordPress will then load the theme (including its `functions.php`) automatically.
+>
+> ```yaml
+> modules:
+>   config:
+>     WPLoader:
+>       plugins:
+>         - woocommerce/woocommerce.php
+>       activatePlugins:
+>         - woocommerce/woocommerce.php
+>       theme: my-theme   # ← activates the theme under test
+> ```
+
+#### 3. WordPress Directory
+
+The third option is to navigate to the root of your site (likely where `wp-config.php` lives) and run the `slic here`
 command.
 
 > Note: This is an opinionated option and there are some assumptions that are made:

src/commands/run.php

@@ -54,12 +54,9 @@
 maybe_generate_htaccess();
 
 // Run the command in the Codeception container.
-$root = slic_plugins_dir( slic_target( true ) );
-
-// If target is site, set the root to the wp dir.
-if ( 'site' === slic_target() ) {
-	$root = slic_wp_dir();
-}
+// Use get_project_local_path() so that theme targets resolve to SLIC_THEMES_DIR
+// rather than always falling back to SLIC_PLUGINS_DIR.
+$root = get_project_local_path();
 
 // Object-cache is disruptive in the context of tests; remove the object cache drop-in before running the tests.
 $object_cache_dropin = slic_wp_dir( 'wp-content/object-cache.php' );

src/commands/using.php

@@ -24,7 +24,7 @@
 }
 
 $using = slic_target();
-$target_path = slic_plugins_dir( $using );
+$target_path = get_project_local_path();
 if ( empty( $using ) ) {
 	echo magenta( "Currently not using any target, commands requiring a target will fail." . PHP_EOL );
 	return;

src/slic.php

@@ -100,12 +100,26 @@ function get_cwd_dir_name() {
 	return '';
 }
 
+/**
+ * Returns true when slic here was run from a themes directory (SLIC_HERE_DIR matches SLIC_THEMES_DIR).
+ * In this mode themes are valid targets even though slic_here_is_site() is false.
+ *
+ * @return bool
+ */
+function slic_here_is_themes() {
+	$here_dir   = realpath( getenv( 'SLIC_HERE_DIR' ) );
+	$themes_dir = realpath( getenv( 'SLIC_THEMES_DIR' ) );
+
+	return $here_dir && $themes_dir && $here_dir === $themes_dir;
+}
+
 /**
  * Gets all valid targets.
  *
  * Valid targets are:
  *   - Anything in the plugins directory.
- *   - If slic here was done on the site level, "site" is also a valid target.
+ *   - If slic here was done at the site level, "site" is also a valid target and themes are included.
+ *   - If slic here was done at the themes directory level, themes are also valid targets.
  *
  * @param bool $as_array Whether to output as an array. If falsy, will output as a formatted string, including
  *                       headings, line breaks, and indentation.
@@ -121,12 +135,16 @@ function get_valid_targets( $as_array = true ) {
 	$themes = array_keys( dev_themes() );
 	sort( $themes, SORT_NATURAL );
 
+	$include_themes = slic_here_is_site() || slic_here_is_themes();
+
 	$targets = $plugins;
 
 	if ( slic_here_is_site() ) {
 		$targets     = array_merge( [ 'site' ], $plugins, $themes );
 		$targets_str .= PHP_EOL . '  Site:' . PHP_EOL;
 		$targets_str .= '    - site';
+	} elseif ( slic_here_is_themes() ) {
+		$targets = array_merge( $themes, $plugins );
 	}
 
 	$targets_str .= PHP_EOL . "  Plugins:" . PHP_EOL;
@@ -138,7 +156,7 @@ static function ( $target ) {
 		)
 	);
 
-	if ( slic_here_is_site() && $themes ) {
+	if ( $include_themes && $themes ) {
 		$targets_str .= PHP_EOL . "  Themes:" . PHP_EOL;
 		$targets_str .= implode(
 			PHP_EOL, array_map(
@@ -1226,7 +1244,8 @@ function dir_has_req_build_file( $base_command, $path ) {
  */
 function maybe_build_install_command_pool( $base_command, $target, array $sub_directories = [] ) {
 	// Only prompt if the target itself has has been identified as available to build. If any subs need to build, will auto-try.
-	if ( dir_has_req_build_file( $base_command, slic_plugins_dir( $target ) ) ) {
+	// Use get_project_local_path() so that theme targets resolve to SLIC_THEMES_DIR instead of SLIC_PLUGINS_DIR.
+	if ( dir_has_req_build_file( $base_command, get_project_local_path() ) ) {
 		$run = ask(
 			PHP_EOL . yellow( $target . ':' ) . " Would you like to run the {$base_command} install processes for this plugin?",
 			'yes'
@@ -1271,7 +1290,8 @@ function build_command_pool( $base_command, array $command, array $sub_directori
 	$targets     = [];
 
 	// If applicable, include target plugin before subdirectory plugins.
-	$path = $using === 'site' ? slic_wp_dir() : slic_plugins_dir( slic_target() );
+	// Use get_project_local_path() so that theme targets resolve to SLIC_THEMES_DIR.
+	$path = get_project_local_path();
 	if ( dir_has_req_build_file( $base_command, $path ) ) {
 		$targets[] = 'target';
 	}