cli-common state components: path/dir resolver + hermetic test helper + tier-1 cache core

[rianjs]

Build the shared cli-common state components — §6 step 1 ("commons-first") of docs/working-with-state.md. Foundational layer; no CLI port in this issue (ports are per-unit, later, each with its own §3.2 migration matrix).

Scope (§5)

(a) Path/dir resolver (§5a) — owns the genuinely-common policy, not a thin os.User*Dir()+Join wrapper:

• credential-scope config-dir naming rule (§3) + per-binary cache-dir rule (§4.1)
• create vs. no-create split (resolver must not mkdir on dry-run / config clear paths)
• a migration-source enumeration seam so each CLI's bespoke legacy probing plugs in without the resolver trying to be generic about legacy layouts
• does not ban a CLI from calling os.User*Dir() for its own legacy-probe paths

(a) 7-var hermetic test helper (§3.1) — overrides the full set: HOME, USERPROFILE, AppData, LocalAppData, XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME. Ships once here; no CLI re-derives the list. Load-bearing (HOME-only is a Windows real-dir leak).

(b) Tier-1 cache core (§5b) — directory-agnostic:

• Envelope[T]{Resource,Instance,FetchedAt,TTL,Version,Data} + ReadResource[T]/WriteResource[T]
• atomic temp-file-in-same-dir → chmod 0600 → rename; dir 0700
• version-mismatch-as-miss (schema bumps self-heal)
• freshness Classify/Age/Status (Fresh|Stale|Uninitialized|Manual|Unavailable; manual = never auto-expire)
• cache path from an injected Locator{Root, InstanceKey} — receives Root, never derives it

Tier 2 (registry/DAG/fetchers/refresh wiring) is explicitly deferred (§5b rule-of-three; post-cfl).

Out of scope

• Any CLI port / config relocation / §3.2 migration matrix (per-unit, later)
• Tier-2 cache layer
• Cutting the INT-310 semver tag (only after the consumer matrix is green — §5 guardrail)

Acceptance

• One PR, decomposed commits: (1) resolver, (2) hermetic helper, (3) tier-1 cache core
• make check green (tidy + lint + test); stdlib-only (no go.sum)
• Unit tests for resolver naming/create-split, hermetic helper env coverage, envelope round-trip / atomic-write / version-miss / freshness classification
• Codex architect convergence (blockers=0 majors=0)

Jira: MON-5364 (child of INT-310, Feature, 5pts, Sprint 71)

[rianjs]

MON-5364 — cli-common state components (commons buildout)

Jira: MON-5364 (child of INT-310, Feature, 5pts, Sprint 71) ·
GH: #17 ·
Branch: feature/MON-5364-cli-common-state-components

Implements §6 step 1 ("commons-first") of
cli-common/docs/working-with-state.md: build the shared state components so
the per-unit CLI ports (later, separate tickets) have something to adopt.
No CLI is touched in this PR. No §3.2 migration matrix here — that gate is
per-port and there is no consumer yet.

1. Goal & non-goals

In scope (§5):

• §5a path/dir resolver — owns the genuinely-common policy: credential-scope
  config-dir naming, per-binary cache-dir naming, the create-vs-no-create split.
• §5a 7-var hermetic test helper — ships once here; the highest leak-risk
  item (§3.1). Lives in its own package so production code never imports
  testing.
• §5b tier-1 cache core — directory-agnostic Envelope[T],
  Read/WriteResource[T], atomic temp-file-rename, version-mismatch-as-miss,
  freshness Classify/Age/Status, injected Locator{Root,InstanceKey}.

Explicitly out of scope (write the boundary down so Codex can challenge it):

• Any CLI port, config relocation, or §3.2 8-case migration matrix → per-unit,
  later tickets.
• A migration engine in commons. The doc (§5a) asks for a migration-
  source enumeration seam, not a generic legacy-layout resolver — it is
  emphatic the resolver "must not try to be generic about legacy layouts".
  Decision: the seam = (a) the no-create split (so a CLI can resolve a target
  without side effects before deciding to migrate) + (b) a documented
  LegacySource value type the CLI populates with its own probe paths; the
  resolver never enumerates or reads them. No copy/move/conflict logic in
  commons (that is §3.2 per-port, rule-of-three deferred). Flagged for Codex:
  is a bare type + no-create enough to call a "seam", or is a thin
  Migrate(target, []LegacySource, decodeFn) orchestration warranted now?
• Tier-2 cache (registry / dependency-DAG / fetchers / refresh wiring) — §5b
  rule-of-three, deferred to post-cfl.
• Cutting the INT-310 semver tag — only after the consumer matrix is green
  (§5 guardrail); this PR does not tag.
• Touching the stale "stdlib-only" README claim (credstore already added
  keyring deps + a go.sum); not traceable to this ticket.

Hard constraint: the new packages are pure stdlib (os,
path/filepath, encoding/json, time, regexp, errors, fmt, and
testing only in the test-helper package). No new require → go.mod/
go.sum untouched → the make check tidy gate stays green.

2. Proposed package layout (impl detail — Codex may revise)

Flat module, sibling to credstore/:

cli-common/
  statedir/            # the §5a resolver (no testing import)
    resolver.go
    resolver_test.go
  statedirtest/        # §3.1 7-var hermetic helper (imports testing)
    statedirtest.go
  cache/               # §5b tier-1 core (no testing import)
    envelope.go        # Envelope[T], Read/WriteResource[T], atomic write
    freshness.go       # Status, Classify, Age
    locator.go         # Locator{Root,InstanceKey}, path compose + safety
    *_test.go

Rationale: statedirtest is a separate leaf (mirrors gro's internal/credtest
pattern) so importing the resolver into production never drags in testing.
cache is conceptually independent of statedir (it receives Root via
Locator, never derives it — §5b "directory-agnostic"), so it is its own
package, not a sub-package. Codex decision point: statedir vs statepath
naming; one-package-with-files vs three packages.

3. Component specs

3a. statedir resolver

package statedir

// Scope is the config-dir naming key (§3 credential-scope rule).
type Scope struct {
    // Name is the credential scope, NOT necessarily the binary:
    //  - single-binary CLI      → the tool name ("slck", "nrq", "gro", "sfdc")
    //  - shared-credential repo  → the scope    ("atlassian-cli")
    Name string
}

func (s Scope) ConfigDir() (string, error)          // os.UserConfigDir()/Name, NO mkdir
func (s Scope) ConfigDirEnsured() (string, error)   // + MkdirAll 0700

// Cache is the per-binary cache-dir key (§4.1) — always the binary name,
// even inside a shared-credential repo (jtk and cfl never share a cache).
type Cache struct{ Tool string }

func (c Cache) CacheDir() (string, error)           // os.UserCacheDir()/Tool, NO mkdir
func (c Cache) CacheDirEnsured() (string, error)    // + MkdirAll 0700

// LegacySource is the migration seam (§5a). The resolver does NOT enumerate,
// read, or interpret these — the CLI supplies its own probe paths. Present so
// the *type* is shared/documented; the policy stays per-CLI.
type LegacySource struct {
    Label string // human label for the conflict/notice message
    Path  string // absolute path the CLI computed itself
}

• Name/Tool validated non-empty and free of path separators / . / ..
  (defense-in-depth: it composes a path). Invalid → typed error.
• ConfigDir/CacheDir never mkdir (dry-run / config clear --all /
  resolve-before-migrate must be side-effect free — gro learned this in B2b).
  *Ensured is the only mkdir path, mode 0700.
• Pure os.UserConfigDir() / os.UserCacheDir() + filepath.Join — no
  hand-rolled ~/.config, no %APPDATA% branch. Relative $XDG_* →
  propagate the stdlib error (the §1.1 "intentional tightening").

Verification: resolver_test.go (hermetic via statedirtest): Name
"atlassian-cli" → <UserConfigDir>/atlassian-cli; single-binary → tool name;
ConfigDir does not create the dir (stat shows absent), ConfigDirEnsured
creates it 0700; per-binary cache jtk≠cfl; empty/../separator Name → typed
error; all assertions pass under go test -race.

3b. statedirtest hermetic helper (§3.1, load-bearing)

package statedirtest

// Hermetic points the full 7-var env set at t.TempDir() and returns the root.
// HOME-only is a Windows real-dir leak (os.UserConfigDir reads %AppData%,
// os.UserCacheDir reads %LocalAppData% — neither derived from %USERPROFILE%).
func Hermetic(t *testing.T) string

Sets, via t.Setenv (auto-restored): HOME, USERPROFILE, AppData,
LocalAppData, XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME — the
exact §3.1/§7 list. Subdirs under the temp root so config/cache/data don't
collide. This is the single definition; no CLI re-derives the list (gro's
credtest is provably incomplete: no USERPROFILE/AppData/XDG_DATA_HOME).

Verification: statedirtest_test.go asserts all 7 vars point under the
returned temp dir, that os.UserConfigDir()/os.UserCacheDir() resolve under
it on the running OS, and that values are restored after the subtest. (Cross-OS
behavior documented; CI runs the matrix.)

3c. cache tier-1 core (§5b)

Lift jtk's envelope.go + freshness.go shapes, made directory-agnostic by
injecting the location instead of importing jtk config:

package cache

const Version = 1
var ErrCacheMiss = errors.New("cache miss")

type Locator struct {
    Root        string // supplied by statedir (cache.CacheDir); never derived here
    InstanceKey string // jtk: host/cloud-id; gro: constant; single: "default"
}

func (l Locator) resourceFile(name string) (string, error) // validates + joins

type Envelope[T any] struct {
    Resource  string    `json:"resource"`
    Instance  string    `json:"instance"`
    FetchedAt time.Time `json:"fetched_at"`
    TTL       string    `json:"ttl"`
    Version   int       `json:"version"`
    Data      T         `json:"data"`
}

func ReadResource[T any](loc Locator, name string) (Envelope[T], error)
func WriteResource[T any](loc Locator, name, ttl string, data T) error

type Status int // Uninitialized, Fresh, Stale, Manual, Unavailable
func Classify(fetchedAt time.Time, ttl string, now time.Time) Status
func Age(fetchedAt, now time.Time) string

• resourceFile: both InstanceKey and name validated with jtk's
  isSafeInstanceKey regex ^[A-Za-z0-9][A-Za-z0-9.\-]*$ + .. rejection
  brought into commons — the lib composes a filesystem path from both, so
  both are untrusted. Invalid → typed error, never compose.
• Read: missing file → ErrCacheMiss; JSON error → wrapped error;
  Version != Version → ErrCacheMiss (self-healing schema bump). Reads never
  check freshness.
• Write: temp file in same dir → write → Close → chmod 0600 → rename;
  dir MkdirAll 0700; temp removed on every failure branch. Resource,
  Instance(=loc.InstanceKey), Version, FetchedAt(UTC now) set by the
  lib; TTL from caller.
• Classify/Age: verbatim jtk semantics — "manual" sentinel →
  StatusManual (never auto-expire); FetchedAt.IsZero() or elapsed →
  StatusStale; Age "-"/Ns/Nm/Nh/Nd. StatusUnavailable is defined (parity
  with jtk's registry) but unused by tier-1 (no registry here — documented).

Verification: *_test.go (hermetic, table-driven, -race): envelope
round-trip read-after-write; missing → ErrCacheMiss; bumped Version →
ErrCacheMiss; malformed JSON → non-miss error; atomic write leaves no
*.tmp and a 0600 file under a 0700 dir; failed write removes temp;
InstanceKey/name of "", .., a/b, ../escape → typed error, no file
created; Classify all five states incl. manual + zero time; Age
boundaries (s/m/h/d, negative→0, zero→"-").

4. Step plan (decomposed commits — §6.2 reviewability)

One PR, three independently-reviewable commits, each green on its own:

1. feat(statedir): credential-scope path resolver + create/no-create split
   — statedir/ + statedirtest/ + their tests. Check: go test -race ./statedir/... ./statedirtest/... passes; golangci-lint run clean.
2. feat(cache): directory-agnostic tier-1 envelope + freshness core —
   cache/. Check: go test -race ./cache/... passes; lint clean.
3. docs: mark §6 step 1 (commons buildout) delivered in working-with-state
   — one status line in docs/working-with-state.md §6 noting the components
   exist (no semantic change to the standard). Check: link/markdown sanity;
   no relative-link regressions.

Then: make check (tidy + lint + go test -race ./...) green across the
whole module, including the existing credstore suite (no regression).

5. Risks / decision points for Codex

1. Migration seam minimalism (§1 boundary) — is LegacySource + no-create
   enough, or does §5a demand a Migrate(...) orchestrator now? Argument for
   minimal: no consumer, §3.2 is per-port, rule-of-three not met.
2. Package split — three packages vs one; statedir vs statepath.
3. StatusUnavailable with no registry — keep for jtk parity (smoother
   tier-2 lift) or drop until needed (YAGNI)? Leaning keep + documented.
4. Locator value vs interface — value struct (jtk-like, simple) chosen
   over an interface (no second shape yet → YAGNI).
5. Generics signature — top-level Read/WriteResource[T](loc, …) (Go has
   no generic methods) vs a non-generic Store holding Locator. Chose
   top-level funcs to match jtk and keep Locator a plain value.
6. No new dependency; go.mod/go.sum must be byte-identical post-build
   (the tidy gate asserts this).

[rianjs]

Codex architect plan review (session 019e4019, gpt-5.5 xhigh) — CONVERGED round 2: blockers=0 majors=0 minors=0 nits=1 (nit fixed: stale 'flagged for Codex' wording → resolved rationale).

Round 1 (blockers=0 majors=2 minors=2 nits=1), all accepted & fixed:

• M Locator.Root unchecked → zero-value writes relative to cwd → now validated non-empty+absolute, typed ErrInvalidRoot, cwd-untouched test.
• M Classify state-set overclaimed → clarified: Classify returns ONLY Fresh|Stale|Manual; Uninitialized is caller-derived (ErrCacheMiss), Unavailable registry-derived; String() parity tested separately for all 5.
• m *Ensured 0700 → documented it does NOT re-chmod a pre-existing wrong-mode dir (per-port boundary, §6.4).
• m statedirtest.Hermetic documented as not usable under t.Parallel (t.Setenv mutates process-global env).
• n strings added to the stdlib allowlist.

Codex confirmed: LegacySource+no-create is a sufficient §5a seam (no Migrate engine), 3-package split + statedir naming correct, no silent CLI port, no §3.2/tag/release-train preemption, stdlib-only keeps go.mod/go.sum byte-identical. Proceeding to implementation.