Repo scaffold + ref handling (credstore §2.1, PR0–1)

[rianjs]

Tracks Jira INT-429 (child of epic INT-310 — Get Claude desktop working for people).

First discrete unit of the cli-common shared credential library (per working-with-secrets.md §2.1).

Scope

• Repo scaffold: go.mod (github.com/open-cli-collective/cli-common, go 1.24), LICENSE, README linking back to the Working with Secrets standard, .gitignore
• CI matrix (macOS + Linux + Windows): build / test / lint
• Branch protection per CLI_CONVENTIONS.md (PR + 1 approval, required checks, linear history, squash-only)
• Ref handling (pure, no OS deps): ParseRef / FormatRef / EscapeRefSegment per §1.3 — enforce [A-Za-z0-9_-], reject / inside segments, typed errors
• Fuzz / property tests for ref round-tripping

Out of scope (later units under INT-310)

Backends, Store/Open, SetBundle atomicity, redaction helpers, migration helpers.

[rianjs]

INT-429 — cli-common: repo scaffold + ref handling (credstore §2.1, PR0–1)

Epic: INT-310 (Get Claude desktop working for people). GitHub: #1.
Standard: the Open CLI Collective Secret-Handling Standard (working-with-secrets.md), §2.1 deliverables; ref rules in §1.3.

Goal

Stand up the cli-common repo and ship the first substantive, OS-independent layer of
credstore: the credential-ref grammar (<service>/<profile>). Everything OS-touching
(backends, Store/Open, SetBundle, redaction, migration helpers) is explicitly out
of scope — separate later tickets under INT-310.

This is one PR off feat/INT-429-scaffold-ref-handling. main already has a bootstrap
commit (LICENSE/README/.gitignore) because you cannot PR into an empty repo.

Scope A — Scaffold (was PR0)

1. go.mod: module github.com/open-cli-collective/cli-common, go 1.24 (locked floor;
   nrq/slck Go bump is a later, separate concern).
2. Layout: single module, package credstore in credstore/. Import path
   github.com/open-cli-collective/cli-common/credstore.
3. README.md: purpose + scope; references the Secret-Handling Standard by name and the
   §-numbers this package implements. No hyperlink — the standard is maintained
   outside this repo and is not published; a vendored copy would drift. (Open question for
   architect: acceptable, or vendor a snapshot under docs/?)
4. .github/workflows/ci.yml mirroring sibling atlassian-cli conventions, simplified for
   a single module:
   • on: { push: { branches: [main] }, pull_request: {} }
   • build-test job, strategy.matrix.os: [ubuntu-latest, macos-latest, windows-latest]:
     actions/checkout@v4, actions/setup-go@v5 go-version: '1.24',
     go mod tidy && git diff --exit-code go.mod go.sum, go build -v ./...,
     go test -v -race -coverprofile=coverage.out ./....
   • lint job (ubuntu): golangci/golangci-lint-action@v7 version: v2.0.2.
5. .golangci.yml: copy of atlassian-cli/shared/.golangci.yml (version 2; errcheck,
   govet, ineffassign, staticcheck, unused, misspell, revive, gosec, errorlint,
   exhaustive; _test.go errcheck exclusion; gofmt+goimports with
   local-prefixes: github.com/open-cli-collective/cli-common; run.timeout: 5m).
6. Makefile: .PHONY check: tidy lint test, plus tidy, lint, test
   (go test -race ./...), build (go build ./...). Mirrors sibling gate, minus the
   per-binary targets (this is a library).
7. Branch protection on main via gh api, matching the atlassian-cli sibling:
   • required_status_checks.strict=true, contexts =
     build-test (ubuntu-latest), build-test (macos-latest),
     build-test (windows-latest), lint.
   • required_pull_request_reviews.required_approving_review_count=1.
   • required_linear_history=true, allow_force_pushes=false,
     allow_deletions=false, enforce_admins=false.
   • No signed-commit requirement — none configured locally/globally and the
     atlassian-cli sibling does not enforce it either; matching reality per the
     standard's "match reality" ethos.
   • Repo merge settings: allow_squash_merge=true, allow_merge_commit=false,
     allow_rebase_merge=false, delete_branch_on_merge=true.

Scope B — Ref handling (was PR1), per §1.3

Files: credstore/ref.go, credstore/ref_test.go.

Grammar: a ref is exactly <service>/<profile> — two segments, single / separator.
Allowed within a segment: [A-Za-z0-9_-], at least one char. / is structural and
forbidden inside a segment. The <key> and the <profile>/<key> → Item.Key mapping
are not part of ref parsing (they belong to Store ops, a later ticket).

API:

type RefErrorKind int
const (
    RefErrorEmpty        RefErrorKind = iota // empty ref or empty segment
    RefErrorSegmentCount                     // not exactly service/profile
    RefErrorInvalidChar                      // byte outside [A-Za-z0-9_-]
)

type RefError struct {
    Kind    RefErrorKind
    Segment string // "service" | "profile" | "" when not segment-specific
    Ref     string // offending input — refs are non-secret (§1.2), safe to echo
}
func (e *RefError) Error() string
func (e *RefError) Is(target error) bool // matches by Kind for errors.Is

var (
    ErrRefEmpty        = &RefError{Kind: RefErrorEmpty}
    ErrRefSegmentCount = &RefError{Kind: RefErrorSegmentCount}
    ErrRefInvalidChar  = &RefError{Kind: RefErrorInvalidChar}
)

func ParseRef(ref string) (service, profile string, err error)
func FormatRef(service, profile string) (string, error)
func EscapeRefSegment(raw string) string

Behavior:

• ParseRef: split on /. ≠2 parts → RefErrorSegmentCount. Any empty part →
  RefErrorEmpty. Any byte outside the set → RefErrorInvalidChar (with Segment set).
  Errors carry the offending ref string (refs are non-secret per §1.2 — no leak concern).
• FormatRef: validate both segments (non-empty, charset); on success return
  service + "/" + profile; else a *RefError.
• EscapeRefSegment: deterministic, reversible-by-construction encoding of an arbitrary
  string into the segment charset, for CLIs deriving a profile from a richer identifier
  (e.g. an email — §1.3). Scheme: [A-Za-z0-9-] pass through; _ is the escape char so
  literal _ → __; every other byte → _x + two lowercase hex digits (per UTF-8 byte).
  Example: rian@monitapp.io → rian_x40monitapp_x2eio. Output is always within
  [A-Za-z0-9_-]. Only Escape is implemented — no Unescape until a consumer needs
  it (avoid speculative API); the scheme is designed reversible so it can be added later.

Tests (ref_test.go):

• Table-driven ParseRef / FormatRef: valid s/p; empty ""; /p; s/; s/p/k;
  sp (no slash); invalid chars (space, ., @, unicode); - and _ accepted.
  Assert error Kind via errors.Is against the sentinels.
• EscapeRefSegment: emails, spaces, slashes, unicode, already-safe input, _ doubling;
  assert every output matches ^[A-Za-z0-9_-]+$ and a hand-checked example.
• Round-trip: for valid (s,p), ParseRef(FormatRef(s,p)) == (s,p).
• FuzzParseRef: for any input, either an error, or a successful parse whose segments
  contain no / and only charset bytes and that FormatRef-reproduces the input.

Verification

• go build ./... exits 0.
• go test -race ./... exits 0 (table + round-trip + fuzz seed corpus).
• go vet ./... clean; golangci-lint run clean.
• go mod tidy produces no diff.
• gh api .../branches/main/protection reflects the rules above.
• CI green on all three OS legs + lint; PR merges via squash; INT-429 → Done, Repo scaffold + ref handling (credstore §2.1, PR0–1) #1 closed.

Out of scope (later INT-310 tickets)

Backends (Keychain/wincred/Secret Service/file), Store/Open/Close/Backend,
single-key + bundle ops, SetBundle atomicity, Linux fail-closed classification,
redaction helpers, migration helpers, v0.1.0 tag. nrq/slck Go-1.24 bump.