[Nexthop] Add basic utilities for FBOSS Image Builder

Provide basic tools and utiulities for the distro_cli build system.

- Add custom exception classes for structured error handling
- Define shared constants for Docker configuration and build settings
- Implement path resolution utilities for components
- Define test data fixture for image manifest validation

These core utilities provide the base infrastructure required by all downstream components including Docker integration, artifact handling, and build orchestration.

Author: raghav-nexthop

fboss-image/distro_cli/lib/constants.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2004-present, Facebook, Inc.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree. An additional grant
+# of patent rights can be found in the PATENTS file in the same directory.
+
+"""Constants for FBOSS image builder."""
+
+# Docker image names
+FBOSS_BUILDER_IMAGE = "fboss_builder"

fboss-image/distro_cli/lib/exceptions.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2004-present, Facebook, Inc.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree. An additional grant
+# of patent rights can be found in the PATENTS file in the same directory.
+
+"""Exception definitions for FBOSS image builder."""
+
+
+class FbossImageError(Exception):
+    """Base exception for all fboss-image errors.
+
+    All custom exceptions in the fboss-image tool should inherit from this.
+    This allows the top-level CLI handler to catch and format errors appropriately
+    before returning a non-zero exit code.
+    """
+
+
+class BuildError(FbossImageError):
+    """Build command failed.
+
+    Raised when a component build fails, including:
+    - Build script/command not found
+    - Build process returned non-zero exit code
+    - Build output validation failed
+    """
+
+
+class ManifestError(FbossImageError):
+    """Manifest parsing or validation failed.
+
+    Raised when:
+    - Manifest file not found or invalid JSON
+    - Required fields missing
+    - Invalid manifest structure
+    """
+
+
+class ArtifactError(FbossImageError):
+    """Artifact operation failed.
+
+    Raised when:
+    - Expected artifact not found after build
+    - Artifact download failed
+    - Artifact cache operation failed
+    """
+
+
+class ComponentError(FbossImageError):
+    """Component-specific error.
+
+    Raised when:
+    - Component not found in manifest
+    - Component configuration invalid
+    - Component builder not implemented
+    """

fboss-image/distro_cli/lib/paths.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2004-present, Facebook, Inc.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree. An additional grant
+# of patent rights can be found in the PATENTS file in the same directory.
+
+"""Path resolution utilities for FBOSS image builder."""
+
+from functools import lru_cache
+from pathlib import Path
+
+
+@lru_cache(maxsize=1)
+def get_root_dir() -> Path:
+    """Find the repository root directory.
+
+    This works by walking up from the current file until we find
+    the 'fboss-image' directory, then returning its parent.
+
+    Additionally verifies that both 'fboss-image' and 'fboss' directories
+    exist at the root to ensure we're in the correct repository structure.
+
+    The result is cached after the first call for performance.
+
+    Returns:
+        Path to repository root directory
+
+    Raises:
+        RuntimeError: If the root directory cannot be determined
+    """
+    current = Path(__file__).resolve()
+
+    # Walk up the directory tree looking for fboss-image
+    for parent in current.parents:
+        if (parent / "fboss-image").is_dir() and (parent / "fboss").is_dir():
+            return parent
+
+    raise RuntimeError(
+        f"Could not find repository root from {current}. "
+        f"Expected to find 'fboss-image' and 'fboss' directories in parent path."
+    )
+
+
+def get_abs_path(path_parts: str | list[str]) -> Path:
+    """Get absolute path by joining the parent of 'fboss-image' with provided path parts.
+
+    Args:
+        path_parts: Either a string like "fboss-image/distro_cli/tools" or
+                   a list like ["fboss-image", "distro_cli", "tools"]
+
+    Returns:
+        Absolute path
+
+    Examples:
+        get_abs_path("fboss-image/distro_cli/tools")
+        get_abs_path(["fboss-image", "distro_cli", "tools"])
+        get_abs_path("fboss/oss/scripts")
+    """
+    root = get_root_dir()
+
+    if isinstance(path_parts, str):
+        return root / path_parts
+    return root.joinpath(*path_parts)

fboss-image/distro_cli/tests/dev_image.json

@@ -1,27 +1,27 @@
 {
   "distribution_formats": {
-    "onie": "FBOSS-k6.4.3.bin",
-    "usb": "FBOSS-k6.4.3.iso"
+    "onie": "FBOSS-k6.11.1.bin",
+    "usb": "FBOSS-k6.11.1iso"
   },
   "kernel": {
-    "download": "https://artifact.github.com/nexthop-ai/fboss/fboss-oss_kernel_v6.4.3.tar"
+    "download": "https://artifact.github.com/nexthop-ai/fboss/fboss-oss_kernel_v6.11.1.tar"
   },
   "other_dependencies": [
     {"download": "https://artifact.github.com/nexthop-ai/fsdb/fsdb.rpm"},
     {"download": "file:vendor_debug_tools/tools.rpm"}
   ],
   "fboss-platform-stack": {
-    "execute": ["fboss/fboss/oss/scripts/build.py", "platformstack"]
+    "execute": ["../../../../fboss/fboss/oss/scripts/build.py", "platformstack"]
   },
   "bsps": [
-    {"execute": "vendor_bsp/build.make"},
-    {"execute": "fboss/oss/reference_bsp/build.py"}
+    {"execute": ["../../../../vendor_bsp/build.make"]},
+    {"execute": ["../../../../fboss/oss/reference_bsp/build.py"]}
   ],
   "sai": {
-    "execute": "fboss_brcm_sai/build.sh"
+    "execute": ["../../../../fboss_brcm_sai/build.sh"]
   },
   "fboss-forwarding-stack": {
-    "execute": ["fboss/fboss/oss/scripts/build.py", "forwardingstack"]
+    "execute": ["../../../../fboss/fboss/oss/scripts/build.py", "forwardingstack"]
   },
   "image_build_hooks": {
     "after_pkgs": "additional_os_pkgs.xml"