myxce/.kiro/specs/eliminate-frontend-makefile/requirements.md

Requirements Document

Introduction

src/frontend/Makefile and Meson's tools/go_build wrapper are two independent, parallel build orchestration paths for the same two Go binaries (apiserver, xcecli), each independently computing the same version-fingerprint logic (commit_id/build_time/dirty_fingerprint). This duplication has already caused a real defect (a shell exit-status bug in the Makefile's independent fingerprint computation, dirty-content-fingerprint task 4.3) and the Makefile's own build-server target is independently confirmed currently broken (bug-1597) — the project's own documentation already tells developers to avoid it in favor of /xce-build apiserver.

This feature removes src/frontend/Makefile entirely and consolidates all apiserver/xcecli build and test execution onto Meson, so exactly one build system exists for these components going forward. This is a confirmed decision, not an option to weigh during design: Meson is retained, the Makefile is deleted outright, not kept as a thin or compatibility wrapper.

Boundary Context

• In scope: removing src/frontend/Makefile; ensuring apiserver/xcecli builds, unit tests, CGO-backed backend tests, and the integration/regression test suite are all runnable through Meson or direct, documented, Makefile-free invocations; updating any project script or documentation that discovers a built binary via a Makefile-specific fixed path or instructs a developer to run a Makefile target.
• Out of scope: changing the underlying version-fingerprint computation itself (the single surviving source of truth is unchanged, only the duplicate second computation is removed); changing the CGO build-flag derivation Meson's apiserver build already performs (this feature reuses it, it does not redesign it); rewriting historical/frozen spec documents (e.g. tasks.md/research.md/design.md of already-completed specs) that reference Makefile targets as acceptance criteria for work already shipped; fixing unrelated, adjacent build-tooling defects noted during investigation (e.g. component-failover-adoption's set -euo pipefail CGO-test-skip issue).
• Adjacent expectations: this feature depends on Meson's existing apiserver build already deriving correct CGO flags — that derivation is reused, not duplicated, for backend test execution. Downstream scripts that discover apiserver/xcecli binaries (e.g. HA deploy scripts, resource-verification scripts) must continue to find a usable binary after this change; none of them may be left depending on a Makefile-specific fixed output path once the Makefile is gone.

Requirements

Requirement 1: Single Build Path for Go Binaries

Objective: As a developer, I want apiserver and xcecli to be built through exactly one system, so that build logic and version-fingerprint computation cannot silently drift out of sync between two independent implementations.

Acceptance Criteria

1. When a developer builds apiserver or xcecli through the project's canonical build tooling, the system shall produce the binary without invoking any src/frontend/Makefile target.
2. The system shall compute each binary's version-fingerprint information (commit id, build time, dirty-content fingerprint) from exactly one implementation, not from two independently maintained computations.
3. The system shall not include a src/frontend/Makefile file once the build, unit-test, backend-test, and integration-test capabilities described in Requirements 1-4 are all available without it.

Requirement 2: Go Unit Test Execution Without the Makefile

Objective: As a developer, I want apiserver/xcecli unit tests runnable without src/frontend/Makefile, so that test execution is not split across two orchestration systems.

Acceptance Criteria

1. When the project's canonical build tooling runs apiserver or xcecli unit tests, the system shall do so without invoking src/frontend/Makefile's test target.
2. The system shall preserve existing unit-test behavior (no external dependencies, no live server required) after this change.
3. If a unit test fails, then the system shall report the failure in a form at least as clear and actionable as the current Makefile-driven output (test name, failure reason).

Requirement 3: CGO-Backed Backend Test Coverage Preserved

Objective: As a developer, I want the CGO-backed backend test suite runnable without src/frontend/Makefile, so that removing the Makefile does not silently drop test coverage.

Acceptance Criteria

1. The system shall provide a way to run the full CGO-backed backend test suite that does not depend on src/frontend/Makefile.
2. When the CGO-backed backend test suite runs, the system shall derive its CGO build flags from the same single source Meson's apiserver build already uses, not from a second, independently maintained derivation.
3. The system shall not reduce CGO-backed backend test coverage at any point during this migration — an equivalent, Makefile-free way to run this suite shall exist before src/frontend/Makefile's test-backend target is removed.

Requirement 4: Integration/Regression Test Suite Targets a Canonical Build

Objective: As a developer, I want to run the apiserver integration/regression test suite against a binary built by the project's canonical tooling, so that verification does not require a Makefile-built artifact.

Acceptance Criteria

1. When a developer runs the integration/regression test suite, the system shall accept a binary built by the project's canonical (Makefile-free) build tooling as the target under test.
2. The system shall not require src/frontend/Makefile's build-cli or build-server targets to produce the binary under test.
3. The system shall preserve the existing regression suite's scope and pass/fail criteria after this change.

Requirement 5: Binary Discovery Independent of Makefile-Specific Paths

Objective: As an operator or script maintainer, I want project scripts that locate a built apiserver or xcecli binary to do so without depending on a Makefile-specific fixed output path, so that removing the Makefile does not break deployment or verification tooling.

Acceptance Criteria

1. When a project script needs to locate a built apiserver or xcecli binary, the system shall discover it from the canonical build tooling's output location as the primary source.
2. If no binary is found at the canonical build tooling's output location, then the system shall report an error or warning that names the canonical (Makefile-free) build command to run, and shall not instruct the operator to run a src/frontend/Makefile target that no longer exists.
3. The system shall not require any project script to depend on a src/frontend/Makefile-specific fixed output path (e.g. /tmp/apiserver, /tmp/xce_static) as its only means of locating a built binary.

Requirement 6: Documentation Reflects a Single Build System

Objective: As a developer or operator reading project documentation, I want build and test instructions to reference only the surviving build system, so that I am never directed to run a target that no longer exists.

Acceptance Criteria

1. When live (non-historical) project documentation describes how to build or test apiserver/xcecli, the system's documentation shall reference only the canonical Makefile-free build/test commands.
2. The system shall not retain any live documentation instructing a developer to run a src/frontend/Makefile target.
3. Where a historical, already-completed spec document references a Makefile target as a frozen record of past acceptance criteria, the system shall leave that document unchanged — this requirement applies only to live, currently-authoritative documentation.