Start assets component image signature tests

CMakeLists.txt

@@ -65,6 +65,18 @@ target_link_libraries(pp_foundation
     PRIVATE
         pp_project_warnings)
 
+add_library(pp_assets STATIC
+    src/assets/image_format.cpp)
+target_include_directories(pp_assets
+    PUBLIC
+        "${CMAKE_CURRENT_SOURCE_DIR}/src")
+target_link_libraries(pp_assets
+    PUBLIC
+        pp_foundation
+        pp_project_options
+    PRIVATE
+        pp_project_warnings)
+
 if(PP_BUILD_TOOLS)
     add_subdirectory(tools/pano_cli)
 endif()

docs/modernization/build-inventory.md

@@ -74,7 +74,8 @@ Known local toolchain state:
 - Android SDK: `C:\Users\omara\AppData\Local\Android\Sdk`
 - Android NDK: `C:\Users\omara\AppData\Local\Android\Sdk\ndk\29.0.14206865`
 - Android arm64 headless configure/build passes through root CMake and the
-  `platform-build` automation wrapper.
+  `platform-build` automation wrapper for `pp_foundation`, `pp_assets`,
+  `pano_cli`, and their current headless test binaries.
 - `vcpkg` is not on PATH yet; see DEBT-0007.
 
 Known warnings after the current CMake app build:

docs/modernization/roadmap.md

@@ -243,9 +243,9 @@ Goal: make each component reachable by automated tools and future agents.
 
 Status: in progress. `tests/` exists, `desktop-fast` runs headlessly, and
 PowerShell/bash wrappers exist for configure/build/test/analyze/platform-build.
-`pano_cli` exists with a first JSON automation command for validating
-create-document inputs; full document/app integration is debt-tracked as
-DEBT-0006.
+`pano_cli` exists with JSON automation commands for validating create-document
+inputs and inspecting image signatures; full document/app integration is
+debt-tracked as DEBT-0006.
 
 Implementation tasks:
 
@@ -302,8 +302,9 @@ Status: started. `pp_foundation` exists with binary stream utilities and
 boundary/overread tests. It also owns strict decimal `uint32` parsing used by
 `pano_cli`, with rejection tests for empty, signed, mixed, and overflowing
 input. A deterministic `TraceRecorder` now records component/name/thread/frame
-and stroke timing spans with invalid-end tests. Continue extracting legacy-safe
-utilities before moving assets, paint, or document behavior.
+and stroke timing spans with invalid-end tests. `pp_assets` has started with
+PNG/JPEG signature detection and corrupt/truncated/unsupported tests. Continue
+extracting legacy-safe utilities before moving paint or document behavior.
 
 Implementation tasks:
 
@@ -503,7 +504,7 @@ Last verified on 2026-05-31:
 
 ```powershell
 cmake --preset windows-msvc-default
-cmake --build --preset windows-msvc-default --config Debug --target pp_foundation_binary_stream_tests pp_foundation_parse_tests pp_foundation_trace_tests pano_cli PanoPainter
+cmake --build --preset windows-msvc-default --config Debug --target pp_foundation_binary_stream_tests pp_foundation_parse_tests pp_foundation_trace_tests pp_assets_image_format_tests pano_cli PanoPainter
 ctest --preset desktop-fast --build-config Debug
 powershell -ExecutionPolicy Bypass -File scripts\automation\test.ps1 -Preset desktop-fast -Configuration Debug
 powershell -ExecutionPolicy Bypass -File scripts\automation\build.ps1 -Preset windows-msvc-default -Configuration Debug -Target pano_cli
@@ -516,7 +517,10 @@ Results:
 - `pp_foundation_binary_stream_tests` passed.
 - `pp_foundation_parse_tests` passed.
 - `pp_foundation_trace_tests` passed.
+- `pp_assets_image_format_tests` passed.
 - `pano_cli_create_document_smoke` passed.
+- `pano_cli_inspect_image_rejects_unsupported` passed as an expected failure
+  test.
 - `PanoPainter.exe` built through CMake at
   `out/build/windows-msvc-default/Debug/PanoPainter.exe`.
 - PowerShell build/test automation wrappers return JSON summaries and passed

scripts/automation/platform-build.ps1

@@ -1,7 +1,7 @@
 [CmdletBinding()]
 param(
     [string[]]$Presets = @("android-arm64"),
-    [string[]]$Targets = @("pp_foundation", "pano_cli", "pp_foundation_binary_stream_tests", "pp_foundation_parse_tests", "pp_foundation_trace_tests")
+    [string[]]$Targets = @("pp_foundation", "pp_assets", "pano_cli", "pp_foundation_binary_stream_tests", "pp_foundation_parse_tests", "pp_foundation_trace_tests", "pp_assets_image_format_tests")
 )
 
 $ErrorActionPreference = "Stop"

scripts/automation/platform-build.sh

@@ -3,7 +3,7 @@ set -u
 
 preset="${1:-android-arm64}"
 shift || true
-targets="${*:-pp_foundation pano_cli pp_foundation_binary_stream_tests pp_foundation_parse_tests pp_foundation_trace_tests}"
+targets="${*:-pp_foundation pp_assets pano_cli pp_foundation_binary_stream_tests pp_foundation_parse_tests pp_foundation_trace_tests pp_assets_image_format_tests}"
 start="$(date +%s)"
 
 cmake --preset "$preset"

src/assets/image_format.cpp

@@ -0,0 +1,94 @@
+#include "assets/image_format.h"
+
+#include <array>
+#include <cstdint>
+
+namespace pp::assets {
+
+namespace {
+
+constexpr std::array png_signature {
+    std::byte { 0x89 },
+    std::byte { 0x50 },
+    std::byte { 0x4e },
+    std::byte { 0x47 },
+    std::byte { 0x0d },
+    std::byte { 0x0a },
+    std::byte { 0x1a },
+    std::byte { 0x0a },
+};
+
+[[nodiscard]] bool starts_with(std::span<const std::byte> bytes, std::span<const std::byte> prefix) noexcept
+{
+    if (bytes.size() < prefix.size()) {
+        return false;
+    }
+
+    for (std::size_t i = 0; i < prefix.size(); ++i) {
+        if (bytes[i] != prefix[i]) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+[[nodiscard]] bool is_prefix_of(std::span<const std::byte> bytes, std::span<const std::byte> signature) noexcept
+{
+    if (bytes.size() >= signature.size()) {
+        return false;
+    }
+
+    for (std::size_t i = 0; i < bytes.size(); ++i) {
+        if (bytes[i] != signature[i]) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+}
+
+pp::foundation::Result<ImageFormat> detect_image_format(std::span<const std::byte> bytes) noexcept
+{
+    if (bytes.empty()) {
+        return pp::foundation::Result<ImageFormat>::failure(
+            pp::foundation::Status::invalid_argument("image data must not be empty"));
+    }
+
+    if (starts_with(bytes, png_signature)) {
+        return pp::foundation::Result<ImageFormat>::success(ImageFormat::png);
+    }
+
+    if (is_prefix_of(bytes, png_signature)) {
+        return pp::foundation::Result<ImageFormat>::failure(
+            pp::foundation::Status::out_of_range("image data is a truncated PNG signature"));
+    }
+
+    if (bytes.size() < 3U) {
+        return pp::foundation::Result<ImageFormat>::failure(
+            pp::foundation::Status::out_of_range("image data is too short to identify"));
+    }
+
+    if (bytes[0] == std::byte { 0xff } && bytes[1] == std::byte { 0xd8 } && bytes[2] == std::byte { 0xff }) {
+        return pp::foundation::Result<ImageFormat>::success(ImageFormat::jpeg);
+    }
+
+    return pp::foundation::Result<ImageFormat>::failure(
+        pp::foundation::Status::invalid_argument("unsupported image signature"));
+}
+
+const char* image_format_name(ImageFormat format) noexcept
+{
+    switch (format) {
+    case ImageFormat::png:
+        return "png";
+    case ImageFormat::jpeg:
+        return "jpeg";
+    }
+
+    return "unknown";
+}
+
+}

src/assets/image_format.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#include "foundation/result.h"
+
+#include <cstddef>
+#include <span>
+
+namespace pp::assets {
+
+enum class ImageFormat {
+    png,
+    jpeg,
+};
+
+[[nodiscard]] pp::foundation::Result<ImageFormat> detect_image_format(
+    std::span<const std::byte> bytes) noexcept;
+
+[[nodiscard]] const char* image_format_name(ImageFormat format) noexcept;
+
+}

tests/CMakeLists.txt

@@ -36,9 +36,25 @@ add_test(NAME pp_foundation_trace_tests COMMAND pp_foundation_trace_tests)
 set_tests_properties(pp_foundation_trace_tests PROPERTIES
     LABELS "foundation;desktop-fast")
 
+add_executable(pp_assets_image_format_tests
+    assets/image_format_tests.cpp)
+target_link_libraries(pp_assets_image_format_tests PRIVATE
+    pp_assets
+    pp_test_harness)
+
+add_test(NAME pp_assets_image_format_tests COMMAND pp_assets_image_format_tests)
+set_tests_properties(pp_assets_image_format_tests PROPERTIES
+    LABELS "assets;desktop-fast")
+
 if(TARGET pano_cli)
     add_test(NAME pano_cli_create_document_smoke
         COMMAND pano_cli create-document --width 64 --height 32 --layers 2)
     set_tests_properties(pano_cli_create_document_smoke PROPERTIES
         LABELS "integration;desktop-fast")
+
+    add_test(NAME pano_cli_inspect_image_rejects_unsupported
+        COMMAND pano_cli inspect-image --path "${CMAKE_CURRENT_SOURCE_DIR}/data/images/unsupported-image.txt")
+    set_tests_properties(pano_cli_inspect_image_rejects_unsupported PROPERTIES
+        LABELS "assets;integration;desktop-fast"
+        WILL_FAIL TRUE)
 endif()

tests/assets/image_format_tests.cpp

@@ -0,0 +1,88 @@
+#include "assets/image_format.h"
+#include "test_harness.h"
+
+#include <array>
+#include <cstddef>
+#include <string_view>
+
+using pp::assets::ImageFormat;
+using pp::assets::detect_image_format;
+using pp::assets::image_format_name;
+using pp::foundation::StatusCode;
+
+namespace {
+
+void detects_png_and_jpeg_signatures(pp::tests::Harness& h)
+{
+    constexpr std::array png {
+        std::byte { 0x89 },
+        std::byte { 0x50 },
+        std::byte { 0x4e },
+        std::byte { 0x47 },
+        std::byte { 0x0d },
+        std::byte { 0x0a },
+        std::byte { 0x1a },
+        std::byte { 0x0a },
+        std::byte { 0x00 },
+    };
+    constexpr std::array jpeg {
+        std::byte { 0xff },
+        std::byte { 0xd8 },
+        std::byte { 0xff },
+        std::byte { 0xe0 },
+    };
+
+    const auto png_format = detect_image_format(png);
+    const auto jpeg_format = detect_image_format(jpeg);
+
+    PP_EXPECT(h, png_format.ok());
+    PP_EXPECT(h, png_format.value() == ImageFormat::png);
+    PP_EXPECT(h, image_format_name(png_format.value()) == std::string_view("png"));
+    PP_EXPECT(h, jpeg_format.ok());
+    PP_EXPECT(h, jpeg_format.value() == ImageFormat::jpeg);
+    PP_EXPECT(h, image_format_name(jpeg_format.value()) == std::string_view("jpeg"));
+}
+
+void rejects_empty_truncated_and_unsupported_inputs(pp::tests::Harness& h)
+{
+    constexpr std::array<std::byte, 0> empty {};
+    constexpr std::array partial_png {
+        std::byte { 0x89 },
+        std::byte { 0x50 },
+        std::byte { 0x4e },
+    };
+    constexpr std::array short_unknown {
+        std::byte { 0x12 },
+        std::byte { 0x34 },
+    };
+    constexpr std::array unsupported {
+        std::byte { 0x47 },
+        std::byte { 0x49 },
+        std::byte { 0x46 },
+        std::byte { 0x38 },
+    };
+
+    const auto empty_result = detect_image_format(empty);
+    const auto partial_png_result = detect_image_format(partial_png);
+    const auto short_result = detect_image_format(short_unknown);
+    const auto unsupported_result = detect_image_format(unsupported);
+
+    PP_EXPECT(h, !empty_result.ok());
+    PP_EXPECT(h, empty_result.status().code == StatusCode::invalid_argument);
+    PP_EXPECT(h, !partial_png_result.ok());
+    PP_EXPECT(h, partial_png_result.status().code == StatusCode::out_of_range);
+    PP_EXPECT(h, !short_result.ok());
+    PP_EXPECT(h, short_result.status().code == StatusCode::out_of_range);
+    PP_EXPECT(h, !unsupported_result.ok());
+    PP_EXPECT(h, unsupported_result.status().code == StatusCode::invalid_argument);
+}
+
+}
+
+int main()
+{
+    pp::tests::Harness harness;
+    harness.run("detects_png_and_jpeg_signatures", detects_png_and_jpeg_signatures);
+    harness.run("rejects_empty_truncated_and_unsupported_inputs", rejects_empty_truncated_and_unsupported_inputs);
+    return harness.finish();
+}

tests/data/images/unsupported-image.txt

@@ -0,0 +1 @@
+GIF8

tools/pano_cli/CMakeLists.txt

@@ -3,4 +3,5 @@ add_executable(pano_cli
 target_link_libraries(pano_cli PRIVATE
     pp_project_options
     pp_project_warnings
-    pp_foundation)
+    pp_foundation
+    pp_assets)

tools/pano_cli/main.cpp

@@ -1,9 +1,14 @@
+#include "assets/image_format.h"
 #include "foundation/parse.h"
 #include "foundation/result.h"
 
 #include <cstdint>
+#include <fstream>
 #include <iostream>
+#include <iterator>
+#include <string>
 #include <string_view>
+#include <vector>
 
 namespace {
 
@@ -13,6 +18,10 @@ struct DocumentArgs {
     std::uint32_t layers = 1;
 };
 
+struct InspectImageArgs {
+    std::string path;
+};
+
 void print_error(std::string_view command, std::string_view message)
 {
     std::cout << "{\"ok\":false,\"command\":\"" << command
@@ -24,6 +33,7 @@ void print_help()
     std::cout
         << "pano_cli commands:\n"
         << "  create-document --width N --height N [--layers N]\n"
+        << "  inspect-image --path FILE\n"
         << "  --help\n";
 }
 
@@ -81,6 +91,60 @@ int create_document(int argc, char** argv)
     return 0;
 }
 
+pp::foundation::Status parse_inspect_image_args(int argc, char** argv, InspectImageArgs& args)
+{
+    for (int i = 2; i < argc; ++i) {
+        const std::string_view key(argv[i]);
+        if (key == "--path") {
+            if (i + 1 >= argc) {
+                return pp::foundation::Status::invalid_argument("missing value for option");
+            }
+
+            args.path = argv[++i];
+        } else {
+            return pp::foundation::Status::invalid_argument("unknown option");
+        }
+    }
+
+    if (args.path.empty()) {
+        return pp::foundation::Status::invalid_argument("path must not be empty");
+    }
+
+    return pp::foundation::Status::success();
+}
+
+int inspect_image(int argc, char** argv)
+{
+    InspectImageArgs args;
+    const auto status = parse_inspect_image_args(argc, argv, args);
+    if (!status.ok()) {
+        print_error("inspect-image", status.message);
+        return 2;
+    }
+
+    std::ifstream stream(args.path, std::ios::binary);
+    if (!stream) {
+        print_error("inspect-image", "image file could not be opened");
+        return 2;
+    }
+
+    const std::vector<char> chars {
+        std::istreambuf_iterator<char>(stream),
+        std::istreambuf_iterator<char>()
+    };
+    const auto* data = reinterpret_cast<const std::byte*>(chars.data());
+    const auto format = pp::assets::detect_image_format(std::span<const std::byte>(data, chars.size()));
+    if (!format) {
+        print_error("inspect-image", format.status().message);
+        return 2;
+    }
+
+    std::cout << "{\"ok\":true,\"command\":\"inspect-image\",\"format\":\""
+              << pp::assets::image_format_name(format.value())
+              << "\",\"bytes\":" << chars.size() << "}\n";
+    return 0;
+}
+
 }
 
 int main(int argc, char** argv)
@@ -100,6 +164,10 @@ int main(int argc, char** argv)
         return create_document(argc, argv);
     }
 
+    if (command == "inspect-image") {
+        return inspect_image(argc, argv);
+    }
+
     print_error(command, "unknown command");
     return 2;
 }