feat: add the meshStack CLI and the API client it shares with the Terraform provider

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path // empty' | { read -r f; [[ \"$f\" == *.go ]] && cd \"$CLAUDE_PROJECT_DIR\" && go tool golangci-lint fmt \"$f\"; } 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

.dockerignore

@@ -0,0 +1,11 @@
+# The build only needs the Go sources, go.mod and go.sum. Everything below would
+# otherwise be copied into the build context and invalidate its cache.
+.git/
+.github/
+dist/
+.nix-go/
+meshstack
+.env
+.vscode/
+.idea/
+*.md

.github/workflows/build-image.yml

@@ -0,0 +1,84 @@
+# Builds the meshstack container image and pushes it to GHCR only. Modelled on
+# meshcloud/building-block-runner's build-images.yml, minus the Docker Hub push.
+name: Build Image
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAMESPACE: ${{ github.repository_owner }}
+  IMAGE_NAME: meshstack-cli
+
+on:
+  # Called by the release workflow, so a tagged release publishes the matching image.
+  workflow_call:
+    inputs:
+      version:
+        description: "Release version to tag the image with, e.g. v1.2.3"
+        required: true
+        type: string
+  # A push to main refreshes :main, which is what makes the image usable before the
+  # first release exists.
+  push:
+    branches:
+      - main
+  # Pull requests build the image but do not push it, so a broken Dockerfile fails
+  # review rather than main.
+  pull_request:
+    paths:
+      - 'Dockerfile'
+      - '.github/workflows/build-image.yml'
+      - 'go.mod'
+      - 'go.sum'
+      - '**/*.go'
+
+jobs:
+  build:
+    name: Build and push image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      # Tags are computed here rather than with docker/metadata-action, to keep the
+      # set of pinned actions small.
+      - name: Determine version and tags
+        id: meta
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            version="${{ inputs.version }}"
+            tags="${REGISTRY}/${IMAGE_NAMESPACE}/${IMAGE_NAME}:${version}"
+            tags="${tags},${REGISTRY}/${IMAGE_NAMESPACE}/${IMAGE_NAME}:latest"
+          elif [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            version="main-$(git rev-parse --short HEAD)"
+            tags="${REGISTRY}/${IMAGE_NAMESPACE}/${IMAGE_NAME}:main"
+            tags="${tags},${REGISTRY}/${IMAGE_NAMESPACE}/${IMAGE_NAME}:${version}"
+          else
+            version="pr-${{ github.event.number }}"
+            tags="${REGISTRY}/${IMAGE_NAMESPACE}/${IMAGE_NAME}:${version}"
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "tags=${tags}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Login to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            VERSION=${{ steps.meta.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+# Releases the meshstack CLI when a tag matching "v*" is pushed.
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  goreleaser:
+    name: GoReleaser
+    runs-on: ubuntu-latest
+    permissions:
+      # Creating a release and uploading its assets counts as writing contents.
+      contents: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Let goreleaser read older tags, which it needs for the changelog.
+          fetch-depth: 0
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7.2.3
+        with:
+          args: release --clean
+        env:
+          # GitHub sets GITHUB_TOKEN automatically.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Publishes the image for the same tag. Separate job so a failing image build does
+  # not take the archives down with it.
+  image:
+    name: Image
+    needs: [ goreleaser ]
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/build-image.yml
+    with:
+      version: ${{ github.ref_name }}

.golangci.yml

@@ -1 +1,230 @@
+# Visit https://golangci-lint.run/ for usage documentation
+# and information on other useful linters.
+#
+# Kept deliberately close to the meshStack Terraform provider's configuration, so
+# that code moving between the two repositories does not trip a different linter set.
 version: "2"
+issues:
+  max-same-issues: 0
+
+formatters:
+  enable:
+    - gci
+    - gofmt
+  settings:
+    gci:
+      sections:
+        - standard     # Go standard library
+        - default      # All other external dependencies
+        - localmodule  # This repository's modules
+
+linters:
+  default: none
+  enable:
+    - depguard
+    - durationcheck
+    - errcheck
+    - copyloopvar
+    - forbidigo
+    - forcetypeassert
+    - godot
+    - ineffassign
+    - makezero
+    - misspell
+    - nilerr
+    - predeclared
+    - staticcheck
+    - usetesting
+    - unconvert
+    - unparam
+    - unused
+    - govet
+    - testifylint
+    - thelper
+
+  exclusions:
+    rules:
+      # A test that stands up an httptest.Server and points a client at it makes no request
+      # the shipped binary makes, so the rule below has nothing to say about it.
+      - path: _test\.go
+        linters:
+          - forbidigo
+
+      # The one package that may build a client, which is the whole point of the rule.
+      - path: internal/http/
+        linters:
+          - forbidigo
+
+  settings:
+    # One HTTP client for the process, built in internal/http, and nothing else may make an
+    # outbound request of its own. There used to be three: pkg/auth posted to /api/login
+    # through http.DefaultClient, which has no timeout at all; pkg/oidc kept one with a
+    # 30-second one; and the API client built a third with five minutes. Only the last of them
+    # retried, so which policy a request got depended on which package happened to make it.
+    #
+    # It sits at the module root rather than under client/ because Go's internal rule would
+    # otherwise close it to pkg/oidc and pkg/auth, and inside the module's internal tree
+    # because the Terraform provider must not be able to configure it.
+    #
+    # This is forbidigo rather than a depguard deny because depguard bans an import path and
+    # net/http is one package for three unrelated things. Denying it would also deny
+    # http.StatusOK and http.MethodPost, which every caller reading a response needs, and the
+    # http.Server that pkg/oidc/browser runs for the loopback redirect — a server, not a
+    # second client. Naming the identifiers keeps all of that legal.
+    forbidigo:
+      # Match on the type rather than on the written name. It is what makes `pkg` below work,
+      # and it is what this rule needs, because internal/http's own type is also called Client
+      # and is imported under the name http. Without it, every legitimate use would be a
+      # finding and every net/http one behind an alias would not.
+      analyze-types: true
+      forbid:
+        - pattern: \.(Client|DefaultClient|Transport|DefaultTransport|Get|Head|Post|PostForm)$
+          pkg: ^net/http$
+          msg: the process has one HTTP client, built in internal/http; take it from there rather than making another
+
+    # These rules are the dependency policy, not an enforcement of one written down
+    # elsewhere, so widening one is a decision rather than a lint fix. The lists below
+    # are exhaustive by intent: two external dependencies, cobra and charmbracelet/log,
+    # each confined to a smaller area than the module.
+    #
+    # The reason to keep it that tight is outside this repository. The meshStack
+    # Terraform provider imports client/ and pkg/auth, so every dependency reachable
+    # from those packages lands in the provider's dependency tree, and from there in
+    # the public checksum database.
+    depguard:
+      rules:
+        # The package the Terraform provider consumes most directly.
+        client:
+          files:
+            # Both patterns are needed: '**/dir/**/*.go' only matches files in
+            # subdirectories of dir, never files directly inside it.
+            - "**/client/*.go"
+            - "**/client/**/*.go"
+            - "!$test"
+          list-mode: strict
+          allow:
+            - $gostd
+            - github.com/meshcloud/meshstack-cli/client
+            # The HTTP machinery client/ is built on. It moved out of client/internal so that
+            # pkg/oidc and pkg/auth could reach it too, which is why the meshObject clients
+            # import it from the module root now.
+            - github.com/meshcloud/meshstack-cli/internal/http
+            # The setting mechanism, for MESHSTACK_SKIP_VERSION_CHECK.
+            - github.com/meshcloud/meshstack-cli/internal/setting
+
+        pkg:
+          files:
+            - "**/pkg/*.go"
+            - "**/pkg/**/*.go"
+            - "!$test"
+          list-mode: strict
+          deny:
+            - pkg: github.com/spf13/cobra
+              desc: cobra belongs in cmd/; pkg/ is also consumed by the Terraform provider
+            - pkg: github.com/meshcloud/meshstack-cli/pkg/oidc/browser
+              desc: only cmd/ and internal/cli may open a browser; the Terraform provider links pkg/auth and must not be able to reach the browser flow
+          allow:
+            - $gostd
+            - github.com/meshcloud/meshstack-cli/client
+            - github.com/meshcloud/meshstack-cli/pkg
+            # The process's one HTTP client. pkg/auth and pkg/oidc each address a different
+            # host — meshStack and the identity provider — and both go through it.
+            - github.com/meshcloud/meshstack-cli/internal/http
+            # The setting mechanism. pkg/setting is the narrower view the Terraform provider
+            # gets: a source it may supply, and a declaration it may read.
+            - github.com/meshcloud/meshstack-cli/internal/setting
+
+        # internal/http is the process's one HTTP client, and it needs nothing but the standard
+        # library to be one. It sits outside client/ because Go's internal rule would otherwise
+        # close it to pkg/, and inside the module's internal tree because the Terraform provider
+        # must not be able to configure it.
+        internal-http:
+          files:
+            - "**/internal/http/*.go"
+            - "!$test"
+          list-mode: strict
+          allow:
+            - $gostd
+
+        # internal/cli implements the CLI's half of auth.Input: flags, stdin, a terminal
+        # prompt and the browser login. Go's internal rule already keeps it out of the
+        # Terraform provider, which is what makes it the one place outside cmd/ that may
+        # reach pkg/oidc/browser. The pkg rule above cannot reach these files — its
+        # files: list names **/pkg/ — so the deny there does not apply to them.
+        internal-cli:
+          files:
+            - "**/internal/cli/*.go"
+            - "!$test"
+          list-mode: strict
+          allow:
+            - $gostd
+            - github.com/meshcloud/meshstack-cli
+
+        # cmd/ builds the command tree, and is the only place cobra is used.
+        cmd:
+          files:
+            - "**/cmd/*.go"
+            - "**/cmd/**/*.go"
+            # Excluding cmd/meshstack is what lets the next rule grant more than this
+            # one does. A file matching two rules has to satisfy both, so overlapping
+            # rules intersect and never widen.
+            - "!**/cmd/meshstack/*.go"
+            - "!$test"
+          list-mode: strict
+          deny:
+            - pkg: log # as $gostd is allowed
+              desc: Write user-facing output through the command's own streams
+          allow:
+            - $gostd
+            - log/slog # a longer prefix than the deny above, so it outranks it
+            - github.com/meshcloud/meshstack-cli
+            - github.com/spf13/cobra
+
+        # The one package that configures a logger, and therefore the only one that may
+        # name a logging implementation. Everywhere else logs through log/slog against
+        # the handler installed here.
+        cmd-meshstack:
+          files:
+            - "**/cmd/meshstack/*.go"
+            - "!$test"
+          list-mode: strict
+          deny:
+            - pkg: log # as $gostd is allowed
+              desc: Write user-facing output through the command's own streams
+          allow:
+            - $gostd
+            - log/slog
+            - github.com/meshcloud/meshstack-cli
+            - github.com/spf13/cobra
+            - github.com/charmbracelet/log
+
+        # acceptance/ drives the built binary against a live local meshStack, as a
+        # subprocess. It is deny-by-default like everything else, and it needs less than
+        # most: os/exec and net/http out of the standard library, testify, and client/ for
+        # the one struct it shares with the code under test — it decodes /mesh/info into
+        # client.MeshInfo, so the suite fails when that type and the backend disagree.
+        #
+        # It deliberately may not reach pkg/ or internal/. A test that called the CLI's own
+        # resolution to work out where its profile went would pass whenever that resolution
+        # was consistently wrong; asserting on the files and the exit status is the whole
+        # point of running the binary rather than a cobra command in-process.
+        acceptance:
+          files:
+            - "**/acceptance/*.go"
+          list-mode: strict
+          allow:
+            - $gostd
+            - github.com/meshcloud/meshstack-cli/client
+            - github.com/stretchr/testify
+
+        # Tests may additionally use testify, which is what the client's moved tests
+        # are written against.
+        tests:
+          files:
+            - "$test"
+          list-mode: strict
+          allow:
+            - $gostd
+            - github.com/meshcloud/meshstack-cli
+            - github.com/spf13/cobra
+            - github.com/stretchr/testify