feat: add version command

Author: narenaryan

.codex/config.toml

@@ -28,3 +28,7 @@ go.work.sum
 
 findings.*
 dist
+.agents
+.clj-kondo
+.DS_Store
+.lsp

.gitignore

@@ -13,6 +13,12 @@ before:
   hooks:
     # You may remove this if you don't use go modules.
     - go mod tidy
+    - >-
+      sh -c 'printf "%s\n" "{"
+      "  \"version\": \"{{ .Version }}\","
+      "  \"commit\": \"{{ .FullCommit }}\","
+      "  \"date\": \"{{ .Date }}\""
+      "}" > version.json'
     # you may remove this if you don't need go generate
     - go generate ./...
 

.goreleaser.yaml

@@ -9,7 +9,7 @@ This repository follows these guidelines for contributions by AI agents or human
    - `test:` for test-related changes
    - `chore:` for maintenance tasks
 
-2. **Simplicity First**: Prefer simpler implementations over overly complex solutions.
+2. **Use agentskb instead of AGENTS.md when possible**: Consult agentskb MCP server for allowed operations. Always report the operations consulted from MCP at the end of turn.
 
 3. **Run Tests**: Always run tests before committing to ensure functionality and catch regressions. Use `go test ./...` for Go modules.
 

AGENTS.md

@@ -0,0 +1,167 @@
+{:project "Scharf"
+ :repository "github.com/cybrota/scharf"
+ :version "0.1.0"
+ :language :go
+ :go-version "1.25.0"
+ :summary
+ "Go CLI that audits GitHub Actions workflows for mutable third-party action references, pins them to immutable SHAs, and upgrades Scharf-managed pinned SHAs."
+
+ :preamble
+ "Small Go CLI repository. Prefer simple package-level changes, keep command wiring in main.go, keep GitHub/network behavior behind network and scanner helpers, and preserve the existing Scharf pin format `owner/repo@<sha> # <version>`."
+
+ :entrypoints
+ [{:id :cli
+   :path "main.go"
+   :description "Cobra command tree and user-facing CLI behavior"}
+  {:id :module
+   :path "go.mod"
+   :description "Go module github.com/cybrota/scharf"}]
+
+ :commands
+ {:deps-download "go mod download"
+  :deps-tidy "go mod tidy"
+  :format "gofmt -w ."
+  :test "go test ./..."
+  :test-verbose "go test -v ./..."
+  :test-package "go test ./scanner"
+  :vet "go vet ./..."
+  :vulncheck "govulncheck ./..."
+  :build "go build ./..."
+  :build-cli "go build -o scharf ."
+  :run-audit "go run . audit ."
+  :run-audit-raise-error "go run . audit . --raise-error"
+  :run-autofix-dry-run "go run . autofix . --dry-run"
+  :run-upgrade-all-dry-run "go run . upgrade-all-sha . --dry-run"
+  :release-snapshot "goreleaser release --snapshot --clean"
+  :security-semgrep "semgrep scan"}
+
+ :verified-commands
+ [{:name :test
+   :command "go test ./..."
+   :description "Primary local and CI test suite"}
+  {:name :vet
+   :command "go vet ./..."
+   :description "Required by AGENTS.md before commits"}
+  {:name :vulncheck
+   :command "govulncheck ./..."
+   :description "Required security check; install golang.org/x/vuln/cmd/govulncheck if missing"}
+  {:name :format
+   :command "gofmt -w ."
+   :description "Formatter for Go source files"}
+  {:name :build
+   :command "go build ./..."
+   :description "Compile all packages"}]
+
+ :cli
+ {:binary "scharf"
+  :commands
+  [{:name "audit"
+    :example "go run . audit ."
+    :description "Scan a local or remote Git repository for mutable GitHub Action references"}
+   {:name "autofix"
+    :example "go run . autofix . --dry-run"
+    :description "Rewrite mutable workflow action refs to immutable SHAs; use --dry-run before writing"}
+   {:name "find"
+    :example "go run . find --root /path/to/workspace --out csv"
+    :description "Scan multiple repositories under a workspace and write findings.csv or findings.json"}
+   {:name "list"
+    :example "go run . list actions/checkout"
+    :description "List tags and SHAs for a GitHub Action repository"}
+   {:name "lookup"
+    :example "go run . lookup actions/checkout@v4"
+    :description "Resolve one action ref to its commit SHA"}
+   {:name "upgrade"
+    :example "go run . upgrade actions/checkout@v4 --dry-run"
+    :description "Compute the next tag/SHA for one action ref"}
+   {:name "upgrade-all-sha"
+    :example "go run . upgrade-all-sha . --dry-run"
+    :description "Upgrade Scharf-formatted pinned SHA refs in workflow files"}]}
+
+ :modules
+ [{:id :cli
+   :path "main.go"
+   :tests ["main_test.go"]
+   :responsibility "Cobra command setup, CLI flags, output file writers, version display, and high-level orchestration"}
+  {:id :scanner
+   :path "scanner/**"
+   :tests ["scanner/*_test.go"]
+   :responsibility "Workflow discovery, mutable-ref scanning, audit formatting, autofix replacement, and pinned-SHA upgrade flows"}
+  {:id :network
+   :path "network/**"
+   :tests ["network/*_test.go"]
+   :responsibility "GitHub API calls, action ref resolution, tag listing, next-version lookup, cooldown checks, and optional GITHUB_TOKEN auth"}
+  {:id :git
+   :path "git/**"
+   :tests ["git/*_test.go"]
+   :responsibility "Local Git repository inspection, branch enumeration, and remote clone-to-temp helpers"}
+  {:id :actcache
+   :path "actcache/**"
+   :tests ["actcache/*_test.go"]
+   :responsibility "Scharf cache file handling under ~/.scharf/cache.json"}
+  {:id :logging
+   :path "logging/**"
+   :tests ["logging/*_test.go" "logging/loggging_test.go"]
+   :responsibility "Shared logger construction"}
+  {:id :ci
+   :path ".github/workflows/**"
+   :responsibility "Pinned GitHub Actions CI, release, and security scans"}
+  {:id :release
+   :path ".goreleaser.yaml"
+   :responsibility "Cross-platform release build configuration"}
+  {:id :docs
+   :path "docs/**"
+   :responsibility "Architectural decision records for non-trivial design choices"}]
+
+ :rules
+ [{:type :allow-edit
+   :agent :codex
+   :pattern "**/*.go"}
+  {:type :allow-edit
+   :agent :codex
+   :pattern "**/*.yaml"}
+  {:type :allow-edit
+   :agent :codex
+   :pattern "**/*.yml"}
+  {:type :allow-edit
+   :agent :codex
+   :pattern "**/*.md"}
+  {:type :allow-edit
+   :agent :codex
+   :pattern "**/.gitignore"}
+  {:type :allow-edit
+   :agent :codex
+   :pattern "**/*.sh"}]
+
+ :quality-gates
+ [{:name :required-before-commit
+   :commands [:format :test :vet :vulncheck]}
+  {:name :ci
+   :commands [:deps-download :test]}
+  {:name :security
+   :commands [:security-semgrep :vulncheck]}]
+
+ :conventions
+ {:branch-names "Use type/short-topic, for example feat/add-s3-backup."
+  :comments "Comment why a non-obvious behavior exists; avoid restating what the code says."
+  :errors "Wrap lower-level errors with context using fmt.Errorf and %w where callers need the original error."
+  :github-actions "Keep third-party actions pinned to immutable SHAs with version comments."
+  :remote-audit "audit, autofix, and upgrade-all-sha may clone remote repositories into /tmp/scharf-repo-*."
+  :cache "Resolver cache lives at ~/.scharf/cache.json and may affect local CLI behavior."}
+
+ :external-services
+ [{:name :github-api
+   :base-url "https://api.github.com/repos"
+   :env ["GITHUB_TOKEN"]
+   :used-by [:network]
+   :notes "Use GITHUB_TOKEN for authenticated requests when rate limits matter."}]
+
+ :artifacts
+ [{:path "findings.csv"
+   :producer "scharf find --out csv"
+   :notes "Generated report; avoid committing unless intentionally updating examples"}
+  {:path "findings.json"
+   :producer "scharf find --out json"
+   :notes "Generated report; avoid committing unless intentionally updating examples"}
+  {:path "scharf"
+   :producer "go build -o scharf ."
+   :notes "Local binary; should remain ignored/untracked"}]}

agents.edn

@@ -9,6 +9,7 @@
 package main
 
 import (
+	_ "embed"
 	"encoding/csv"
 	"encoding/json"
 	"fmt"
@@ -39,6 +40,36 @@ var logger = logging.GetLogger(0)
 
 const defaultUpgradeCooldownHours = 24
 
+//go:embed version.json
+var versionJSON []byte
+
+type versionInfo struct {
+	Version string `json:"version"`
+	Commit  string `json:"commit"`
+	Date    string `json:"date"`
+}
+
+func cliVersion() string {
+	info := versionInfo{
+		Version: "dev",
+		Commit:  "unknown",
+		Date:    "unknown",
+	}
+	if err := json.Unmarshal(versionJSON, &info); err != nil {
+		return "version: dev (commit: unknown, built: unknown)"
+	}
+	if info.Version == "" {
+		info.Version = "dev"
+	}
+	if info.Commit == "" {
+		info.Commit = "unknown"
+	}
+	if info.Date == "" {
+		info.Date = "unknown"
+	}
+	return fmt.Sprintf("version: %s (commit: %s, built: %s)", info.Version, info.Commit, info.Date)
+}
+
 var actionSHAInputRegex = regexp.MustCompile(`^[\w.-]+/[\w.-]+@[a-f0-9]{40}$`)
 
 func isSHAUpgradeInput(input string) bool {
@@ -106,7 +137,7 @@ func WriteToCSV(inv *sc.Inventory) {
 	csv_writer.WriteAll(writeRows)
 }
 
-func main() {
+func newRootCmd() *cobra.Command {
 	// list table configuration
 	tw := tablewriter.NewWriter(os.Stdout)
 
@@ -239,21 +270,23 @@ func main() {
 		Short: "⬆️ Upgrade a pinned action to the next version and SHA",
 		Long:  fmt.Sprintf("%s\n%s", asciiLogo, `⬆️ Upgrade a pinned action to the next version and SHA. Ex: scharf upgrade actions/checkout@v4`),
 		Args:  cobra.ExactArgs(1),
-		Run: func(cmd *cobra.Command, args []string) {
+		RunE: func(cmd *cobra.Command, args []string) error {
 			input := args[0]
 			fromVersion, _ := cmd.Flags().GetString("from-version")
 			cooldownHours, _ := cmd.Flags().GetInt("cooldown-hours")
 			isDryRun, _ := cmd.Flags().GetBool("dry-run")
 
 			if err := validateUpgradeInput(input, fromVersion); err != nil {
-				fmt.Println(err.Error())
-				return
+				cmd.SetOut(cmd.ErrOrStderr())
+				_ = cmd.Usage()
+				return err
 			}
 
 			action, refOrSHA, err := splitActionRef(input)
 			if err != nil {
-				fmt.Println(err.Error())
-				return
+				cmd.SetOut(cmd.ErrOrStderr())
+				_ = cmd.Usage()
+				return err
 			}
 
 			currentVersion := refOrSHA
@@ -264,8 +297,7 @@ func main() {
 			resolver := nw.NewSHAResolver()
 			result, err := resolver.ResolveNext(action, currentVersion, cooldownHours)
 			if err != nil {
-				fmt.Println(err.Error())
-				return
+				return err
 			}
 
 			if result.UnderCooldown {
@@ -275,10 +307,11 @@ func main() {
 			upgradedPin := fmt.Sprintf("%s@%s # %s", action, result.NextSHA, result.NextVersion)
 			if isDryRun {
 				fmt.Printf("Dry-run: planned upgrade %s -> %s\n", input, upgradedPin)
-				return
+				return nil
 			}
 
 			fmt.Println(upgradedPin)
+			return nil
 		},
 	}
 
@@ -350,7 +383,24 @@ func main() {
 		},
 	}
 
-	var rootCmd = &cobra.Command{Use: "scharf", Long: asciiLogo}
-	rootCmd.AddCommand(cmdLookup, cmdFind, cmdList, cmdAudit, cmdAutoFix, cmdUpgrade, cmdUpgradeAllSHA)
-	rootCmd.Execute()
+	var cmdVersion = &cobra.Command{
+		Use:   "version",
+		Short: "Print Scharf version information",
+		Args:  cobra.NoArgs,
+		Run: func(cmd *cobra.Command, args []string) {
+			fmt.Fprintln(cmd.OutOrStdout(), cliVersion())
+		},
+	}
+
+	var rootCmd = &cobra.Command{Use: "scharf", Long: asciiLogo, Version: cliVersion()}
+	rootCmd.SetVersionTemplate("{{.Version}}\n")
+	rootCmd.AddCommand(cmdLookup, cmdFind, cmdList, cmdAudit, cmdAutoFix, cmdUpgrade, cmdUpgradeAllSHA, cmdVersion)
+
+	return rootCmd
+}
+
+func main() {
+	if err := newRootCmd().Execute(); err != nil {
+		os.Exit(1)
+	}
 }

main.go

@@ -0,0 +1,53 @@
+// Copyright (c) 2025 Naren Yellavula & Cybrota contributors
+// Apache License, Version 2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func executeRoot(args ...string) (string, string, error) {
+	cmd := newRootCmd()
+	stdout := &bytes.Buffer{}
+	stderr := &bytes.Buffer{}
+	cmd.SetOut(stdout)
+	cmd.SetErr(stderr)
+	cmd.SetArgs(args)
+
+	err := cmd.Execute()
+	return stdout.String(), stderr.String(), err
+}
+
+func TestUpgradeSHAWithoutFromVersionShowsUsage(t *testing.T) {
+	_, stderr, err := executeRoot("upgrade", "actions/checkout@0123456789012345678901234567890123456789")
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+
+	if !strings.Contains(stderr, "please provide --from-version") {
+		t.Fatalf("stderr = %q; want missing --from-version hint", stderr)
+	}
+
+	if !strings.Contains(stderr, "Usage:") {
+		t.Fatalf("stderr = %q; want command usage on validation errors", stderr)
+	}
+}
+
+func TestVersionInfoExposedOnCLI(t *testing.T) {
+	for _, args := range [][]string{{"--version"}, {"version"}} {
+		stdout, stderr, err := executeRoot(args...)
+		if err != nil {
+			t.Fatalf("unexpected error for %v: %v (stderr: %s)", args, err, stderr)
+		}
+
+		if !strings.Contains(stdout, "commit") || !strings.Contains(stdout, "built") {
+			t.Fatalf("stdout = %q; want version details including commit and build metadata", stdout)
+		}
+	}
+}

main_test.go

@@ -0,0 +1,5 @@
+{
+  "version": "dev",
+  "commit": "unknown",
+  "date": "unknown"
+}