installer: scope DirectAdmin adapter to control-plane only (Path A)

Clarifies PR26.3 scope after auditor disposition:

  - Top-level doc-comment: "control-plane only"; full DirectAdmin
    service-port surface (16+ public-facing ports) is NOT validated
    here — that lands in PR26.4 via
    internal/ports/panel_loader.LoadPanelConfig("directadmin") and
    /etc/nftban/conf.d/panels/directadmin/main.conf.
  - PR26.4 follow-up note inline at the top of directadmin.go.
  - ValidateReachability error message: explicitly says
    "control-plane port N not in LISTEN state — control-plane
    unreachable" so the user-facing AssertionResult.Detail (and
    log lines) cannot be misread as a full panel-survival claim.
  - New test: ErrorMentionsControlPlane (positive: "control-plane"
    is in the message; negative: no affirmative full-surface claim).
  - New test: Reason_DoesNotImplyFullPortSurvival at the framework
    integration layer.
  - Tightened existing TestFrameworkIntegration_DA_Detected_NotReachable_Blocks
    to assert the surfaced Reason mentions "control-plane".

No internal/ports import in this PR (deliberately deferred to
PR26.4). No new mutation surface; adapter remains read-only. No
cPanel/Plesk/classifier/restore code added.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: itcmsgr

internal/installer/panelfw/adapters/directadmin/directadmin.go

@@ -20,10 +20,33 @@
 // First and only adapter shipped in this PR. cPanel/Plesk/etc. live in
 // future PRs under the same framework.
 //
+// SCOPE — CONTROL PLANE ONLY (PR26.3)
+// -----------------------------------
+// This adapter validates DirectAdmin **control-plane reachability**
+// only. It detects DirectAdmin and validates the DirectAdmin control
+// port (TCP 2222 by default, per-config override via directadmin.conf
+// `port=N`).
+//
+// It does NOT yet validate the full DirectAdmin service-port surface
+// (the 16+ public-facing ports DirectAdmin manages on behalf of
+// hosted accounts: SMTP/SMTPS, IMAP/IMAPS, POP3/POP3S, FTP/FTPS, SSH,
+// HTTP/HTTPS, DNS, etc.). Those are tracked separately by the
+// canonical /etc/nftban/conf.d/panels/directadmin/main.conf and are
+// loaded by internal/ports/panel_loader.LoadPanelConfig — neither of
+// which this adapter consumes.
+//
+// PR26.4 follow-up:
+//   Full port-surface validation MUST reuse
+//   internal/ports/panel_loader.LoadPanelConfig("directadmin") and the
+//   canonical conf.d panel config. PR26.3 deliberately does not import
+//   internal/ports — that import lands in PR26.4 so the control-plane
+//   assertion ships narrowly first and full-surface validation is a
+//   separate, separately-reviewed change.
+//
 // Read-only by interface contract:
 //   - Detect:               filesystem stat + service-active query + ss listener parse
 //   - RequiredPorts:        config-file read (best-effort); falls back to default 2222
-//   - ValidateReachability: ss -lnt output parse for the required port
+//   - ValidateReachability: ss -lnt output parse for the control port
 //
 // No mutation surface: no nft, no service writes, no file writes, no
 // shell out beyond the read-only `systemctl is-active` and `ss -lnt`
@@ -148,15 +171,22 @@ func (a *adapter) RequiredPorts(ctx context.Context, exec executor.Executor) ([]
 
 // ValidateReachability implements panelfw.PanelAdapter. Read-only.
 //
-// Confirms the required TCP port is in LISTEN state. Returns nil on
-// success; a structured error otherwise. Does NOT mutate ports,
-// services, or rules.
+// Confirms the DirectAdmin **control-plane** TCP port is in LISTEN
+// state. Returns nil on success; a structured error otherwise. Does
+// NOT mutate ports, services, or rules.
+//
+// Scope is the control plane (default 2222) only. The full DirectAdmin
+// service-port surface (mail/web/SSH/etc.) is NOT validated here —
+// see the file-level "PR26.4 follow-up" comment.
 func (a *adapter) ValidateReachability(ctx context.Context, exec executor.Executor) error {
 	port := readConfiguredPort(exec)
 	if portInListenState(exec, port) {
 		return nil
 	}
-	return fmt.Errorf("DirectAdmin TCP port %d not in LISTEN state — panel control surface unreachable", port)
+	return fmt.Errorf(
+		"DirectAdmin control-plane port %d not in LISTEN state — control-plane unreachable "+
+			"(note: this assertion validates the control plane only; full DirectAdmin port surface validated in PR26.4)",
+		port)
 }
 
 // readConfiguredPort returns the configured control port from

internal/installer/panelfw/adapters/directadmin/directadmin_test.go

@@ -245,6 +245,42 @@ func TestValidateReachability_NotListening_ReturnsError(t *testing.T) {
 	}
 }
 
+// PR26.3 Path A: the user-facing error must explicitly identify the
+// scope as control-plane, not "panel survival" or "full panel". This
+// keeps operators from mistakenly believing the assertion has
+// validated the full DirectAdmin port surface.
+func TestValidateReachability_NotListening_ErrorMentionsControlPlane(t *testing.T) {
+	a := New()
+	mock := executor.NewMockExecutor()
+	mock.RunResults["ss:-lnt"] = executor.Result{ExitCode: 0, Stdout: ssOutput(80)}
+
+	err := a.ValidateReachability(context.Background(), mock)
+	if err == nil {
+		t.Fatalf("expected error when control port not listening")
+	}
+	msg := err.Error()
+	if !strings.Contains(msg, "control-plane") {
+		t.Errorf("error must explicitly say 'control-plane'; got %q", msg)
+	}
+	// Negative: the message must NOT make affirmative claims of full
+	// survival or full surface validation. We allow the explanatory
+	// negation form ("full DirectAdmin port surface validated in
+	// PR26.4") because it reads as scope clarification, not a claim
+	// the assertion has validated those ports.
+	for _, forbidden := range []string{
+		"full panel survival validated",
+		"full panel survived",
+		"all DirectAdmin ports validated",
+		"all DirectAdmin ports listening",
+		"all panel ports listening",
+		"all panel ports validated",
+	} {
+		if strings.Contains(msg, forbidden) {
+			t.Errorf("error must NOT claim %q (overstates scope); got %q", forbidden, msg)
+		}
+	}
+}
+
 // Defensive: ":22222" must not match expected ":2222".
 func TestValidateReachability_PortPrefixCollision(t *testing.T) {
 	a := New()
@@ -332,6 +368,46 @@ func TestFrameworkIntegration_DA_Detected_NotReachable_Blocks(t *testing.T) {
 	if !strings.Contains(res.Reason, "directadmin") {
 		t.Errorf("Reason should mention directadmin: %q", res.Reason)
 	}
+	// PR26.3 Path A: the surfaced Reason must say control-plane.
+	if !strings.Contains(res.Reason, "control-plane") {
+		t.Errorf("Reason must say 'control-plane'; got %q", res.Reason)
+	}
+}
+
+// PR26.3 Path A: the surfaced Reason on a failing DA host must NOT
+// claim that the full panel survival was checked — the assertion
+// covers only the control plane in PR26.3. Full port-surface
+// validation lands in PR26.4.
+func TestFrameworkIntegration_DA_Reason_DoesNotImplyFullPortSurvival(t *testing.T) {
+	a := New()
+	mock := executor.NewMockExecutor()
+	mock.Dirs[installDir] = true
+	mock.Files[binaryPath] = []byte("ELF")
+	mock.Services[systemdUnit] = true
+	mock.RunResults["ss:-lnt"] = executor.Result{ExitCode: 0, Stdout: ssOutput(80)}
+
+	res := panelfw.EvaluateAdapters(context.Background(), mock, newTestLogger(),
+		[]panelfw.PanelAdapter{a}, panelfw.DefaultPolicy())
+
+	if !res.Fatal {
+		t.Fatalf("expected Fatal=true; got %#v", res)
+	}
+	// These phrases would imply the assertion validated more than the
+	// control plane. The error MAY mention "full ... port surface" in
+	// a NEGATION (e.g., "...full DirectAdmin port surface validated in
+	// PR26.4"), so we look for affirmative-claim verbs instead.
+	for _, forbidden := range []string{
+		"full panel survival validated",
+		"full panel survived",
+		"all DirectAdmin ports validated",
+		"all DirectAdmin ports listening",
+		"all panel ports listening",
+		"all panel ports validated",
+	} {
+		if strings.Contains(res.Reason, forbidden) {
+			t.Errorf("Reason must NOT claim %q (overstates PR26.3 scope); got %q", forbidden, res.Reason)
+		}
+	}
 }
 
 func TestFrameworkIntegration_DA_Absent_Passes(t *testing.T) {