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,85 @@
+# 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, so an image exists before the first release does.
+  push:
+    branches:
+      - main
+  # Builds the image but does 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
+
+      # Computed here rather than with docker/metadata-action, to keep the set of pinned
+      # actions small.
+      - name: Determine version and tags
+        id: meta
+        env:
+          # Read through the environment, because a tag name may hold shell metacharacters and
+          # ${{ }} would paste them into the script this job runs.
+          VERSION_INPUT: ${{ inputs.version }}
+        run: |
+          if [ -n "${VERSION_INPUT}" ]; then
+            version="${VERSION_INPUT}"
+            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,44 @@
+# 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:
+      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_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 }}

.github/workflows/test-acceptance.yml

@@ -0,0 +1,87 @@
+# The acceptance suite needs a whole meshStack backend, so it cannot run here. This workflow asks
+# the private meshStack mono repo to run it and report the result back as a check run.
+name: Acceptance Tests
+
+# The push trigger catches a CLI/backend regression on main, before a release tag.
+on:
+  pull_request_target:
+  push:
+    branches:
+      - main
+      # TEMPORARY, delete before merge. A pull_request_target run takes this file from the base
+      # branch, where it does not exist yet, so a push is the only trigger that can try the
+      # dispatcher out on its own pull request.
+      - feature/scaffold-cli
+
+permissions:
+  contents: read
+
+jobs:
+  # No `name:`, unlike test.yml's jobs: nothing gates on this check. The gating check is
+  # "Acceptance Tests (meshStack backend)", which meshfed-release posts.
+  request:
+    runs-on: ubuntu-latest
+    env:
+      SATELLITE_REF: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.ref || github.ref_name }}
+
+      # The run has to be in our own repository, and on a pull request the head branch has to live
+      # here too — which means its author has write access, so the code under test is code we
+      # already trust.
+      DISPATCH: ${{ github.repository_owner == 'meshcloud' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
+
+    # This workflow MUST NOT check out the pull request, and has no `actions/checkout` for that
+    # reason. `pull_request_target` runs in the base repo's context with its secrets, so checking
+    # out contributor code here would be the classic "pwn request" hole.
+    steps:
+      - name: Explain a skipped fork pull request
+        if: env.DISPATCH != 'true' && github.event_name == 'pull_request_target'
+        env:
+          BASE_REPO: ${{ github.repository }}
+        run: echo "::notice::Acceptance tests are not dispatched for a fork pull request. A maintainer has to adopt the branch into $BASE_REPO before the suite can run against it."
+
+      # Downscoped to `actions: write` at mint time, so a later widening of the app cannot leak
+      # into this workflow.
+      - name: Mint a token for the dispatch
+        id: token
+        if: env.DISPATCH == 'true'
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          # The secret holds the numeric app id, not a client id: the action reads `client-id` or
+          # the deprecated `app-id` into one value, and GitHub takes either as the JWT issuer. The
+          # name stays because it is an organization secret every satellite reads.
+          client-id: ${{ secrets.SATELLITE_GH_APP_ID }}
+          private-key: ${{ secrets.SATELLITE_GH_APP_PRIVATE_KEY }}
+          owner: meshcloud
+          repositories: meshfed-release
+          permission-actions: write
+
+      # meshfed-release pairs a satellite branch with a same-named branch of its own, so the
+      # dispatch names that branch rather than always `develop`: a `workflow_dispatch` reads the
+      # workflow file from the ref it is given, and `develop` would run the orchestration that is
+      # already merged. This token may dispatch workflows there and read nothing, so trying the
+      # dispatch is the only branch lookup available.
+      #
+      # `$SATELLITE_REF` reaches the script through the environment, never as a `${{ }}` expression
+      # GitHub substitutes into the script text: a branch named `$(id)` would otherwise run as a
+      # command.
+      - name: Request the acceptance run
+        if: env.DISPATCH == 'true'
+        env:
+          GH_TOKEN: ${{ steps.token.outputs.token }}
+        run: |
+          set -euo pipefail
+          request() {
+            gh workflow run ci-satellite.yml \
+              --repo meshcloud/meshfed-release \
+              --ref "$1" \
+              -f repo=meshstack-cli \
+              -f branch_name="$SATELLITE_REF"
+          }
+          if request "$SATELLITE_REF"; then
+            orchestrated_from="$SATELLITE_REF"
+          else
+            echo "::notice::meshfed-release has no branch $SATELLITE_REF to dispatch, so develop orchestrates this run."
+            request develop
+            orchestrated_from=develop
+          fi
+          echo "::notice::Requested an acceptance run for $SATELLITE_REF, orchestrated from meshfed-release $orchestrated_from. The result arrives as the \"Acceptance Tests (meshStack backend)\" check."

.github/workflows/test.yml

@@ -0,0 +1,101 @@
+name: Tests
+
+# No `paths-ignore` on either trigger, deliberately: a workflow skipped that way never reports its
+# checks, so a required check on it stays "expected" forever and blocks the merge. A skipped *job*
+# reports success; a skipped *workflow* does not.
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Go Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+      - run: go mod tidy
+      - run: go build -v ./...
+      - name: git diff
+        run: |
+          git diff --compact-summary --exit-code || \
+            (echo; echo "Unexpected difference in directories after 'go mod tidy'. Run 'go mod tidy' command and commit."; exit 1)
+
+  golangci:
+    needs: [ build ]
+    name: Go Lint and Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+      # Built here rather than downloaded by the action below: golangci-lint's formatters use the
+      # go/format compiled into the binary, so the formatting they enforce comes from the Go release
+      # that built the linter. The tool directive in go.mod is the single pin.
+      - name: Build the pinned golangci-lint
+        run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
+        with:
+          # The step above already installed it; the action is here for the annotations it puts on
+          # the pull request diff, which a bare `run:` does not produce.
+          install-mode: none
+      - name: Suggest fix command on failure
+        if: failure()
+        run: |
+          echo "::error::Linting or formatting issues detected. Run 'task lint -- --fix' locally to automatically fix these issues, then commit the changes."
+
+  test:
+    name: Go Test
+    needs: [ build ]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+      # Binary coverage data (GOCOVERDIR format) rather than a text profile, because only the
+      # binary form merges with the acceptance run's coverage. `-coverpkg=./...` has to match what
+      # meshfed-release runs the acceptance suite with, or the merged figure is a ratio over two
+      # different denominators.
+      - name: Run unit tests with gotestsum
+        run: |
+          mkdir -p covdata/unit
+          go tool gotestsum --junitfile junit.xml --format testdox -- \
+            -coverpkg=./... ./... -args -test.gocoverdir="$PWD/covdata/unit"
+
+      # meshfed-release finds this by the pull request head sha, so it has to be uploaded from a
+      # `pull_request` job. The contract with that side is the artifact name `covdata-unit` and
+      # covmeta.*/covcounters.* at its root, which naming the directory gives and a glob would nest.
+      - name: Upload unit coverage data
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: covdata-unit
+          path: covdata/unit
+          retention-days: 3
+
+      - name: Report unit coverage
+        if: always()
+        run: |
+          if ! ls covdata/unit/covmeta.* >/dev/null 2>&1; then
+            echo "Unit coverage: no data produced." >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          go tool covdata textfmt -i=covdata/unit -o=unit.txt
+          echo "Unit coverage: $(go tool cover -func=unit.txt | tail -1 | awk '{print $NF}')" >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -0,0 +1,34 @@
+# Binary produced by 'task build'
+/meshstack
+
+# Release artifacts produced by goreleaser
+/dist/
+
+# Go environment created by the Nix dev shell (flake.nix shellHook)
+/.nix-go/
+
+# Store symlink left behind by 'nix build'
+/result
+/result-*
+
+# Local meshStack credentials, read by the Taskfile's dotenv
+.env
+
+# A go.work names other checkouts by path, so it describes one developer's or one CI runner's
+# directory layout and never the repository. meshfed-release's go-satellite plugin writes one when
+# it runs the acceptance suite, and the meshStack Terraform provider writes one to build against a
+# paired branch of this repository.
+go.work
+go.work.sum
+
+# What the CI test command leaves behind when you reproduce it locally.
+covdata/
+junit.xml
+unit.txt
+
+# Editor and IDE directories
+.vscode/
+.idea/
+
+# Per-developer Claude Code settings; .claude/settings.json is shared and committed
+.claude/settings.local.json