test(compat): add STUBCLI_NEEDS_TOKEN stub hook + token-style SkipDataPath self-test

The merged `Runner.SkipDataPath` self-test
(`TestRunContract_SkipDataPath_GatesDataSubtests`) is adversarial in
the broadest possible way: `STUBCLI_FORMATS=__never__` makes the stub
reject every `--format` value at parse time. That proves the
`SkipDataPath` guard is load-bearing, but against a failure mode
(parse-rejection) that no real exporter actually exhibits.

`STUBCLI_NEEDS_TOKEN=1` adds the tighter adversarial model called out
in DT's review of #14: parse succeeds, the data call fails non-zero
with `error: not logged in` on stderr. That is the shape real
credentialed exporters (crono / liftoff / withings) hit in CI when no
secrets are provisioned — the exact scenario `SkipDataPath` exists to
escape.

The new self-test (`TestRunContract_SkipDataPath_WithNotLoggedIn`)
runs the full formats bundle with `STUBCLI_NEEDS_TOKEN=1` and
`SkipDataPath: true`. Parse-level subtests pass because they assert
on the rejection side of unknown flags, which never reach the token
check. Data-path subtests skip via the guard.

Neutering the `SkipDataPath` guards in jsonIsArray / csvHasHeader /
defaultIsMarkdown makes the test fail with
`--format <codec> exited 1; stderr="error: not logged in\n"` — a
distinct failure shape from the `__never__` variant's
`invalid value for --format`. The two adversarial models therefore
cover different regressions of the same guard.

No contract or `Runner` surface changes. SkipDataPath shipped in #14
and is settled.

Refs:
- Closed PR #15 — origin of STUBCLI_NEEDS_TOKEN
- Merged PR #14 — Runner.SkipDataPath
- QUA-34

Co-Authored-By: Paperclip <[email protected]>

Author: LeadGoEngineer

compat/formats/formats_test.go

@@ -94,6 +94,36 @@ func TestRunContract_SkipDataPath_GatesDataSubtests(t *testing.T) {
 	formats.RunContract(t, r)
 }
 
+// TestRunContract_SkipDataPath_WithNotLoggedIn is the token-style
+// adversarial complement to TestRunContract_SkipDataPath_GatesDataSubtests.
+//
+// The __never__ variant proves the SkipDataPath guard is load-bearing
+// against a stub that rejects every --format value at parse time. This
+// variant proves it is load-bearing against the failure mode real
+// credentialed exporters (crono / liftoff / withings) actually hit in
+// CI: --format parses cleanly, but the data call fails non-zero with
+// a "not logged in"-style error because no token is available.
+//
+// STUBCLI_NEEDS_TOKEN=1 produces exactly that shape. Parse-level
+// subtests still pass (--help has no token check; --format
+// obviously-not-a-format is rejected at parse, before the token
+// check). Data-path subtests skip via SkipDataPath.
+//
+// Delete the SkipDataPath guard in jsonIsArray / csvHasHeader /
+// defaultIsMarkdown and this test fails with `--format <codec> exited
+// 1; stderr=…not logged in…` — a distinct failure shape from the
+// __never__ variant's `…invalid value for --format…`, so the two
+// adversarial models cover different regressions of the same guard.
+func TestRunContract_SkipDataPath_WithNotLoggedIn(t *testing.T) {
+	bin := buildStub(t)
+	r := compat.Runner{
+		Binary:       bin,
+		Env:          []string{"STUBCLI_NEEDS_TOKEN=1"},
+		SkipDataPath: true,
+	}
+	formats.RunContract(t, r)
+}
+
 // TestSupportsFormat documents the nil-vs-empty-vs-subset behavior
 // of compat.Runner.SupportsFormat at the package level. The formats
 // bundle's skip guards rely on these semantics being stable.

compat/internal/stubcli/main.go

@@ -39,6 +39,19 @@
 // rather than running it against a stub that would reject the call.
 // When unset, all three §4 codecs are accepted.
 //
+// STUBCLI_NEEDS_TOKEN=1, when set, makes the stub simulate a
+// credentialless-CI failure: `--help` and `--format <unknown>` still
+// behave normally (the hook does not fire during parse), but a
+// successful parse of `--format <known codec>` does NOT emit data —
+// instead the stub exits non-zero with `error: not logged in` on
+// stderr and an empty stdout. This is the failure mode real
+// credentialed exporters (crono / liftoff / withings) hit in CI:
+// flag parsing succeeds, the data call fails because no token is
+// available. The compat/formats self-test uses this to prove that
+// Runner.SkipDataPath is load-bearing against the token-style
+// adversarial model — not just the broader STUBCLI_FORMATS=__never__
+// reject-everything model.
+//
 // stubcli never makes a network request.
 package main
 
@@ -160,6 +173,19 @@ func parseAndEmit(progName string, args []string) {
 		os.Exit(2)
 	}
 
+	// STUBCLI_NEEDS_TOKEN=1 simulates a credentialless-CI failure:
+	// flags parsed cleanly, but the data call fails because no token
+	// is available. Mirrors the shape real credentialed exporters
+	// (crono / liftoff / withings) hit when run from a CI environment
+	// without secrets. Exit code 1 (data-call failure) is distinct
+	// from the 2 used for parse failures above, so a test that
+	// expected a parse-rejection but accidentally took the data path
+	// sees a different shape.
+	if os.Getenv("STUBCLI_NEEDS_TOKEN") == "1" {
+		fmt.Fprintln(os.Stderr, "error: not logged in")
+		os.Exit(1)
+	}
+
 	// The stub has no upstream, so it always reports the empty data
 	// set. Per CONTRACT §4: `[]` for json, header-only for csv,
 	// nothing for markdown.