From 3170222b27b73961420acbfd63659dc104aabaa0 Mon Sep 17 00:00:00 2001
From: Lucas Machado <lucas.dpmachado@gmail.com>
Date: Fri, 10 Jul 2026 21:23:54 +0200
Subject: [PATCH] feat: add install-only setup action

---
 .github/workflows/pr.yml            | 17 +++++++++++++
 .structlint.yaml                    |  1 +
 README.md                           | 11 ++++++++
 docs/specs/013-setup-action.md      | 31 +++++++++++++++++++++++
 docs/specs/013-setup-action.plan.md |  7 ++++++
 setup/action.yml                    | 39 +++++++++++++++++++++++++++++
 6 files changed, 106 insertions(+)
 create mode 100644 docs/specs/013-setup-action.md
 create mode 100644 docs/specs/013-setup-action.plan.md
 create mode 100644 setup/action.yml

diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 54e9e53..df421c1 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -62,6 +62,23 @@ jobs:
         with:
           since: origin/${{ github.base_ref }}
 
+  setup-action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - id: setup
+        uses: ./setup
+        with:
+          version: v0.6.0
+      - name: Verify setup outputs and executable
+        env:
+          BINARY: ${{ steps.setup.outputs.binary }}
+          VERSION: ${{ steps.setup.outputs.version }}
+        run: |
+          test -x "$BINARY"
+          test -n "$VERSION"
+          test "$(command -v structlint)" = "$BINARY"
+
   lint:
     runs-on: ubuntu-latest
     steps:
diff --git a/.structlint.yaml b/.structlint.yaml
index 7d077da..68539f7 100644
--- a/.structlint.yaml
+++ b/.structlint.yaml
@@ -17,6 +17,7 @@ dir_structure:
     - ".github/**"          # GitHub configuration
     - "schema/**"           # JSON Schema for editor autocomplete
     - "skills/**"           # Shipped agent skill (SKILL.md)
+    - "setup/**"            # Install-only GitHub Action
   disallowedPaths:
     - "vendor/**"           # Vendor dependencies
     - "node_modules/**"     # Node.js dependencies
diff --git a/README.md b/README.md
index 1fd16ce..c96b17b 100644
--- a/README.md
+++ b/README.md
@@ -513,6 +513,17 @@ structlint completion fish > ~/.config/fish/completions/structlint.fish
 
 ### GitHub Action
 
+Install without running Structlint (for Gauntlet or custom pipelines):
+
+```yaml
+- uses: AxeForging/structlint/setup@v0.6.0
+  with:
+    version: v0.6.0
+```
+
+Pin both references for reproducible CI; use `version: latest` only when
+intentionally opting into floating releases.
+
 The simplest way to use structlint in CI — no Go setup required:
 
 ```yaml
diff --git a/docs/specs/013-setup-action.md b/docs/specs/013-setup-action.md
new file mode 100644
index 0000000..0887b2c
--- /dev/null
+++ b/docs/specs/013-setup-action.md
@@ -0,0 +1,31 @@
+# Setup action
+
+## Problem
+
+The root action installs and runs Structlint, so workflows that orchestrate it
+through Gauntlet must duplicate installer shell code.
+
+## Approach
+
+Add an install-only `setup/action.yml` composite action. It accepts `version`
+(default `v0.6.0`) and `install-dir` (default runner temp), invokes the existing
+checksum-verifying installer, adds the directory to `PATH`, and verifies the
+binary. Keep the root action backward-compatible.
+
+## Requirements
+
+- Never compile Structlint or silently fall back to `go install`.
+- Preserve checksum verification from `install.sh`.
+- Permit an explicit pinned tag or `latest`.
+- Expose the installed version and binary path as outputs.
+- Document pinned usage through Gauntlet.
+
+## Test plan
+
+- Existing executable installer regression test remains authoritative.
+- Exercise the composite action in the repository PR workflow.
+- Run the real Structlint and Dupehound gates through Gauntlet.
+
+## Rollout
+
+Pilot in Structlint, then apply the same contract to Dupehound and Gauntlet.
diff --git a/docs/specs/013-setup-action.plan.md b/docs/specs/013-setup-action.plan.md
new file mode 100644
index 0000000..6c29557
--- /dev/null
+++ b/docs/specs/013-setup-action.plan.md
@@ -0,0 +1,7 @@
+# Setup action plan
+
+- [x] Add install-only composite action and outputs.
+- [x] Add action contract validation to PR CI.
+- [x] Document direct and Gauntlet usage.
+- [ ] Validate and merge the pilot PR.
+- [ ] Roll the contract into Dupehound and Gauntlet.
diff --git a/setup/action.yml b/setup/action.yml
new file mode 100644
index 0000000..42ac0b5
--- /dev/null
+++ b/setup/action.yml
@@ -0,0 +1,39 @@
+name: Setup Structlint
+description: Install a checksum-verified Structlint release and add it to PATH.
+author: AxeForging
+inputs:
+  version:
+    description: Structlint release tag, or latest for a floating install.
+    required: false
+    default: v0.6.0
+  install-dir:
+    description: Installation directory. Empty uses RUNNER_TEMP/structlint-bin.
+    required: false
+    default: ""
+outputs:
+  binary:
+    description: Absolute path to the installed binary.
+    value: ${{ steps.install.outputs.binary }}
+  version:
+    description: Version reported by the installed binary.
+    value: ${{ steps.install.outputs.version }}
+runs:
+  using: composite
+  steps:
+    - id: install
+      shell: bash
+      env:
+        REQUESTED_VERSION: ${{ inputs.version }}
+        REQUESTED_DIR: ${{ inputs.install-dir }}
+      run: |
+        set -euo pipefail
+        install_dir="${REQUESTED_DIR:-${RUNNER_TEMP}/structlint-bin}"
+        STRUCTLINT_VERSION="$REQUESTED_VERSION" STRUCTLINT_INSTALL_DIR="$install_dir" "$GITHUB_ACTION_PATH/../install.sh"
+        binary="$install_dir/structlint"
+        test -x "$binary"
+        echo "$install_dir" >> "$GITHUB_PATH"
+        echo "binary=$binary" >> "$GITHUB_OUTPUT"
+        echo "version=$($binary --version | head -1)" >> "$GITHUB_OUTPUT"
+branding:
+  icon: check-square
+  color: blue