refactor(command): migrate CLI entry point to the new command architecture

Makefile

@@ -41,10 +41,10 @@ clean:
 
 # Test targets
 test: build
-	./build/debug/test/scrap_test
+	ctest --test-dir build/debug --output-on-failure
 
 test-verbose: build
-	./build/debug/test/scrap_test -v high
+	ctest --test-dir build/debug --output-on-failure --verbose
 
 # Code quality targets
 format:

README.md

@@ -126,12 +126,13 @@ scrap update
 scrap is in early alpha development (v0.0.1). Currently implemented:
 
 ✅ **Core Features**
-- Project creation (`scrap new`)
-- Template system with variable substitution
-- Basic command structure (build, run, clean)
-- Configuration file parsing (`scrap.toml`)
+- CLI command framework (help, version, command discovery)
 
 🚧 **In Progress**
+- Project creation (`scrap new`) - currently a placeholder command
+- Template system with variable substitution
+- Basic command structure (build, run, clean) - currently placeholder commands
+- Configuration file parsing (`scrap.toml`)
 - Git-based template repository integration
 - Build system implementation
 - Toolchain management
@@ -226,13 +227,13 @@ cmake --build build/debug --parallel
 # Run tests
 cmake --build build/debug --target test
 
-# Or run tests directly
-./build/debug/test/scrap_test
+# Or run tests directly with ctest
+ctest --test-dir build/debug --output-on-failure
 ```
 
 ### Testing
 
-The project uses Catch2 v3.7.1 for unit testing. Tests are automatically built when `BUILD_TESTS=ON`.
+The project uses GoogleTest for unit testing, run through ctest. Tests are automatically built when `BUILD_TESTS=ON`.
 
 ```bash
 # Build and run all tests
@@ -241,23 +242,23 @@ cmake --build build/debug --target test
 # Run tests with verbose output
 ctest --test-dir build/debug --output-on-failure --verbose
 
-# Run specific test executable
-./build/debug/test/scrap_test
+# Run a specific test executable directly
+./build/debug/test/scrap_gtest
+./build/debug/test/scrap_gtest_cli11
 
 # Release build testing
 cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
 cmake --build build/release --target test
 ```
 
 **Test Structure:**
-- `test/unit/` - Unit tests for individual components
-- `test/helpers/` - Test utilities (TestPresenter, FileSystemHelper)
-- `test/fixtures/` - Test data and mock templates
+- `test/unit/command/` - Unit tests for the command layer
 
 ## 📊 Roadmap
 
 ### Phase 1: Foundation (Current)
-- ✅ Command structure and template system
+- ✅ Command structure (CLI framework)
+- 🚧 Template system
 - 🚧 Configuration management
 - 🚧 Basic build system
 

src/CMakeLists.txt

@@ -6,91 +6,31 @@ configure_file(
     @ONLY
 )
 
-add_executable(${PROJECT_NAME} ${SCRAP_SOURCES})
+add_executable(${PROJECT_NAME} ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
 
 target_sources(${PROJECT_NAME} PRIVATE
-    ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp
     # Generated version source
     ${CMAKE_CURRENT_BINARY_DIR}/shared/constants/version.cpp
-    # New command architecture
+    # Command architecture
     ${CMAKE_CURRENT_SOURCE_DIR}/command/Application.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/command/BuiltinCommandResolver.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/CommandCatalog.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/CommandHandler.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/CommandResolver.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/command/ParserAdapter.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/command/HelpRenderer.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/command/VersionRenderer.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/DefaultHelpRenderer.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/DefaultVersionRenderer.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/command/BuiltinCommandResolver.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/ExternalCommandResolver.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/ExternalMetadataProvider.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/command/HelpRenderer.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/command/ParserAdapter.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/ProjectCommandResolver.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/ScriptsReader.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/StubScriptsReader.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/command/VersionRenderer.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/command/driver/CLI11ParserAdapter.cpp
-    # Legacy command components (to be removed in main.cpp migration)
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/Application.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/Operation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/CompositeOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/CommandDispatcher.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/ApplicationCommandHandler.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/HelpCommand.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/CommandOptions.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/ParsedOptions.cpp
-    # CLI driver implementations
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/driver/CLI11Parser.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/driver/CLI11CommandDispatcher.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/command/driver/PresenterFormatter.cpp
-    # Presentation components
-    ${CMAKE_CURRENT_SOURCE_DIR}/shared/presentation/driver/ConsolePresenter.cpp
-    # Repository components
-    ${CMAKE_CURRENT_SOURCE_DIR}/repository/model/Repository.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/repository/RepositoryFactory.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/repository/driver/GitDriver.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/repository/driver/LibGitRepository.cpp
-    # Toolchain components
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/ToolchainModule.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/model/Toolchain.cpp
-    # ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/service/ToolchainService.cpp  # Old implementation
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/service/MockToolchainService.cpp
-    # ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/driver/ToolchainRepository.cpp  # Old implementation
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/command/ToolchainOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/command/ListOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/command/InstallOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/toolchain/command/SelectOperation.cpp
-    # Project components
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/ProjectModule.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/model/Project.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/model/ProjectError.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/service/MockProjectService.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/command/NewOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/command/BuildOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/command/RunOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/project/command/CleanOperation.cpp
-    # Configuration components
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/ConfigurationModule.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/model/ConfigurationSource.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/model/Configuration.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/model/ProjectConfiguration.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/model/ConfigurationError.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/model/ToolchainReference.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/service/ConfigurationService.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/service/DefaultConfigurationService.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/service/ConfigurationServiceError.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/driver/TomlDriver.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/driver/TomlPlusPlusDriver.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/configuration/driver/TomlDriverError.cpp
-    # Template components
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/TemplateModule.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/model/Template.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/model/TemplateError.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/service/TemplateService.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/service/TemplateServiceError.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/service/TemplateProcessor.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/command/TemplateOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/command/ListOperation.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/template/command/UpdateOperation.cpp
+    # Composition root helpers
+    ${CMAKE_CURRENT_SOURCE_DIR}/command/NullMetadataProvider.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/command/RuntimeEnvironmentFactory.cpp
 )
 
 target_compile_options(${PROJECT_NAME} PUBLIC
@@ -112,14 +52,8 @@ set_target_properties(${PROJECT_NAME} PROPERTIES
     OUTPUT_NAME "scrap"
 )
 
-find_package(Dross REQUIRED)
-find_package(Git2 REQUIRED)
 find_package(CLI11 REQUIRED)
-find_package(TomlPlusPlus REQUIRED)
 
 target_link_libraries(${PROJECT_NAME} PRIVATE
-    dross
-    libgit2package
     CLI11::CLI11
-    tomlplusplus::tomlplusplus
 )

src/command/Application.cpp

@@ -70,6 +70,11 @@ auto Application::run(std::span<const char* const> argv, const RuntimeEnvironmen
             return 1;
         }
         auto handler = entry->createHandler(invocation.options);
+        if (handler == nullptr) {
+            std::cerr << "Command '" << invocation.commandPath << "' is not available yet.\n";
+            std::cerr << "Run 'scrap --help' for usage information.\n";
+            return 1;
+        }
         const InvocationContext ctx{invocation.options, &env, &catalog};
         return handler->execute(ctx);
     }

src/command/ExternalCommandResolver.cpp

@@ -12,6 +12,7 @@
 #include <memory>
 #include <string>
 #include <string_view>
+#include <system_error>
 #include <utility>
 #include <vector>
 
@@ -26,14 +27,18 @@ constexpr std::string_view ExternalPrefix = "scrap-";
  */
 auto isScrapExecutable(const std::filesystem::directory_entry& entry) -> bool
 {
-    if (! entry.is_regular_file()) {
+    std::error_code ec;
+    if (! entry.is_regular_file(ec) || ec) {
         return false;
     }
     auto filename = entry.path().filename().string();
     if (! filename.starts_with(ExternalPrefix)) {
         return false;
     }
-    auto status = std::filesystem::status(entry.path());
+    auto status = std::filesystem::status(entry.path(), ec);
+    if (ec) {
+        return false;
+    }
     return (status.permissions() & std::filesystem::perms::owner_exec) != std::filesystem::perms::none;
 }
 
@@ -95,12 +100,13 @@ auto ExternalCommandResolver::resolve(const RuntimeEnvironment& env) -> std::vec
     std::vector<CommandEntry> entries;
 
     for (const auto& searchPath : env.searchPaths) {
-        if (! std::filesystem::is_directory(searchPath)) {
+        std::error_code ec;
+        if (! std::filesystem::is_directory(searchPath, ec) || ec) {
             continue;
         }
-        for (const auto& dirEntry : std::filesystem::directory_iterator(searchPath)) {
-            if (isScrapExecutable(dirEntry)) {
-                entries.push_back(buildEntry(dirEntry.path(), metadataProvider_.get()));
+        for (std::filesystem::directory_iterator it(searchPath, ec), end; ! ec && it != end; it.increment(ec)) {
+            if (isScrapExecutable(*it)) {
+                entries.push_back(buildEntry(it->path(), metadataProvider_.get()));
             }
         }
     }

src/command/NullMetadataProvider.cpp

@@ -0,0 +1,20 @@
+#include "command/NullMetadataProvider.h"
+
+#include "command/ExternalMetadataProvider.h"
+
+#include <filesystem>
+#include <string>
+
+namespace scrap::Command {
+
+/**
+ * Always return an error indicating the metadata protocol is not yet implemented.
+ */
+// NOLINTNEXTLINE(readability-convert-member-functions-to-static) — virtual override
+auto NullMetadataProvider::fetch([[maybe_unused]] const std::filesystem::path& executable)
+    -> std::expected<ExternalCommandMetadata, std::string>
+{
+    return std::unexpected(std::string{"external metadata protocol not yet implemented"});
+}
+
+}  // namespace scrap::Command

src/command/NullMetadataProvider.h

@@ -0,0 +1,31 @@
+#pragma once
+
+#include "command/ExternalMetadataProvider.h"
+
+#include <expected>
+#include <filesystem>
+#include <string>
+
+namespace scrap::Command {
+
+/**
+ * @brief Metadata provider stub used until the external metadata protocol lands.
+ *
+ * External commands are still discovered by ExternalCommandResolver via
+ * filesystem scanning; this provider simply reports that fetching rich
+ * metadata (name/description/options) is not yet supported. The real
+ * --scrap-metadata protocol is implemented in a later phase.
+ */
+class NullMetadataProvider final : public ExternalMetadataProvider {
+public:
+    /**
+     * @brief Always report metadata fetching as unimplemented.
+     *
+     * @param executable Path to the scrap-* executable (unused).
+     * @return An error describing that the protocol is not yet implemented.
+     */
+    [[nodiscard]] auto
+    fetch(const std::filesystem::path& executable) -> std::expected<ExternalCommandMetadata, std::string> override;
+};
+
+}  // namespace scrap::Command

src/command/RuntimeEnvironmentFactory.cpp

@@ -0,0 +1,42 @@
+#include "command/RuntimeEnvironmentFactory.h"
+
+#include "command/RuntimeEnvironment.h"
+
+#include <cstddef>
+#include <filesystem>
+#include <string>
+
+namespace scrap::Command {
+
+/**
+ * Build a RuntimeEnvironment from the given cwd, SCRAP_HOME, and PATH values.
+ */
+auto makeRuntimeEnvironment(const std::filesystem::path& cwd,
+                            const std::string& scrapHome,
+                            const std::string& pathEnv) -> RuntimeEnvironment
+{
+    RuntimeEnvironment env;
+    env.projectRoot = cwd;
+
+    if (! scrapHome.empty()) {
+        env.searchPaths.emplace_back(std::filesystem::path(scrapHome) / "bin");
+    }
+
+    std::size_t start = 0;
+    while (start <= pathEnv.size()) {
+        auto separator = pathEnv.find(':', start);
+        auto segment =
+            (separator == std::string::npos) ? pathEnv.substr(start) : pathEnv.substr(start, separator - start);
+        if (! segment.empty()) {
+            env.searchPaths.emplace_back(segment);
+        }
+        if (separator == std::string::npos) {
+            break;
+        }
+        start = separator + 1;
+    }
+
+    return env;
+}
+
+}  // namespace scrap::Command

src/command/RuntimeEnvironmentFactory.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include "command/RuntimeEnvironment.h"
+
+#include <filesystem>
+#include <string>
+
+namespace scrap::Command {
+
+/**
+ * @brief Build a RuntimeEnvironment from raw process inputs.
+ *
+ * Pure function: projectRoot and searchPaths are derived solely from the
+ * arguments, without reading environment variables or touching the
+ * filesystem. Callers (e.g. main()) are responsible for reading SCRAP_HOME
+ * and PATH and for resolving the current working directory.
+ *
+ * @param cwd       Current working directory, used as projectRoot.
+ * @param scrapHome Value of SCRAP_HOME, or empty if unset. When non-empty,
+ *                  "<scrapHome>/bin" is prepended to searchPaths.
+ * @param pathEnv   Value of PATH, colon-separated. Empty segments (from
+ *                  leading, trailing, or doubled colons) are skipped.
+ * @return Constructed RuntimeEnvironment.
+ */
+[[nodiscard]] auto makeRuntimeEnvironment(const std::filesystem::path& cwd,
+                                          const std::string& scrapHome,
+                                          const std::string& pathEnv) -> RuntimeEnvironment;
+
+}  // namespace scrap::Command