feat: skills internal download and lock

Author: KartikJha

internal/ai/skills/download.go

@@ -20,7 +20,7 @@ const (
 	agentSkillsAPI    = "https://api.github.com/repos/auth0/agent-skills/commits/"
 	pluginSubtreePath = "plugins/auth0"
 	skillsHTTPTimeout = 60 * time.Second
-	maxSkillsDownload = 100 * 1024 * 1024 // 100 MB
+	maxSkillsDownload = 100 * 1024 * 1024 // 100 MB.
 )
 
 var skillsHTTPClient = &http.Client{Timeout: skillsHTTPTimeout}
@@ -192,9 +192,7 @@ func downloadViaZip(targetDir, ref string) (string, error) {
 	return fetchCommitSHA(ref)
 }
 
-// extractTarGzSubtree reads a .tar.gz from r and copies entries whose name starts with
-// prefix into destDir (stripping the prefix from the output path).
-// extractEntry writes a single archive entry to destDir. isDir and mode describe the entry;
+// ExtractEntry writes a single archive entry to destDir. IsDir and mode describe the entry;
 // open returns a reader for its content (ignored when isDir is true). The name is checked
 // against prefix and any path-traversal attempt is rejected.
 func extractEntry(name string, isDir bool, mode os.FileMode, open func() (io.ReadCloser, error), prefix, destDir string) error {
@@ -260,7 +258,7 @@ func extractTarGzSubtree(r io.Reader, prefix, destDir string) error {
 // extractZipSubtree opens the ZIP at zipPath (with known size) and copies entries whose
 // name starts with prefix into destDir (stripping the prefix).
 func extractZipSubtree(zipPath string, size int64, prefix, destDir string) error {
-	// zip.NewReader needs an io.ReaderAt, so we re-open the file.
+	// Zip.NewReader needs an io.ReaderAt, so we re-open the file.
 	f, err := os.Open(zipPath)
 	if err != nil {
 		return err

internal/ai/skills/download_test.go

@@ -80,7 +80,7 @@ func assertFileContent(t *testing.T, path, want string) {
 	assert.Equal(t, want, string(data))
 }
 
-// --- extractEntry ---
+// --- extractEntry ---.
 
 func TestExtractEntry(t *testing.T) {
 	open := func(content string) func() (io.ReadCloser, error) {
@@ -137,7 +137,7 @@ func TestExtractEntry(t *testing.T) {
 	})
 }
 
-// --- extractTarGzSubtree ---
+// --- extractTarGzSubtree ---.
 
 func TestExtractTarGzSubtree(t *testing.T) {
 	const prefix = "repo-main/plugins/auth0/"
@@ -171,7 +171,7 @@ func TestExtractTarGzSubtree(t *testing.T) {
 	})
 }
 
-// --- extractZipSubtree ---
+// --- extractZipSubtree ---.
 
 func TestExtractZipSubtree(t *testing.T) {
 	const prefix = "repo-main/plugins/auth0/"
@@ -203,7 +203,7 @@ func TestExtractZipSubtree(t *testing.T) {
 	})
 }
 
-// --- mergeDir ---
+// --- mergeDir ---.
 
 func TestMergeDir(t *testing.T) {
 	t.Run("copies flat files", func(t *testing.T) {
@@ -230,7 +230,7 @@ func TestMergeDir(t *testing.T) {
 	})
 }
 
-// --- fetchToTempFile ---
+// --- fetchToTempFile ---.
 
 func TestFetchToTempFile(t *testing.T) {
 	t.Run("returns open seeked file and byte count on 200", func(t *testing.T) {
@@ -265,7 +265,7 @@ func TestFetchToTempFile(t *testing.T) {
 	})
 }
 
-// --- fetchCommitSHA ---
+// --- fetchCommitSHA ---.
 
 func TestFetchCommitSHA(t *testing.T) {
 	shaResponse := func(sha string) roundTripFunc {

internal/ai/skills/lock.go

@@ -8,8 +8,8 @@ import (
 	"time"
 )
 
-// SkillsLock records the installed state of the auth0 agent-skills plugin.
-type SkillsLock struct {
+// Lock records the installed state of the auth0 agent-skills plugin.
+type Lock struct {
 	Repo          string    `json:"repo"`
 	Ref           string    `json:"ref"`
 	CommitSHA     string    `json:"commitSHA"`
@@ -18,27 +18,27 @@ type SkillsLock struct {
 	LastCheckedAt time.Time `json:"lastCheckedAt"`
 	Skills        []string  `json:"skills"`
 	Agents        []string  `json:"agents"`
-	Scope         string    `json:"scope"` // "global" or "local"
+	Scope         string    `json:"scope"` // "global" or "local".
 }
 
 // ReadLock reads the skills-lock.json at path. Returns nil, nil when the file does not exist.
-func ReadLock(path string) (*SkillsLock, error) {
+func ReadLock(path string) (*Lock, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
 			return nil, nil
 		}
 		return nil, err
 	}
-	var lock SkillsLock
+	var lock Lock
 	if err := json.Unmarshal(data, &lock); err != nil {
 		return nil, err
 	}
 	return &lock, nil
 }
 
 // WriteLock serialises lock as JSON and writes it to path, creating parent directories as needed.
-func WriteLock(path string, lock *SkillsLock) error {
+func WriteLock(path string, lock *Lock) error {
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
 		return err
 	}

internal/ai/skills/lock_test.go

@@ -74,7 +74,7 @@ func TestWriteLock(t *testing.T) {
 		dir := t.TempDir()
 		path := filepath.Join(dir, "skills-lock.json")
 
-		lock := &SkillsLock{
+		lock := &Lock{
 			Repo:          "https://github.com/auth0/agent-skills.git",
 			Ref:           "main",
 			CommitSHA:     "deadbeef",
@@ -102,7 +102,7 @@ func TestWriteLock(t *testing.T) {
 		dir := t.TempDir()
 		path := filepath.Join(dir, "nested", "deep", "skills-lock.json")
 
-		require.NoError(t, WriteLock(path, &SkillsLock{Scope: "global"}))
+		require.NoError(t, WriteLock(path, &Lock{Scope: "global"}))
 
 		got, err := ReadLock(path)
 		require.NoError(t, err)
@@ -114,8 +114,8 @@ func TestWriteLock(t *testing.T) {
 		dir := t.TempDir()
 		path := filepath.Join(dir, "skills-lock.json")
 
-		require.NoError(t, WriteLock(path, &SkillsLock{CommitSHA: "first"}))
-		require.NoError(t, WriteLock(path, &SkillsLock{CommitSHA: "second"}))
+		require.NoError(t, WriteLock(path, &Lock{CommitSHA: "first"}))
+		require.NoError(t, WriteLock(path, &Lock{CommitSHA: "second"}))
 
 		got, err := ReadLock(path)
 		require.NoError(t, err)
@@ -126,7 +126,7 @@ func TestWriteLock(t *testing.T) {
 		dir := t.TempDir()
 		path := filepath.Join(dir, "skills-lock.json")
 
-		original := &SkillsLock{
+		original := &Lock{
 			Repo:          "https://github.com/auth0/agent-skills.git",
 			Ref:           "v1.2.3",
 			CommitSHA:     "cafebabe",