Skip to content

The only tool you need to know what is happening and how to fix it.

ci: enforce the CLI's documented pre-commit gate (#307)

FrameAutomata33849e810bf9
diff --git a/.github/workflows/cli-lint.yml b/.github/workflows/cli-lint.yml
new file mode 100644
index 00000000..85627846
--- /dev/null
+++ b/.github/workflows/cli-lint.yml
@@ -0,0 +1,84 @@
+name: CLI Lint
+
+# `cd cli && just check` is the documented pre-commit gate. cli.yml already
+# covers its test, contract-test and gen-skills-check recipes; this workflow
+# covers the remaining two, lint and vulncheck.
+#
+# Separate from cli.yml because the triggers differ: cli.yml also runs on
+# backend changes so the contract tests can catch backend drift, but nothing
+# in backend/ can change the result of linting or scanning the cli module.
+#
+# Scope note: cli/test/contract is a separate Go module, so `./...` does not
+# reach it and neither job covers it. It is test-only and ships nothing.
+on:
+ push:
+ branches: [main]
+ paths:
+ - "cli/**"
+ - ".github/workflows/cli-lint.yml"
+ pull_request:
+ paths:
+ - "cli/**"
+ - ".github/workflows/cli-lint.yml"
+ # A CVE lands in the vulnerability database without anyone pushing a commit.
+ # Without this, the vulncheck job below could only ever fire on a cli/ change
+ # -- 6% of commits -- so a new advisory could sit unreported for weeks.
+ schedule:
+ - cron: "17 6 * * *"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+# Two jobs, not one: a lint nit and a stdlib CVE are different signals, and
+# neither should mask the other.
+jobs:
+ lint:
+ # The daily run exists for the vulnerability database. Lint is pinned and
+ # deterministic, so re-running it on a timer would only add noise.
+ if: github.event_name != 'schedule'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Go
+ uses: actions/setup-go@v5
+ with:
+ go-version-file: cli/go.mod
+ cache-dependency-path: cli/go.sum
+
+ # Pinned, not `latest`: a new linter release must never turn an unrelated
+ # PR red. CI is authoritative for the version -- cli/flake.nix takes
+ # whatever golangci-lint its nixpkgs input carries and cannot pin one, so
+ # a local `just lint` can legitimately differ after a flake update.
+ - name: Lint
+ uses: golangci/golangci-lint-action@v9
+ with:
+ version: v2.13.1
+ working-directory: cli
+
+ vulncheck:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: cli
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Go
+ uses: actions/setup-go@v5
+ with:
+ go-version-file: cli/go.mod
+ cache-dependency-path: cli/go.sum
+
+ # Pinned like the linter, and for the same reason. Pinning costs no
+ # freshness: govulncheck fetches the advisory database from vuln.go.dev
+ # at run time, so the schedule above is what keeps this current, not the
+ # tool version.
+ - name: Install govulncheck
+ run: go install golang.org/x/vuln/cmd/[email protected]
+
+ - name: Vulncheck
+ run: govulncheck ./...
diff --git a/CLAUDE.md b/CLAUDE.md
index a6eee3aa..e29e60a4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,7 @@ Traceway is an error tracking and monitoring platform consisting of:
| Backend | `cd backend && go run ./cmd/traceway` | API server (port 8082) |
| CLI | `cd cli && just build` | Builds `bin/traceway` |
| CLI | `cd cli && just test` | Runs unit tests |
-| CLI | `cd cli && just check` | Lint + test + vulncheck (pre-commit gate) |
+| CLI | `cd cli && just check` | Lint + test + vulncheck + skill drift + contract tests (pre-commit gate; CI enforces it for `cli/`) |
| CLI | `cd cli && just smoke-test` | Live E2E (needs `TRACEWAY_SMOKE_*` env vars) |
Set `JWT_SECRET` (min 32 characters) before running the backend — it is the one variable with no default. `SQLITE_PATH` sets the database location, defaulting to `./traceway.db` in the working directory.
diff --git a/cli/.golangci.yml b/cli/.golangci.yml
new file mode 100644
index 00000000..d7dcac65
--- /dev/null
+++ b/cli/.golangci.yml
@@ -0,0 +1,54 @@
+# Lint policy for the CLI module. `just check` is the documented pre-commit
+# gate, and CI enforces it (.github/workflows/cli-lint.yml).
+#
+# Exclusions are kept narrow. Where the codebase already checks a function's
+# error somewhere, the unactionable call sites get an explicit `_ =` instead of
+# a module-wide exclusion, so the linter keeps guarding the sites that matter.
+version: "2"
+
+run:
+ # cli/test/smoke sits behind //go:build smoke, so the default package load
+ # cannot see it. It is the module's largest end-to-end surface; lint it too.
+ build-tags:
+ - smoke
+
+linters:
+ settings:
+ errcheck:
+ exclude-functions:
+ # Cleanup of a temp file the happy path has already renamed away.
+ # A failure here means the file is gone, which is the goal.
+ - os.Remove
+ # A response body being abandoned: the status code and any decode
+ # error are what the caller acts on.
+ - (io.ReadCloser).Close
+
+ staticcheck:
+ # golangci-lint's default set, minus one check. Spelled out because bare
+ # "all" is wider than the default: it turns on the ST1003 naming checks,
+ # which would rename Id -> ID across the client's wire structs.
+ checks:
+ - all
+ - -ST1000
+ - -ST1003
+ - -ST1016
+ - -ST1020
+ - -ST1021
+ - -ST1022
+ # QF1008 wants in.timeRangeIn.resolve() shortened to in.resolve().
+ # Naming the embedded struct documents which mixin supplies the method,
+ # which is worth more than the saved characters.
+ - -QF1008
+
+# gofmt only, not gofumpt: gofmt is the language's own baseline, so gating it
+# costs no style debate. The dev shell ships gofumpt for anyone who wants the
+# stricter pass locally.
+formatters:
+ enable:
+ - gofmt
+
+issues:
+ # A gate should show everything it found. The defaults cap output at 50 per
+ # linter and 3 per identical message, which silently hides real hits.
+ max-issues-per-linter: 0
+ max-same-issues: 0
diff --git a/cli/cmd/traceway/enumvalidation_test.go b/cli/cmd/traceway/enumvalidation_test.go
index 82f96682..b4468771 100644
--- a/cli/cmd/traceway/enumvalidation_test.go
+++ b/cli/cmd/traceway/enumvalidation_test.go
@@ -20,19 +20,19 @@ func TestEnumFlagValidation_acceptsAndRejects(t *testing.T) {
args []string
}
type rejectCase struct {
- name string
- args []string
+ name string
+ args []string
expectFlagInMsg string
- expectAllowed []string
+ expectAllowed []string
}
emptyOK := func(_ http.ResponseWriter, _ *http.Request) {}
tests := []struct {
- group string
+ group string
emptyJSON string
- valid []validCase
- reject []rejectCase
+ valid []validCase
+ reject []rejectCase
}{
{
group: "exceptions list --search-type",
diff --git a/cli/cmd/traceway/mcp.go b/cli/cmd/traceway/mcp.go
index e68f4b70..7844da79 100644
--- a/cli/cmd/traceway/mcp.go
+++ b/cli/cmd/traceway/mcp.go
@@ -40,14 +40,14 @@ optional TRACEWAY_PROJECT default project id.`,
func runMcp(cmd *cobra.Command, _ []string) error {
cfg, err := resolveMcpConfig(cmd.ErrOrStderr())
if err != nil {
- fmt.Fprintln(cmd.ErrOrStderr(), "traceway mcp:", err)
+ _, _ = fmt.Fprintln(cmd.ErrOrStderr(), "traceway mcp:", err)
return newCLIError(exitcode.Auth, "not_authenticated")
}
srv := mcpserver.New(cfg)
err = srv.Run(cmd.Context(), &mcp.StdioTransport{})
if err != nil && !errors.Is(err, cmd.Context().Err()) && !isClientDisconnect(err) {
- fmt.Fprintln(cmd.ErrOrStderr(), "traceway mcp:", err)
+ _, _ = fmt.Fprintln(cmd.ErrOrStderr(), "traceway mcp:", err)
return newCLIError(exitcode.Generic, "mcp_server_failed")
}
return nil
@@ -81,7 +81,7 @@ func resolveMcpConfig(errOut io.Writer) (mcpserver.Config, error) {
url, token := os.Getenv("TRACEWAY_URL"), os.Getenv("TRACEWAY_TOKEN")
if url != "" || token != "" {
if flagProfile != "" {
- fmt.Fprintln(errOut, "traceway mcp: ignoring TRACEWAY_URL/TRACEWAY_TOKEN because --profile was given")
+ _, _ = fmt.Fprintln(errOut, "traceway mcp: ignoring TRACEWAY_URL/TRACEWAY_TOKEN because --profile was given")
} else {
if url == "" || token == "" {
return mcpserver.Config{}, errors.New("TRACEWAY_URL and TRACEWAY_TOKEN must be set together")
diff --git a/cli/cmd/traceway/setup_apply.go b/cli/cmd/traceway/setup_apply.go
index d908fb0c..e04140d8 100644
--- a/cli/cmd/traceway/setup_apply.go
+++ b/cli/cmd/traceway/setup_apply.go
@@ -170,12 +170,12 @@ func runSetupApply(cmd *cobra.Command, _ []string) error {
if err != nil {
return renderSetupAPIError(cmd.ErrOrStderr(), mode, err)
}
- fmt.Fprintf(cmd.ErrOrStderr(), "Applying plan to organization %q on %s as %s\n", session.OrganizationName, url, session.Email)
+ _, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Applying plan to organization %q on %s as %s\n", session.OrganizationName, url, session.Email)
if err := c.SubmitSetupPlan(ctx, plan.Projects); err != nil {
return renderSetupAPIError(cmd.ErrOrStderr(), mode, err)
}
- fmt.Fprintf(cmd.ErrOrStderr(), "Plan submitted. Ask the user to review and approve it at %s/setup (it also appears on the registration page if they still have it open).\nWaiting for approval...\n", url)
+ _, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Plan submitted. Ask the user to review and approve it at %s/setup (it also appears on the registration page if they still have it open).\nWaiting for approval...\n", url)
projects, err := waitForSetupDecision(ctx, cmd.ErrOrStderr(), mode, c)
if err != nil {
@@ -299,13 +299,13 @@ func renderSetupApplySummary(out io.Writer, mode output.Mode, summaries []setupA
}
tw := output.NewTabWriter(out)
- fmt.Fprintln(tw, "NAME\tFRAMEWORK\tSTATUS\tENV\tDASHBOARD")
+ _, _ = fmt.Fprintln(tw, "NAME\tFRAMEWORK\tSTATUS\tENV\tDASHBOARD")
for _, s := range summaries {
env := "-"
if s.EnvFile != "" {
env = fmt.Sprintf("%s (%s, %s)", s.EnvFile, s.EnvVar, s.EnvResult)
}
- fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", s.Name, s.Framework, s.Status, env, s.DashboardURL)
+ _, _ = fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", s.Name, s.Framework, s.Status, env, s.DashboardURL)
}
if err := tw.Flush(); err != nil {
return err
@@ -318,13 +318,13 @@ func renderSetupApplySummary(out io.Writer, mode output.Mode, summaries []setupA
}
}
if len(withDeployment) > 0 {
- fmt.Fprintln(out, "\nNext steps (deployment credentials):")
+ _, _ = fmt.Fprintln(out, "\nNext steps (deployment credentials):")
for _, p := range withDeployment {
credential := p.EnvVar
if credential == "" {
credential = "its Traceway credential"
}
- fmt.Fprintf(out, " - %s: add %s to %s. The exact command with the secret value is on %s/setup.\n", p.Name, credential, p.Deployment.Platform, url)
+ _, _ = fmt.Fprintf(out, " - %s: add %s to %s. The exact command with the secret value is on %s/setup.\n", p.Name, credential, p.Deployment.Platform, url)
}
}
return nil
diff --git a/cli/go.mod b/cli/go.mod
index 70086a7c..35376faf 100644
--- a/cli/go.mod
+++ b/cli/go.mod
@@ -2,6 +2,8 @@ module github.com/tracewayapp/traceway/cli
go 1.26.2
+toolchain go1.26.6
+
require (
github.com/google/jsonschema-go v0.4.3
github.com/google/uuid v1.6.0
diff --git a/cli/internal/config/config.go b/cli/internal/config/config.go
index 1b2da560..793d9f35 100644
--- a/cli/internal/config/config.go
+++ b/cli/internal/config/config.go
@@ -142,11 +142,11 @@ func (c *Config) Save() error {
defer os.Remove(tmpName) // no-op if rename succeeded
if err := tmp.Chmod(0o600); err != nil {
- tmp.Close()
+ _ = tmp.Close()
return fmt.Errorf("chmod temp: %w", err)
}
if _, err := tmp.Write(data); err != nil {
- tmp.Close()
+ _ = tmp.Close()
return fmt.Errorf("writing temp: %w", err)
}
if err := tmp.Close(); err != nil {
diff --git a/cli/internal/envfile/envfile.go b/cli/internal/envfile/envfile.go
index 48edc5da..326c4834 100644
--- a/cli/internal/envfile/envfile.go
+++ b/cli/internal/envfile/envfile.go
@@ -102,11 +102,11 @@ func writeAtomic(path, content string, mode fs.FileMode) error {
defer os.Remove(tmpName)
if _, err := tmp.WriteString(content); err != nil {
- tmp.Close()
+ _ = tmp.Close()
return fmt.Errorf("writing %s: %w", path, err)
}
if err := tmp.Chmod(mode); err != nil {
- tmp.Close()
+ _ = tmp.Close()
return fmt.Errorf("writing %s: %w", path, err)
}
if err := tmp.Close(); err != nil {
diff --git a/cli/internal/output/yaml.go b/cli/internal/output/yaml.go
index 9d61969f..b66fa66e 100644
--- a/cli/internal/output/yaml.go
+++ b/cli/internal/output/yaml.go
@@ -25,6 +25,8 @@ func RenderYAML(w io.Writer, v any, fields []string) error {
}
enc := yaml.NewEncoder(w)
enc.SetIndent(2)
- defer enc.Close()
+ // Encode flushes the whole document, so Close only finalizes the stream and
+ // has no buffered output left that could fail here.
+ defer func() { _ = enc.Close() }()
return enc.Encode(generic)
}
diff --git a/cli/internal/state/state.go b/cli/internal/state/state.go
index 9108e66d..ab09c704 100644
--- a/cli/internal/state/state.go
+++ b/cli/internal/state/state.go
@@ -86,11 +86,11 @@ func (s *State) Save() error {
defer os.Remove(tmpName) // no-op if rename succeeded
if err := tmp.Chmod(0o600); err != nil {
- tmp.Close()
+ _ = tmp.Close()
return fmt.Errorf("chmod temp: %w", err)
}
if _, err := tmp.Write(data); err != nil {
- tmp.Close()
+ _ = tmp.Close()
return fmt.Errorf("writing temp: %w", err)
}
if err := tmp.Close(); err != nil {
diff --git a/cli/pkg/client/client_test.go b/cli/pkg/client/client_test.go
index f0ea83e3..150e259a 100644
--- a/cli/pkg/client/client_test.go
+++ b/cli/pkg/client/client_test.go
@@ -69,7 +69,7 @@ func TestDo_omitsAuthHeaderWhenJWTEmpty(t *testing.T) {
if got := r.Header.Get("Authorization"); got != "" {
t.Errorf("expected no Authorization header, got %q", got)
}
- w.Write([]byte(`{}`))
+ _, _ = w.Write([]byte(`{}`))
}))
defer srv.Close()
diff --git a/cli/test/contract/go.mod b/cli/test/contract/go.mod
index b1e388db..8b9283e3 100644
--- a/cli/test/contract/go.mod
+++ b/cli/test/contract/go.mod
@@ -2,6 +2,8 @@ module github.com/tracewayapp/traceway/cli/test/contract
go 1.26.2
+toolchain go1.26.6
+
require (
github.com/google/uuid v1.6.0
github.com/modelcontextprotocol/go-sdk v1.6.1
diff --git a/cli/test/smoke/mcp_test.go b/cli/test/smoke/mcp_test.go
index 473f8379..8e2f4710 100644
--- a/cli/test/smoke/mcp_test.go
+++ b/cli/test/smoke/mcp_test.go
@@ -61,7 +61,7 @@ func TestMcp_stdioHandshake(t *testing.T) {
}
defer func() { _ = cmd.Process.Kill() }()
- fmt.Fprintln(stdin, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}`)
+ _, _ = fmt.Fprintln(stdin, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}`)
line := make(chan string, 1)
go func() {