feat: bootstrap the meshStack CLI and move the API client in

[grubmeshi]

Stands up this repository and moves the meshStack API client into it from the Terraform provider, so
the provider and the CLI share one client instead of each carrying its own.

ClickUp: 86cb61rzz, milestone
86cb61we4.

Three commits, meant to be read in order:

1. feat: bootstrap the meshStack CLI repository — Taskfile, Go-only CI, Nix dev shell, and a
   cobra root command that prints help and nothing else yet.
2. feat: move the meshStack API client in and add pkg/login — client/ and the shared
   pkg/login.
3. feat: release with goreleaser and publish a container image — the release path.

Layout

Path	Holds
cmd/meshstack/	package main: main() and the root command. The only main package.
cmd/<subcommand>/	One package per subcommand. Package name is the subcommand, file name is the leaf command, so cmd/buildingblock/list.go will hold meshstack buildingblock list.
pkg/	Logic that needs no CLI process, and that the provider can import.
client/	The meshStack API client, on the path it had in the provider.

There is no main.go at the repository root, on purpose: the binary takes its name from its
directory, so go build ./cmd/meshstack and
go install github.com/meshcloud/meshstack-cli/cmd/meshstack@latest both produce meshstack with no
-o flag, while the module stays meshstack-cli. cmd/meshstack is the one directory under cmd/
that is not a subcommand.

Only the root command exists so far. The convention for the rest is written down in AGENTS.md rather
than demonstrated with a stub command that does nothing. cmd/meshstack wires children in explicitly
with AddCommand; nothing registers itself from init().

Dependency policy

One external dependency, cobra, and only cmd/ may use it. Everything else is standard library, with
testify in tests. depguard in .golangci.yml enforces that per directory — read those rules as the
policy. It matters because the provider imports client/ and pkg/login, so anything added here
lands in the provider's dependency tree and in the public checksum database.

cobra brings spf13/pflag and inconshreveable/mousetrap with it as indirect dependencies.

Each depguard rule was checked by compiling a file that violates it, because a rule matching no file
is a silent no-op. That is how a pattern bug surfaced: **/client/**/*.go matches files in
subdirectories of client/ only, never files directly inside it, so most of the client would have
been unguarded. Both patterns are now listed. The same bug was in the provider's config, where it left
51 client files and all 23 clientmock files unchecked — fixed separately and already on the
provider's main.

pkg/login resolves credentials; it does not run the login exchange

The exchange already exists in client/internal/auth.go, where it posts to /api/login, caches the
access token and refreshes it before expiry. Go's internal rule keeps that code inside client/, so
pkg/login reaches it through client.NewApiKeyAuthorization. A second, hand-rolled exchange would
have produced a static token that starts returning 401 once it expires.

credentials := login.FromEnv().Merge(explicitOverrides) // non-empty overrides win
endpoint, err := credentials.EndpointURL()
authorization, err := credentials.Authorization() // ApiToken outranks ApiKey/ApiSecret

Merge exists for the provider, which merges its provider block attributes over FromEnv so an
explicitly configured attribute outranks the environment.

The four MESHSTACK_ names are exported consts, not private ones. The provider's diagnostics
quote the variable names in their message text, so keeping them private would mean the same strings
living in both repositories.

Releasing

A v* tag publishes archives and checksums for linux, darwin and windows on amd64 and arm64, then
builds the container image for the same tag as a separate job. The image workflow is reusable, so a
push to main refreshes :main through the same path — without that, no usable image would exist
until the first release. Pull requests build the image without pushing it.

Everything published carries the repository name — archives, checksums and
ghcr.io/meshcloud/meshstack-cli — while the binary inside is meshstack, so
docker run ghcr.io/meshcloud/meshstack-cli buildingblock list reads like the local invocation.
No GPG signing: the provider signs because the Terraform registry demands it, which does not apply
here.

Known gap, for later

Authorization.Header takes a client/internal.HttpClient, so nothing outside client/ can call it,
and nothing can read the cached token back out. Caching a token in ~/.config/meshstack-cli will
need a new exported seam. pkg/login is the only place that constructs an Authorization, which is
where that seam belongs. The read side is already free: a cached token goes back in through
client.NewApiTokenAuthorization, the same path MESHSTACK_API_TOKEN uses.

Verification

• All 66 client files build here, and every moved test passes unmodified.
• pkg/login has 19 subtests across five table-driven tests. The precedence case was
  mutation-checked: it fails on an implementation that prefers key and secret over the token.
• golangci-lint: clean.
• goreleaser check passes; goreleaser release --snapshot produces meshstack-cli_*.tar.gz
  containing a meshstack binary that reports the injected version. The image builds and runs, at
  4.6 MB.
• The provider was rewritten onto this module locally, behind a temporary
  replace github.com/meshcloud/meshstack-cli => ../meshstack-cli, and its 83 unit tests pass with
  no failures. That is the gate from the feature plan: nothing was pushed here until the provider
  was green against it. Provider PR: feat!: consume the meshStack API client from meshstack-cli terraform-provider-meshstack#284.
• Acceptance tests against a live backend have not been run.

Still open

• The MPL-2.0 LICENSE, matching the license the client code already carries. collie-cli is
  Apache-2.0, so this is a deliberate pick rather than the house default.

🤖 Generated with Claude Code

[grubmeshi]

Redone with git subtree instead of a copy, and force pushed.

git subtree split --prefix=client on the provider's current main, then git subtree add here. The client arrives with 197 commits of its own history, back to refactor: move client to separate package, so authorship and per-change granularity survive the move, and future changes travel with git subtree pull / git subtree push.

Commits

feat: bootstrap the meshStack CLI repository	unchanged
Add client/ from terraform-provider-meshstack via git subtree	the import merge, 197 commits
refactor: point the moved client at the meshstack-cli module path	the one local edit: 38 files
feat: add pkg/login, the shared credential resolution	split out of the old commit 2
feat: release with goreleaser and publish a container image	unchanged
docs: record that client/ is a git subtree and how to sync it	new

Still a clean fast-forward from main (8f6cc2f), so your direct-push plan is unaffected.

Validation

You asked me to prove that before and after differ only by client changes made in the provider meanwhile. Rather than eyeball a diff, I checked both ends by extracting all four trees and normalising the module path:

• My earlier copy == provider client/ at 8dbef43, the commit I had snapshotted. Identical, so the old copy was faithful.
• The subtree result == provider client/ at current main. Identical, so the import is faithful.

The observed before/after change set then matches the provider's own 8dbef43..main change set exactly:

Files client/client.go and client/client.go differ
Files client/landingzone.go and client/landingzone.go differ
Only in client: client_test.go
Only in client: mesh_info.go

Whole-tree diff confirms nothing else moved:

 client/client.go      | 34 +++++++++++++-------------
 client/client_test.go | 44 ++++++++++++++++++++++++++++++
 client/landingzone.go | 12 ++++++----
 client/mesh_info.go   | 51 +++++++++++++++++++++++++++++++++++++
 go.mod                |  4 ++--
 go.sum                |  9 ++++-----

So my copy was stale by seven provider commits — the MESHSTACK_SKIP_VERSION_CHECK fix, the landing zone spec.restricted work, and the new meshStack instance data source with mesh_info.go. Those are now in. The go.mod delta is only testify 1.12.0 → 1.12.1 and testify's own transitive yaml module rename; the new client files import stdlib, client/internal and testify in tests, so the stdlib-only depguard rule still holds.

Two things worth knowing

The import merge does not compile on its own. git subtree add brings files verbatim, so at that commit they still import terraform-provider-meshstack/client; the next commit fixes it. Adapting inside the merge would have meant rewriting the content of all 197 commits, which is what avoiding a copy was meant to prevent. CI runs on the branch head, so this is not visible there.

History browsing needs both paths. The split history carries files at the repository root and the merge re-roots them under client/, so git log -- client/client.go stops at the merge while git log -- client/client.go client.go shows all 58. git blame client/client.go traverses it correctly on its own. git log --follow does not help — it resolves renames within a commit's parents, not across a subtree re-rooting. I had claimed --follow worked in the first draft of the merge message; it does not, and the message now documents the forms that do. All of this is recorded in AGENTS.md.

Re-verified after the rebuild: lint clean, all tests pass, goreleaser check passes, and a snapshot cross-compiles all five targets with the version ldflag intact.

[grubmeshi]

CI is green. The lint failure after the subtree import took three attempts to diagnose, and the first two explanations were wrong — worth writing down because the cause is not obvious and the same trap sits in the provider's workflow.

Symptom. client/internal/retry_test.go:46: File is not properly formatted, on a file no local run objects to.

What it was not. Not only-new-issues mapping a whole-directory patch (fails identically without it). Not the Go toolchain on PATH (fails identically with CI on go1.26.5, same as local).

What it is. golangci-lint's formatters use the go/format compiled into the linter binary, so the gofmt they enforce comes from the Go release that built the linter, not from the toolchain on PATH. version: latest with the default binary install fetched a 2.13.0 built with Go 1.27, while go.mod pins 1.26. Go 1.27 widens end-of-line comment alignment groups, so it wants that test table's comments at a much wider column.

The two are mutually exclusive — Go 1.26 rejects Go 1.27's formatting and vice versa — so reformatting the file was not an option in either direction.

Controlled comparison, same config and file, pristine checkout, empty cache:

linter	built with	result
2.13.0 from source	Go 1.26.5	clean
2.13.0 official binary	Go 1.27.0	reports the finding
2.12.2 system	Go 1.26.3	clean

Fix. CI builds the linter from source with go.mod's Go (install-mode: goinstall) and pins v2.13.0. Formatting is then decided by the Go the code is written against, and a linter bump becomes a deliberate edit. setup-go reads go.mod for the same reason — it is what builds the linter. Recorded in AGENTS.md so nobody switches back to the faster binary install without knowing what it costs.

only-new-issues is also gone, and stays gone: this repository starts clean, so filtering to changed code cannot help and can only hide a finding. It hid this one.

Worth a separate look: the provider's lint job has the same version: latest + go-version: stable + only-new-issues: true combination, so the same drift is latent there — currently invisible because the flag filters against pushes that do not touch the file. It will surface the first time someone edits a file with wide aligned comments. Happy to open a small PR for it if you want.

[nroi]

d: for gofmt, I'd suggest configuring a hook or something that ensures claude always runs that tool after editing a file. That's a deterministic mechanism that's far more reliable than an instruction in the AGENTS.md.

We have something similar in place in meshfed-release for ktlint.

[nroi]

d: I think the convention we want to rely on is that a developer at meshcloud has the repositories checked out in the same structure as they exist within the meshcloud github org, so meshfed-release would be a sibling directory of meshstack-cli., So, you'd have to refer to it as:

Suggested change

	`grill-me` skill in `meshfed-release/.agents/skills/`.)
	`grill-me` skill in `../meshfed-release/.agents/skills/`.)

[grubmeshi]

yes, correct. that was missed here! fix it also at other places if necessary.

[nroi]

d: that's a lot of details about technical plumbing and such, I wonder if this should be shortened. Shouldn't claude opus be sufficiently smart to figure out such details on its own? Just my impression, feel free to disregard if you consider those details useful.

[grubmeshi]

yes, true. let's shorten it. also investigate tf repo provider instructions if they can be optimized.