[2.x] Deprecate the rebuild command

CHANGELOG.md

@@ -23,7 +23,7 @@ This serves two purposes:
 - for changes in existing functionality.
 
 ### Deprecated
-- for soon-to-be removed features.
+- Deprecated the `rebuild` command. It has no remaining internal consumers now that the realtime compiler renders pages in-memory, and single-page builds can silently leave aggregate outputs (sitemap, RSS, search index, navigation) stale. It will be removed in v3.0; use `Hyde\Framework\Actions\StaticPageBuilder::handle()` instead if you need to build a single page programmatically.
 
 ### Removed
 - for now removed features.

docs/creating-content/compile-and-deploy.md

@@ -16,7 +16,7 @@ Now that you have some amazing content, you'll want to compile your site into st
 php hyde build
 ```
 
-**You can also compile a single file:**
+**You can also compile a single file, though this is deprecated and will be removed in v3.0 (use `Hyde\Framework\Actions\StaticPageBuilder::handle()` instead if you need this programmatically):**
 
 ```bash
 php hyde rebuild <filepath>
@@ -35,7 +35,7 @@ php hyde serve
 #### Learn more about these commands in the [console commands](console-commands) documentation:
 
 - [Build command](console-commands#build-the-static-site)
-- [Rebuild command](console-commands#build-a-single-file)
+- [Rebuild command (Deprecated)](console-commands#rebuild)
 - [Serve command](console-commands#start-the-realtime-compiler)
 
 ---

docs/getting-started/console-commands.md

@@ -47,7 +47,7 @@ Here is a quick reference of all the available commands. You can also run `php h
 |-----------------------------------------|---------------------------------------------------------------------------------------------|
 | [`build`](#build)                       | Build the static site                                                                       |
 | [`serve`](#serve)                       | Start the realtime compiler server                                                          |
-| [`rebuild`](#rebuild)                   | Run the static site builder for a single file                                               |
+| [`rebuild`](#rebuild)                   | Run the static site builder for a single file (Deprecated, will be removed in v3.0)         |
 | [`build:rss`](#build-rss)               | Generate the RSS feed                                                                       |
 | [`build:search`](#build-search)         | Generate the `docs/search.json` file                                                        |
 | [`build:sitemap`](#build-sitemap)       | Generate the `sitemap.xml` file                                                             |
@@ -83,6 +83,8 @@ Build the static site
 
 <a name="rebuild" style="display: inline-block; position: absolute; margin-top: -5rem;"></a>
 
+>warning **Deprecated:** The `rebuild` command is deprecated and will be removed in HydePHP v3.0. It has no remaining internal consumers now that the realtime compiler renders pages in-memory, and building a single page can silently leave aggregate outputs (sitemap, RSS, search index, navigation) stale. If you need to build a single page programmatically, use `Hyde\Framework\Actions\StaticPageBuilder::handle()` instead.
+
 ```bash
 php hyde rebuild <path>
 ```

packages/framework/src/Console/Commands/RebuildPageCommand.php

@@ -25,17 +25,21 @@
 
 /**
  * Build a single static site file.
+ *
+ * @deprecated This command is deprecated and will be removed in HydePHP v3.0. Use \Hyde\Framework\Actions\StaticPageBuilder::handle() instead.
  */
 class RebuildPageCommand extends Command
 {
     /** @var string */
     protected $signature = 'rebuild {path : The relative file path (example: _posts/hello-world.md)}';
 
     /** @var string */
-    protected $description = 'Run the static site builder for a single file';
+    protected $description = 'Run the static site builder for a single file [Deprecated, will be removed in v3.0]';
 
     public function handle(): int
     {
+        $this->printDeprecationWarning();
+
         if ($this->argument('path') === Hyde::getMediaDirectory()) {
             return (new TransferMediaAssets())->run($this->output);
 
@@ -47,6 +51,16 @@ public function handle(): int
         return $this->makeBuildTask($this->output, $this->getNormalizedPathString())->run();
     }
 
+    /**
+     * @deprecated The `rebuild` command is deprecated and will be removed in HydePHP v3.0.
+     */
+    protected function printDeprecationWarning(): void
+    {
+        $this->warn('The `rebuild` command is deprecated and will be removed in HydePHP v3.0.');
+        $this->line('If you need to build a single page programmatically, use Hyde\Framework\Actions\StaticPageBuilder::handle() instead.');
+        $this->newLine();
+    }
+
     protected function getNormalizedPathString(): string
     {
         return str_replace('\\', '/', unslash($this->argument('path')));

packages/framework/tests/Feature/Commands/RebuildPageCommandTest.php

@@ -23,6 +23,18 @@ public function testHandleIsSuccessfulWithValidPath()
         $this->resetSite();
     }
 
+    public function testCommandOutputsDeprecationWarning()
+    {
+        $this->file('_pages/test-page.md', 'foo');
+
+        $this->artisan('rebuild _pages/test-page.md')
+            ->expectsOutput('The `rebuild` command is deprecated and will be removed in HydePHP v3.0.')
+            ->expectsOutput('If you need to build a single page programmatically, use Hyde\Framework\Actions\StaticPageBuilder::handle() instead.')
+            ->assertExitCode(0);
+
+        $this->resetSite();
+    }
+
     public function testMediaFilesCanBeTransferred()
     {
         $this->directory(Hyde::path('_site/media'));