[Crane: crane-migration-python-to-go-full-apm-cli-rewrite] Iteration 4: Milestone 3 -- utils + constants

Port internal/constants, internal/utils/normalization, internal/utils/sha,
internal/utils/paths with parity tests.

- internal/constants: APM file/dir name constants, InstallMode, DefaultSkipDirs
- internal/utils/normalization: BOM strip, CRLF norm, Build ID strip, Normalize
- internal/utils/sha: FormatShortSHA (8-char hex validation, sentinel handling)
- internal/utils/paths: PortableRelpath (cross-platform forward-slash paths)

49 parity tests passing (was 0 on current branch, best was 0.0430).
migration_score: 0.1622 (prev best: 0.0430, delta: +0.1192)

Run: https://github.com/githubnext/apm/actions/runs/26262872727

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: github-actions[bot]

internal/constants/constants.go

@@ -0,0 +1,44 @@
+// Package constants provides shared constants for the APM CLI.
+package constants
+
+// File and directory names
+const (
+	APMYMLFilename            = "apm.yml"
+	APMLockFilename           = "apm.lock"
+	APMModulesDir             = "apm_modules"
+	APMDir                    = ".apm"
+	SkillMDFilename           = "SKILL.md"
+	AgentsMDFilename          = "AGENTS.md"
+	ClaudeMDFilename          = "CLAUDE.md"
+	GithubDir                 = ".github"
+	ClaudeDir                 = ".claude"
+	GitignoreFilename         = ".gitignore"
+	APMModulesGitignorePattern = "apm_modules/"
+)
+
+// InstallMode controls which dependency types are installed.
+type InstallMode string
+
+const (
+	InstallModeAll InstallMode = "all"
+	InstallModeAPM InstallMode = "apm"
+	InstallModeMCP InstallMode = "mcp"
+)
+
+// DefaultSkipDirs lists directories unconditionally skipped during
+// primitive-file discovery. These never contain APM primitives or user
+// source files and can be very large (e.g. node_modules, .git objects).
+// NOTE: .apm is intentionally absent -- it is where primitives live.
+var DefaultSkipDirs = map[string]bool{
+	".git":          true,
+	"node_modules":  true,
+	"__pycache__":   true,
+	".pytest_cache": true,
+	".venv":         true,
+	"venv":          true,
+	".tox":          true,
+	"build":         true,
+	"dist":          true,
+	".mypy_cache":   true,
+	"apm_modules":   true,
+}

internal/constants/constants_test.go

@@ -0,0 +1,68 @@
+// Package constants_test provides parity tests for constants.
+package constants_test
+
+import (
+	"testing"
+
+	"github.com/githubnext/apm/internal/constants"
+)
+
+// TestParityConstantsFilenames verifies file and directory name constants
+// match the Python source (src/apm_cli/constants.py).
+func TestParityConstantsFilenames(t *testing.T) {
+	cases := []struct {
+		name     string
+		got      string
+		expected string
+	}{
+		{"APMYMLFilename", constants.APMYMLFilename, "apm.yml"},
+		{"APMLockFilename", constants.APMLockFilename, "apm.lock"},
+		{"APMModulesDir", constants.APMModulesDir, "apm_modules"},
+		{"APMDir", constants.APMDir, ".apm"},
+		{"SkillMDFilename", constants.SkillMDFilename, "SKILL.md"},
+		{"AgentsMDFilename", constants.AgentsMDFilename, "AGENTS.md"},
+		{"ClaudeMDFilename", constants.ClaudeMDFilename, "CLAUDE.md"},
+		{"GithubDir", constants.GithubDir, ".github"},
+		{"ClaudeDir", constants.ClaudeDir, ".claude"},
+		{"GitignoreFilename", constants.GitignoreFilename, ".gitignore"},
+		{"APMModulesGitignorePattern", constants.APMModulesGitignorePattern, "apm_modules/"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if tc.got != tc.expected {
+				t.Errorf("got %q, want %q", tc.got, tc.expected)
+			}
+		})
+	}
+}
+
+// TestParityConstantsInstallMode verifies InstallMode values match Python.
+func TestParityConstantsInstallMode(t *testing.T) {
+	if constants.InstallModeAll != "all" {
+		t.Errorf("InstallModeAll: got %q, want %q", constants.InstallModeAll, "all")
+	}
+	if constants.InstallModeAPM != "apm" {
+		t.Errorf("InstallModeAPM: got %q, want %q", constants.InstallModeAPM, "apm")
+	}
+	if constants.InstallModeMCP != "mcp" {
+		t.Errorf("InstallModeMCP: got %q, want %q", constants.InstallModeMCP, "mcp")
+	}
+}
+
+// TestParityConstantsDefaultSkipDirs verifies the default skip dirs set
+// matches Python's DEFAULT_SKIP_DIRS frozenset.
+func TestParityConstantsDefaultSkipDirs(t *testing.T) {
+	expected := []string{
+		".git", "node_modules", "__pycache__", ".pytest_cache",
+		".venv", "venv", ".tox", "build", "dist", ".mypy_cache", "apm_modules",
+	}
+	for _, dir := range expected {
+		if !constants.DefaultSkipDirs[dir] {
+			t.Errorf("DefaultSkipDirs missing %q", dir)
+		}
+	}
+	// .apm must NOT be in skip dirs
+	if constants.DefaultSkipDirs[".apm"] {
+		t.Error("DefaultSkipDirs must not contain .apm")
+	}
+}

internal/utils/normalization/normalization.go

@@ -0,0 +1,43 @@
+// Package normalization provides bytes-in / bytes-out content normalization
+// helpers. Mirrors src/apm_cli/utils/normalization.py.
+//
+// Used by drift-detection to compare deployed file bytes against the replay
+// scratch tree without flagging legitimate, deterministic differences:
+//   - Line-ending differences (CRLF vs LF)
+//   - UTF-8 BOMs at the start of the file
+//   - APM <!-- Build ID: <sha> --> headers re-stamped on every recompile
+package normalization
+
+import (
+	"bytes"
+	"regexp"
+)
+
+// BOM is the UTF-8 byte order mark.
+var BOM = []byte{0xef, 0xbb, 0xbf}
+
+// buildIDPattern matches APM <!-- Build ID: <sha> --> headers.
+var buildIDPattern = regexp.MustCompile(`(?i)<!--\s*Build ID:\s*[a-f0-9]+\s*-->\s*\n?`)
+
+// StripBuildID removes APM <!-- Build ID: <sha> --> headers wherever they appear.
+func StripBuildID(content []byte) []byte {
+	return buildIDPattern.ReplaceAll(content, nil)
+}
+
+// NormalizeLineEndings converts CRLF to LF; leaves bare CR alone.
+func NormalizeLineEndings(content []byte) []byte {
+	return bytes.ReplaceAll(content, []byte("\r\n"), []byte("\n"))
+}
+
+// StripBOM drops a UTF-8 BOM at the start of the file (only at offset 0).
+func StripBOM(content []byte) []byte {
+	if bytes.HasPrefix(content, BOM) {
+		return content[len(BOM):]
+	}
+	return content
+}
+
+// Normalize applies all drift-tolerant normalizations to a file's bytes.
+func Normalize(content []byte) []byte {
+	return StripBuildID(NormalizeLineEndings(StripBOM(content)))
+}

internal/utils/normalization/normalization_test.go

@@ -0,0 +1,90 @@
+// Package normalization_test provides parity tests for normalization helpers.
+// Mirrors the behaviour of src/apm_cli/utils/normalization.py.
+package normalization_test
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/githubnext/apm/internal/utils/normalization"
+)
+
+// TestParityNormalizationStripBOM verifies BOM stripping matches Python.
+func TestParityNormalizationStripBOM(t *testing.T) {
+	bom := normalization.BOM
+	cases := []struct {
+		name     string
+		input    []byte
+		expected []byte
+	}{
+		{"no bom", []byte("hello"), []byte("hello")},
+		{"bom prefix", append(append([]byte{}, bom...), []byte("hello")...), []byte("hello")},
+		{"bom only", bom, []byte{}},
+		{"bom in middle not stripped", []byte("hel\xef\xbb\xbflo"), []byte("hel\xef\xbb\xbflo")},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := normalization.StripBOM(tc.input)
+			if !bytes.Equal(got, tc.expected) {
+				t.Errorf("got %q, want %q", got, tc.expected)
+			}
+		})
+	}
+}
+
+// TestParityNormalizationCRLF verifies CRLF-to-LF conversion matches Python.
+func TestParityNormalizationCRLF(t *testing.T) {
+	cases := []struct {
+		name     string
+		input    []byte
+		expected []byte
+	}{
+		{"no crlf", []byte("hello\nworld\n"), []byte("hello\nworld\n")},
+		{"crlf", []byte("hello\r\nworld\r\n"), []byte("hello\nworld\n")},
+		{"bare cr preserved", []byte("hello\rworld"), []byte("hello\rworld")},
+		{"mixed", []byte("a\r\nb\nc\r\n"), []byte("a\nb\nc\n")},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := normalization.NormalizeLineEndings(tc.input)
+			if !bytes.Equal(got, tc.expected) {
+				t.Errorf("got %q, want %q", got, tc.expected)
+			}
+		})
+	}
+}
+
+// TestParityNormalizationStripBuildID verifies Build ID header stripping.
+func TestParityNormalizationStripBuildID(t *testing.T) {
+	cases := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{"no build id", "hello world", "hello world"},
+		{"build id", "<!-- Build ID: abc123 -->\nhello", "hello"},
+		{"build id uppercase", "<!-- BUILD ID: abc123 -->\nhello", "hello"},
+		{"build id no newline", "<!-- Build ID: abc123 -->hello", "hello"},
+		{"build id with spaces", "<!--  Build ID:  abc123  -->\nhello", "hello"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := string(normalization.StripBuildID([]byte(tc.input)))
+			if got != tc.expected {
+				t.Errorf("got %q, want %q", got, tc.expected)
+			}
+		})
+	}
+}
+
+// TestParityNormalizationNormalize verifies composite Normalize function.
+func TestParityNormalizationNormalize(t *testing.T) {
+	bom := normalization.BOM
+	// Build a payload with BOM + Build ID + CRLF
+	input := append(append([]byte{}, bom...), []byte("<!-- Build ID: deadbeef -->\r\nhello\r\nworld\r\n")...)
+	expected := []byte("hello\nworld\n")
+	got := normalization.Normalize(input)
+	if !bytes.Equal(got, expected) {
+		t.Errorf("got %q, want %q", got, expected)
+	}
+}

internal/utils/paths/paths.go

@@ -0,0 +1,33 @@
+// Package paths provides cross-platform path utilities for APM CLI.
+// Mirrors src/apm_cli/utils/paths.py (portable_relpath function).
+package paths
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+// PortableRelpath returns a forward-slash relative path from base to path,
+// resolving both sides first. When path is not under base (or resolution
+// fails), falls back to the resolved absolute path.
+//
+// Mirrors Python's portable_relpath() from utils/paths.py.
+func PortableRelpath(path, base string) string {
+	absPath, err := filepath.Abs(path)
+	if err != nil {
+		return toSlash(path)
+	}
+	absBase, err := filepath.Abs(base)
+	if err != nil {
+		return toSlash(absPath)
+	}
+	rel, err := filepath.Rel(absBase, absPath)
+	if err != nil {
+		return toSlash(absPath)
+	}
+	return toSlash(rel)
+}
+
+func toSlash(p string) string {
+	return strings.ReplaceAll(p, "\\", "/")
+}

internal/utils/paths/paths_test.go

@@ -0,0 +1,37 @@
+// Package paths_test provides parity tests for path utilities.
+package paths_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/githubnext/apm/internal/utils/paths"
+)
+
+// TestParityPathsPortableRelpath verifies portable_relpath behavior.
+func TestParityPathsPortableRelpath(t *testing.T) {
+	tmp := t.TempDir()
+	sub := filepath.Join(tmp, "a", "b")
+	if err := os.MkdirAll(sub, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	cases := []struct {
+		name     string
+		path     string
+		base     string
+		expected string
+	}{
+		{"nested path", filepath.Join(tmp, "a", "b", "c.txt"), tmp, "a/b/c.txt"},
+		{"direct child", filepath.Join(tmp, "file.txt"), tmp, "file.txt"},
+		{"same dir", tmp, tmp, "."},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := paths.PortableRelpath(tc.path, tc.base)
+			if got != tc.expected {
+				t.Errorf("got %q, want %q", got, tc.expected)
+			}
+		})
+	}
+}

internal/utils/sha/sha.go

@@ -0,0 +1,43 @@
+// Package sha provides short SHA formatting helpers.
+// Mirrors src/apm_cli/utils/short_sha.py.
+package sha
+
+import "strings"
+
+// sentinels are values that collapse to empty string.
+var sentinels = map[string]bool{
+	"cached":  true,
+	"unknown": true,
+}
+
+// FormatShortSHA returns an 8-char short SHA or "" for invalid inputs.
+// Rules:
+//   - nil / non-string -> ""
+//   - sentinel strings ("cached", "unknown") -> ""
+//   - shorter than 8 chars -> ""
+//   - contains non-hex characters -> ""
+//   - otherwise: first 8 chars
+func FormatShortSHA(value string) string {
+	candidate := strings.TrimSpace(value)
+	if candidate == "" {
+		return ""
+	}
+	if sentinels[strings.ToLower(candidate)] {
+		return ""
+	}
+	if len(candidate) < 8 {
+		return ""
+	}
+	for _, ch := range candidate {
+		if !isHex(ch) {
+			return ""
+		}
+	}
+	return candidate[:8]
+}
+
+func isHex(ch rune) bool {
+	return (ch >= '0' && ch <= '9') ||
+		(ch >= 'a' && ch <= 'f') ||
+		(ch >= 'A' && ch <= 'F')
+}