feat(build): Add build module and BuildMetadata class

Author: Ishirui

src/dda/build/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025-present Datadog, Inc. <dev@datadoghq.com>
+#
+# SPDX-License-Identifier: MIT

src/dda/build/metadata/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025-present Datadog, Inc. <dev@datadoghq.com>
+#
+# SPDX-License-Identifier: MIT

src/dda/build/metadata/enums.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: 2025-present Datadog, Inc. <dev@datadoghq.com>
+#
+# SPDX-License-Identifier: MIT
+
+from enum import StrEnum
+
+from dda.utils.enums import AliasedStrEnum
+
+
+class ArtifactFormat(StrEnum):
+    """
+    The format of the build artifact.
+    """
+
+    BIN = "bin"
+    SRC = "src"  # Source code tarball
+    DEB = "deb"
+    RPM = "rpm"
+    MSI = "msi"
+    CFG = "cfg"  # Configuration files tarball
+    DOCKER = "docker"  # Docker container image
+
+
+class OS(AliasedStrEnum):
+    """
+    The operating system for which the build artifact is intended.
+    """
+
+    LINUX = "linux"
+    WINDOWS = ("windows", "nt", "win")
+    MACOS = ("macos", "darwin", "osx")
+
+
+class Arch(AliasedStrEnum):
+    """
+    The CPU architecture for which the build artifact is intended.
+    """
+
+    # x86 architectures - canonical name is amd64
+    AMD64 = ("amd64", "x86_64", "x86-64", "x64", "x86")
+
+    # ARM architectures - canonical name is arm64
+    ARM64 = ("arm64", "aarch64")
+
+    # ARMHF architectures
+    ARMHF = "armhf"

src/dda/build/metadata/metadata.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2025-present Datadog, Inc. <dev@datadoghq.com>
+#
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from dda.build.metadata.enums import OS, Arch, ArtifactFormat
+
+if TYPE_CHECKING:
+    from click import Context
+
+    from dda.cli.application import Application
+    from dda.utils.git.changeset import ChangeSet
+    from dda.utils.git.commit import Commit
+
+
+@dataclass
+class BuildMetadata:
+    """
+    Metadata about a build that can be used to identify it.
+    """
+
+    agent_component: str
+    artifact_format: ArtifactFormat
+    commit: Commit
+    arch: Arch
+    os: OS
+    build_time: datetime
+
+    worktree_diff: ChangeSet
+
+    @property
+    def platform(self) -> str:
+        """
+        Return the platform string in the format `os-arch`.
+        """
+        return f"{self.os}-{self.arch}"
+
+    @classmethod
+    def this(cls, ctx: Context, app: Application) -> BuildMetadata:
+        """
+        Create a BuildMetadata instance for the current build.
+        """
+        import platform
+
+        # Current time
+        build_time = datetime.now()  # noqa: DTZ005
+
+        # Parse calling command - the two last parts are the component and format respectively
+        # e.g. `dda build core-agent bin` -> `core-agent` and `bin`
+        command_parts = ctx.command_path.split(" ")
+        if command_parts[-3] != "build":
+            msg = f"Unexpected command path, BuildMetadata.this can only be called from within: {ctx.command_path}"
+            raise ValueError(msg)
+
+        agent_component = command_parts[-2]
+        artifact_format = ArtifactFormat(command_parts[-1])
+
+        # Arch and OS
+        arch = Arch(platform.machine())
+        os = OS(platform.system().lower())
+
+        # Get worktree information - base commit and diff hash
+        worktree_diff = app.tools.git.get_working_tree_changes()
+        commit = app.tools.git.get_head_commit()
+
+        return cls(
+            agent_component=agent_component,
+            artifact_format=artifact_format,
+            commit=commit,
+            arch=arch,
+            os=os,
+            build_time=build_time,
+            worktree_diff=worktree_diff,
+        )