feat(compat): add Subcommands affordance to Runner for cobra-based CLIs

The original Runner shape assumed --since/--until lived on the root
binary. crono is cobra-based — date flags live on `biometrics`,
`exercises`, `nutrition`, `servings`, `notes` — so the dates suite
red-x'd HelpDocumentsDateFlags against it. Liftoff and Withings will
hit the same pattern.

Changes:

  - Runner gains a Subcommands []string field declaring the subcommands
    under which the contract surface lives, plus a WithSubcommand(name)
    composition helper that prepends the subcommand to argv on Run.
  - dates.RunContract dispatches per-subcommand when Subcommands is
    non-empty, scoping each pass under `subcommand=NAME/...` so any
    single-subcommand regression surfaces as a named failure rather
    than masking the rest. Flat CLIs leave Subcommands empty and the
    bundle runs against the root binary unchanged.
  - stubcli grows a second mode (STUBCLI_MODE=cobra) that mirrors a
    cobra-based CLI: root --help lists subcommands without mentioning
    the date flags, and only `biometrics` carries --since/--until. The
    cobra-mode self-test fails fast if the Runner ever stops prepending
    the subcommand.
  - New compat/internal/argecho helper and compat_test.go give the
    WithSubcommand prepend a focused unit test against a binary that
    just echoes os.Args.
  - README + CONTRIBUTING document the affordance and the cobra-style
    integration shape.

Addresses LeadGoEngineer review on PR #6 — the "first machine-attested
contract test" should not ship with a known gap that prevents its only
consumer from going green.

Refs CONTRACT.md §3.

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

Author: LeadGoEngineer

CONTRIBUTING.md

@@ -76,6 +76,7 @@ Rules:
 - Anyone changing `CONTRACT.md` is also expected to update or add tests under `compat/` that exercise the new behavior against every `*-export-cli`.
 - The harness is deliberately black-box: it shells out to the binary and asserts on stdout, stderr, and exit code only. It must not import a CLI's internal packages.
 - One subpackage per contract section (`compat/dates`, future `compat/formats`, `compat/auth`, `compat/prime`). Each exposes a single entry point — `RunContract(t, runner)` — that exporters call from one build-tagged `_test.go` file.
+- Cobra-based exporters whose contract surface lives on subcommands set `compat.Runner.Subcommands`; section bundles dispatch per-subcommand under a `subcommand=NAME/...` subtree. Flat CLIs leave the field empty and the bundle runs against the root binary.
 - A PR that changes the contract without touching `compat/` is incomplete. Either update the tests in the same PR or open a follow-up issue and link it from the PR body before merging — the Lead Go Engineer holds the line on this.
 - Compat tests run in CI on every PR and on `main`. A failing compat test on `main` means at least one shipped CLI no longer matches the contract, and that's a release-blocker incident, not a flake.
 - The Status table in `CONTRACT.md` distinguishes **machine-attested** rows (covered by `compat/`) from **human-attested** rows (still verified by reviewer judgment). Promoting a row from human to machine attestation is itself a worthwhile PR.

compat/README.md

@@ -37,7 +37,28 @@ func TestContractDates(t *testing.T) {
 }
 ```
 
-Then in your CI workflow:
+### Cobra-based CLIs: date flags on subcommands
+
+When `--since`/`--until` live on subcommands (the crono / liftoff / withings pattern), set `Subcommands` and the suite will dispatch per-subcommand:
+
+```go
+func TestContractDates(t *testing.T) {
+    bin := os.Getenv("EXPORT_CLI_BIN")
+    if bin == "" {
+        t.Skip("EXPORT_CLI_BIN not set; skipping compat suite")
+    }
+    dates.RunContract(t, compat.Runner{
+        Binary: bin,
+        Subcommands: []string{
+            "biometrics", "exercises", "nutrition", "servings", "notes",
+        },
+    })
+}
+```
+
+Each subcommand is verified under a `subcommand=NAME/...` subtree, so a regression in any single one fails as a named subtest instead of masking the rest.
+
+### CI workflow
 
 ```yaml
 - name: build
@@ -59,6 +80,8 @@ The exporter does not need a separate `go.mod` for compat tests — the standard
 | `HelpIsHermetic` | §5 | `--help` succeeds with all HTTP proxies pointed at an unreachable address. |
 | `FlagValidationIsHermetic` | §5 | A parse failure also produces no successful outbound request. |
 
+When `compat.Runner.Subcommands` is set, every row above runs once per declared subcommand under `subcommand=NAME/...`.
+
 ## What it does NOT cover yet
 
 The actual local-midnight semantics of `--since 2026-04-15` (the harmonization that just landed across crono/liftoff/withings) is still **human-attested** in the status table. Asserting it black-box requires either:
@@ -78,3 +101,5 @@ When that affordance lands, the test belongs here as `dates.LocalMidnightSemanti
 ## Self-test
 
 This module has its own test that runs the suite against a stub CLI in `internal/stubcli/`. The stub is intentionally narrow — it exists so `go test ./...` from this module's root proves the library compiles and the assertions fire correctly, without depending on any of the real export-CLIs. Failures in the self-test mean the library has a bug; failures in an exporter's compat test mean the exporter drifted from the contract.
+
+The stub has two modes (`STUBCLI_MODE=flat` and `STUBCLI_MODE=cobra`). The flat-mode self-test exercises the original Runner shape; the cobra-mode self-test exercises `Subcommands`-based dispatch. In cobra mode, the stub's root `--help` deliberately omits `--since/--until`, so the cobra-mode self-test fails fast if `compat.Runner` ever stops prepending the subcommand. There is also a focused unit test for `Runner.WithSubcommand` using an `argecho` helper that just prints `os.Args`.

compat/compat.go

@@ -36,6 +36,29 @@ type Runner struct {
 
 	// Timeout is the per-invocation timeout. Zero means 10 seconds.
 	Timeout time.Duration
+
+	// Subcommands declares the subcommands under which the contract
+	// surface lives — for CLIs (typically cobra-based) where flags like
+	// --since and --until are attached to data-producing subcommands
+	// rather than the root binary. Examples: crono's `biometrics`,
+	// `exercises`, `nutrition`, `servings`, `notes` each accept their
+	// own --since/--until.
+	//
+	// Empty means the surface is on the root binary; section bundles
+	// invoke the binary directly. Non-empty means each section's
+	// RunContract iterates the list and verifies the contract once per
+	// subcommand via t.Run, so a regression in any single subcommand
+	// surfaces as a named subtest failure rather than masking the rest.
+	//
+	// The Runner itself does not look at this field; section bundles
+	// (e.g. compat/dates) read it and dispatch via WithSubcommand.
+	Subcommands []string
+
+	// subcommand, when non-empty, is prepended to args on every Run
+	// call. Set via WithSubcommand; section bundles use it to dispatch
+	// per-subcommand. Callers do not need to set it directly — set
+	// Subcommands instead and let the bundle compose the dispatch.
+	subcommand string
 }
 
 // Result captures everything observable about one CLI invocation. All
@@ -68,7 +91,11 @@ func (r Runner) Run(ctx context.Context, args ...string) (Result, error) {
 	runCtx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
-	cmd := exec.CommandContext(runCtx, r.Binary, args...)
+	fullArgs := args
+	if r.subcommand != "" {
+		fullArgs = append([]string{r.subcommand}, args...)
+	}
+	cmd := exec.CommandContext(runCtx, r.Binary, fullArgs...)
 	// Default to an empty env so tests are hermetic. Callers opt into
 	// passing TZ, HOME, etc. via Runner.Env.
 	if r.Env != nil {
@@ -118,3 +145,22 @@ func (r Runner) WithEnv(kv ...string) Runner {
 	out.Env = append(append([]string(nil), r.Env...), kv...)
 	return out
 }
+
+// WithSubcommand returns a copy of r whose Run prepends sub as the
+// first command-line argument. Section bundles use this internally to
+// dispatch per-subcommand when Runner.Subcommands is non-empty;
+// integrators normally set Subcommands and let the bundle do it.
+//
+// Calling WithSubcommand again replaces (not stacks) the previous
+// value; nested subcommand paths are out of scope for the current
+// contract.
+func (r Runner) WithSubcommand(sub string) Runner {
+	out := r
+	out.subcommand = sub
+	return out
+}
+
+// Subcommand returns the subcommand that Run will prepend to args, or
+// the empty string if none is set. Section bundles use this in subtest
+// names so failures point at the offending subcommand.
+func (r Runner) Subcommand() string { return r.subcommand }

compat/compat_test.go

@@ -0,0 +1,98 @@
+package compat_test
+
+import (
+	"context"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/quantcli/common/compat"
+)
+
+// TestWithSubcommand_PrependsArg checks that WithSubcommand causes Run
+// to emit the subcommand as argv[1] in front of the caller's args.
+// We use a small Go program that echoes its os.Args back so the assertion
+// is independent of any system command's flag semantics.
+func TestWithSubcommand_PrependsArg(t *testing.T) {
+	bin := buildArgEcho(t)
+	r := compat.Runner{Binary: bin}.WithSubcommand("biometrics")
+
+	res, err := r.Run(context.Background(), "--help")
+	if err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	if res.ExitCode != 0 {
+		t.Fatalf("exit %d; stderr=%q", res.ExitCode, res.StderrString())
+	}
+	got := strings.TrimRight(res.StdoutString(), "\n")
+	want := "biometrics\n--help"
+	if got != want {
+		t.Errorf("argv mismatch:\n got:\n%s\nwant:\n%s", got, want)
+	}
+}
+
+// TestRun_NoSubcommandPassthrough checks that the default zero
+// subcommand leaves args untouched.
+func TestRun_NoSubcommandPassthrough(t *testing.T) {
+	bin := buildArgEcho(t)
+	r := compat.Runner{Binary: bin}
+
+	res, err := r.Run(context.Background(), "--help")
+	if err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	got := strings.TrimRight(res.StdoutString(), "\n")
+	if got != "--help" {
+		t.Errorf("argv mismatch: got %q want %q", got, "--help")
+	}
+}
+
+// TestWithSubcommand_DoesNotMutateReceiver asserts that WithSubcommand
+// returns a copy and leaves the parent runner unchanged. Section
+// bundles rely on this when iterating Subcommands.
+func TestWithSubcommand_DoesNotMutateReceiver(t *testing.T) {
+	bin := buildArgEcho(t)
+	parent := compat.Runner{Binary: bin}
+	_ = parent.WithSubcommand("biometrics")
+	if parent.Subcommand() != "" {
+		t.Errorf("parent.Subcommand() = %q; want empty after WithSubcommand on copy", parent.Subcommand())
+	}
+}
+
+// TestRun_TimeoutReturnsError exercises the timeout branch so the
+// Runner's error contract (non-zero exit is not an error; timeout is)
+// stays load-bearing.
+func TestRun_TimeoutReturnsError(t *testing.T) {
+	sleeper, err := exec.LookPath("sleep")
+	if err != nil {
+		t.Skip("sleep not on PATH; skipping timeout exercise")
+	}
+	r := compat.Runner{Binary: sleeper, Timeout: 50 * time.Millisecond}
+	_, runErr := r.Run(context.Background(), "5")
+	if runErr == nil {
+		t.Fatal("expected timeout error, got nil")
+	}
+	if !strings.Contains(runErr.Error(), "timed out") {
+		t.Errorf("expected timeout error, got: %v", runErr)
+	}
+}
+
+// buildArgEcho compiles the tiny argecho helper into a temp dir. It is
+// the simplest possible echo-args binary: it prints each os.Args[1:]
+// entry on its own line to stdout. We build it instead of relying on
+// /bin/echo so the test works on any GOOS.
+func buildArgEcho(t *testing.T) string {
+	t.Helper()
+	out := filepath.Join(t.TempDir(), "argecho")
+	if runtime.GOOS == "windows" {
+		out += ".exe"
+	}
+	cmd := exec.Command("go", "build", "-o", out, "github.com/quantcli/common/compat/internal/argecho")
+	if output, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("go build argecho: %v\n%s", err, output)
+	}
+	return out
+}

compat/dates/dates.go

@@ -3,7 +3,10 @@
 //
 // What is machine-attested here:
 //
-//   - The CLI documents `--since` and `--until` in its top-level help.
+//   - The CLI documents `--since` and `--until` in the help output of
+//     whatever entry point owns them — the root binary for flat CLIs,
+//     or each declared subcommand for cobra-based CLIs (set via
+//     compat.Runner.Subcommands).
 //   - An invalid `--since` value produces a non-zero exit with an error
 //     on stderr and an empty stdout.
 //   - A flag-validation failure does not perform a network request.
@@ -52,12 +55,37 @@ import (
 // the others. The bundle is safe to run in parallel with other compat
 // suites; individual subtests are not marked parallel because they
 // shell out to the same binary and the OS may serialize them anyway.
+//
+// If r.Subcommands is non-empty, RunContract iterates the list and
+// runs the four assertions once per subcommand under a
+// "subcommand=NAME" t.Run group. This is how cobra-based CLIs (e.g.
+// crono's `biometrics`, `exercises`, `nutrition`, `servings`, `notes`)
+// attest the contract on every data-producing subcommand. If empty,
+// the assertions run once against the root binary — the right shape
+// for CLIs that put --since/--until at the top level.
 func RunContract(t *testing.T, r compat.Runner) {
 	t.Helper()
 	if r.Binary == "" {
 		t.Fatal("dates: compat.Runner.Binary is empty")
 	}
 
+	if len(r.Subcommands) == 0 {
+		runContractOne(t, r)
+		return
+	}
+	for _, sub := range r.Subcommands {
+		sub := sub
+		t.Run("subcommand="+sub, func(t *testing.T) {
+			runContractOne(t, r.WithSubcommand(sub))
+		})
+	}
+}
+
+// runContractOne runs the four date-flag assertions against a single
+// invocation surface — either the root binary (when r has no
+// subcommand prefix) or a specific subcommand of it.
+func runContractOne(t *testing.T, r compat.Runner) {
+	t.Helper()
 	t.Run("HelpDocumentsDateFlags", func(t *testing.T) {
 		helpDocumentsDateFlags(t, r)
 	})
@@ -73,9 +101,11 @@ func RunContract(t *testing.T, r compat.Runner) {
 }
 
 // helpDocumentsDateFlags asserts that the CLI documents `--since` and
-// `--until` somewhere in its top-level `--help` output. This is the
-// minimum binding between the contract and the binary: an exporter that
-// quietly drops one of the flags will fail this test.
+// `--until` somewhere in the `--help` output of the configured entry
+// point — root binary or subcommand, depending on how the integrator
+// configured compat.Runner. This is the minimum binding between the
+// contract and the binary: an exporter that quietly drops one of the
+// flags will fail this test.
 func helpDocumentsDateFlags(t *testing.T, r compat.Runner) {
 	t.Helper()
 	res := r.MustRun(t, "--help")
@@ -97,12 +127,11 @@ func helpDocumentsDateFlags(t *testing.T, r compat.Runner) {
 // invalidSinceValueFails asserts that a malformed `--since` value causes
 // the CLI to exit non-zero with an error on stderr and an empty stdout.
 //
-// The flag is passed to whatever subcommand the CLI puts first; we use a
-// known-bad value so any subcommand that accepts `--since` will reject
-// it at parse time. If a CLI accepts `--since` only on subcommands, the
-// integrator overrides this test by passing their own subcommand name
-// via a future SubcommandHint hook — for now the contract requires that
-// at least one entry point rejects malformed dates.
+// We use a known-bad value so any entry point that accepts `--since`
+// will reject it at parse time. For cobra-based CLIs whose date flags
+// live on subcommands, the integrator sets compat.Runner.Subcommands;
+// RunContract then dispatches via WithSubcommand and this assertion
+// runs once per declared subcommand.
 func invalidSinceValueFails(t *testing.T, r compat.Runner) {
 	t.Helper()
 	// "obviously-not-a-date" should never parse as a keyword, absolute

compat/dates/dates_test.go

@@ -10,15 +10,35 @@ import (
 	"github.com/quantcli/common/compat/dates"
 )
 
-// TestRunContract_AgainstStub builds the in-tree stub binary and runs
-// the compat suite against it. This is the library's own gate: if the
-// stub (which is contract-compliant by construction) starts failing
-// these tests, the library has a bug, not the stub.
-func TestRunContract_AgainstStub(t *testing.T) {
+// TestRunContract_AgainstStubFlat builds the in-tree stub binary in its
+// default (flat) mode and runs the compat suite against it. This is the
+// library's own gate for the original Runner shape: if the stub (which
+// is contract-compliant by construction) starts failing these tests,
+// the library has a bug, not the stub.
+func TestRunContract_AgainstStubFlat(t *testing.T) {
 	bin := buildStub(t)
 	dates.RunContract(t, compat.Runner{Binary: bin})
 }
 
+// TestRunContract_AgainstStubSubcommand runs the same suite against
+// the stub in cobra mode, with a Subcommands declaration so the Runner
+// dispatches per-subcommand. In cobra mode the stub's root --help does
+// NOT mention --since/--until — only `biometrics --help` does — so this
+// test fails fast if compat.Runner ever stops prepending the
+// subcommand.
+//
+// This is the gate that pins down the contract for crono / liftoff /
+// withings, whose date flags live on cobra subcommands.
+func TestRunContract_AgainstStubSubcommand(t *testing.T) {
+	bin := buildStub(t)
+	r := compat.Runner{
+		Binary:      bin,
+		Env:         []string{"STUBCLI_MODE=cobra"},
+		Subcommands: []string{"biometrics"},
+	}
+	dates.RunContract(t, r)
+}
+
 // buildStub compiles the stub CLI into a temp directory and returns the
 // absolute path. It uses `go build` rather than relying on a checked-in
 // binary so the test is reproducible across platforms.

compat/internal/argecho/main.go

@@ -0,0 +1,17 @@
+// Command argecho prints each of its os.Args[1:] entries on its own
+// line to stdout, then exits zero. It is used by compat_test.go to
+// verify how Runner constructs argv (notably the WithSubcommand
+// prepend behavior) without depending on any system command's flag
+// parsing.
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+func main() {
+	for _, a := range os.Args[1:] {
+		fmt.Println(a)
+	}
+}