build: add generic github repo fetching utility

* add leaflet lexicons

* add prod build flag

README.md

···
 ### First Steps
 
 For a comprehensive walkthrough including task management, time tracking, notes, and media tracking, see the [Quickstart Guide](website/docs/Quickstart.md).
+
+## Development
+
+Noteleaf uses [Task](https://taskfile.dev) for build automation. Development builds include additional tooling commands not available in production builds.
+
+### Building
+
+```sh
+# Production build
+task build
+
+# Development build (with version info and dev tools)
+task build:dev
+
+# Run tests
+task test
+task cov # ...with coverage
+```
+
+### Development Tools
+
+Dev builds (`task build:dev`) include a `tools` subcommand with maintenance utilities:
+
+**Documentation Generation:**
+
+```sh
+# Generate Docusaurus documentation
+noteleaf tools docgen --format docusaurus --out website/docs/manual
+
+# Generate man pages
+noteleaf tools docgen --format man --out docs/manual
+```
+
+**Data Synchronization:**
+
+```sh
+# Fetch Leaflet lexicons from GitHub
+noteleaf tools fetch lexicons
+
+# Fetch from a specific commit
+noteleaf tools fetch lexicons --sha abc123def
+
+# Generic GitHub repository archive fetcher
+noteleaf tools fetch gh-repo \
+  --repo owner/repo \
+  --path schemas/ \
+  --output local/schemas/
+```
+
+Production builds (`task build:rc`, `task build:prod`) use the `-tags prod` flag to exclude dev tools.

Taskfile.yml

···
       - echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}}"
 
   build:dev:
-    desc: Build binary with dev version (includes git commit hash)
+    desc: Build binary with dev version (includes git commit hash and dev tools)
     vars:
       VERSION: "{{.GIT_DESCRIBE}}"
       LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.Commit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
···
       - 'echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}} (version: {{.VERSION}})"'
 
   build:rc:
-    desc: Build release candidate binary (requires git tag with -rc suffix)
+    desc: Build release candidate binary (requires git tag with -rc suffix, excludes dev tools)
     vars:
       VERSION: "{{.GIT_TAG}}"
       LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.Commit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
···
         msg: "Git tag must contain '-rc' for release candidate builds (e.g., v1.0.0-rc1)"
     cmds:
       - mkdir -p {{.BUILD_DIR}}
-      - go build -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
+      - go build -tags prod -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
       - 'echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}} (version: {{.VERSION}})"'
 
   build:prod:
-    desc: Build production binary (requires clean semver git tag)
+    desc: Build production binary (requires clean semver git tag, excludes dev tools)
     vars:
       VERSION: "{{.GIT_TAG}}"
       LDFLAGS: "-X {{.VERSION_PKG}}.Version={{.VERSION}} -X {{.VERSION_PKG}}.Commit={{.GIT_COMMIT}} -X {{.VERSION_PKG}}.BuildDate={{.BUILD_DATE}}"
···
         msg: "Working directory must be clean (no uncommitted changes) for production builds"
     cmds:
       - mkdir -p {{.BUILD_DIR}}
-      - go build -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
+      - go build -tags prod -ldflags "{{.LDFLAGS}}" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.CMD_DIR}}
       - 'echo "Built {{.BUILD_DIR}}/{{.BINARY_NAME}} (version: {{.VERSION}})"'
 
   clean:

cmd/main.go

···
 	"github.com/stormlightlabs/noteleaf/internal/ui"
 	"github.com/stormlightlabs/noteleaf/internal/utils"
 	"github.com/stormlightlabs/noteleaf/internal/version"
-	"github.com/stormlightlabs/noteleaf/tools"
 )
 
 var (
···
 		root.AddCommand(cmd)
 	}
 
-	root.AddCommand(tools.NewDocGenCommand(root))
+	registerTools(root)
 
 	opts := []fang.Option{
 		fang.WithVersion(version.String()),

cmd/tools_dev.go

···
+//go:build !prod
+
+package main
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/stormlightlabs/noteleaf/tools"
+)
+
+// registerTools adds development tools to the root command
+func registerTools(root *cobra.Command) {
+	root.AddCommand(tools.NewToolsCommand(root))
+}

cmd/tools_prod.go

···
+//go:build prod
+
+package main
+
+import "github.com/spf13/cobra"
+
+// registerTools is a no-op in production builds
+func registerTools(*cobra.Command) {}

tools/docgen.go

···
+//go:build !prod
+
 package tools
 
 import (
···
 	}
 
 	for _, cmd := range root.Commands() {
-		if cmd.Name() == path[0] || contains(cmd.Aliases, path[0]) {
+		if cmd.Name() == path[0] || slices.Contains(cmd.Aliases, path[0]) {
 			if len(path) == 1 {
 				return cmd
 			}
···
 
 	return nil
 }
-
-// contains checks if a string is in a slice
-func contains(slice []string, str string) bool {
-	return slices.Contains(slice, str)
-}

tools/fetch.go

···
+//go:build !prod
+
+package tools
+
+import "github.com/spf13/cobra"
+
+// NewFetchCommand creates a parent command for fetching remote resources
+func NewFetchCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "fetch",
+		Short: "Fetch remote resources",
+		Long: `Fetch and synchronize remote resources from GitHub repositories.
+
+Includes commands for fetching lexicons, schemas, and other data files.`,
+	}
+
+	cmd.AddCommand(NewGHRepoCommand())
+	cmd.AddCommand(NewLexiconsCommand())
+
+	return cmd
+}

tools/lexicon_fetch.go

···
+//go:build !prod
+
+package tools
+
+import (
+	"context"
+
+	"github.com/spf13/cobra"
+)
+
+// NewLexiconsCommand creates a command for fetching Leaflet lexicons
+func NewLexiconsCommand() *cobra.Command {
+	var sha string
+	var output string
+
+	cmd := &cobra.Command{
+		Use:   "lexicons",
+		Short: "Fetch Leaflet lexicons from GitHub",
+		Long: `Fetches Leaflet lexicons from the hyperlink-academy/leaflet repository.
+
+This is a convenience wrapper around gh-repo with pre-configured defaults
+for the Leaflet lexicon repository.`,
+		Example: `  # Fetch latest lexicons
+  noteleaf tools fetch lexicons
+
+  # Fetch from a specific commit
+  noteleaf tools fetch lexicons --sha abc123def
+
+  # Fetch to a custom directory
+  noteleaf tools fetch lexicons --output ./tmp/lexicons`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			config := ArchiveConfig{
+				Repo:       "hyperlink-academy/leaflet",
+				Path:       "lexicons/pub/leaflet/",
+				Output:     output,
+				SHA:        sha,
+				FormatJSON: true,
+			}
+
+			ctx := cmd.Context()
+			if ctx == nil {
+				ctx = context.Background()
+			}
+
+			return fetchAndExtractArchive(ctx, config, cmd.OutOrStdout())
+		},
+	}
+	cmd.Flags().StringVar(&sha, "sha", "", "Specific commit SHA (default: latest)")
+	cmd.Flags().StringVar(&output, "output", "lexdocs/leaflet/", "Output directory for lexicons")
+	return cmd
+}

tools/registry.go

···
+//go:build !prod
+
+package tools
+
+import "github.com/spf13/cobra"
+
+// NewToolsCommand creates a parent command for all development tools
+func NewToolsCommand(root *cobra.Command) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "tools",
+		Short: "Development and maintenance tools",
+		Long: `Development tools for documentation generation, data synchronization,
+and maintenance tasks. These commands are only available in dev builds.`,
+	}
+	cmd.AddCommand(NewDocGenCommand(root))
+	cmd.AddCommand(NewFetchCommand())
+
+	return cmd
+}

tools/repo_archive.go

···
+//go:build !prod
+
+package tools
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// GitHubCommit represents a GitHub API commit response
+type GitHubCommit struct {
+	SHA    string `json:"sha"`
+	Commit struct {
+		Message string `json:"message"`
+	} `json:"commit"`
+}
+
+// ArchiveConfig contains configuration for fetching and extracting archives
+type ArchiveConfig struct {
+	Repo       string
+	Path       string
+	Output     string
+	SHA        string
+	FormatJSON bool
+}
+
+// NewGHRepoCommand creates a command for fetching GitHub repository archives
+func NewGHRepoCommand() *cobra.Command {
+	var config ArchiveConfig
+
+	cmd := &cobra.Command{
+		Use:   "gh-repo",
+		Short: "Fetch and extract files from a GitHub repository archive",
+		Long: `Fetches a GitHub repository archive (tarball), extracts specific paths,
+and optionally formats JSON files using Go's standard library.
+
+This is useful for syncing lexicons, schemas, or other data files from GitHub repositories.`,
+		Example: `  # Fetch lexicons from a specific path
+  noteleaf tools fetch gh-repo \
+    --repo hyperlink-academy/leaflet \
+    --path lexicons/pub/leaflet/ \
+    --output lexdocs/leaflet/
+
+  # Fetch from a specific commit
+  noteleaf tools fetch gh-repo \
+    --repo owner/repo \
+    --path schemas/ \
+    --output local/schemas/ \
+    --sha abc123def`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if config.Repo == "" {
+				return fmt.Errorf("--repo is required")
+			}
+			if config.Path == "" {
+				return fmt.Errorf("--path is required")
+			}
+			if config.Output == "" {
+				return fmt.Errorf("--output is required")
+			}
+
+			ctx := cmd.Context()
+			if ctx == nil {
+				ctx = context.Background()
+			}
+
+			return fetchAndExtractArchive(ctx, config, cmd.OutOrStdout())
+		},
+	}
+
+	cmd.Flags().StringVar(&config.Repo, "repo", "", "GitHub repository (owner/name)")
+	cmd.Flags().StringVar(&config.Path, "path", "", "Path within repository to extract")
+	cmd.Flags().StringVar(&config.Output, "output", "", "Output directory for extracted files")
+	cmd.Flags().StringVar(&config.SHA, "sha", "", "Specific commit SHA (default: latest)")
+	cmd.Flags().BoolVar(&config.FormatJSON, "format-json", true, "Format JSON files with indentation")
+	return cmd
+}
+
+// fetchAndExtractArchive fetches a GitHub archive and extracts specific paths
+func fetchAndExtractArchive(ctx context.Context, config ArchiveConfig, out io.Writer) error {
+	sha := config.SHA
+	if sha == "" {
+		var err error
+		sha, err = getLatestCommit(ctx, config.Repo, config.Path)
+		if err != nil {
+			return fmt.Errorf("failed to get latest commit: %w", err)
+		}
+		fmt.Fprintf(out, "Latest commit: %s\n", sha)
+	}
+
+	tmpDir, err := os.MkdirTemp("", "repo-archive-*")
+	if err != nil {
+		return fmt.Errorf("failed to create temp directory: %w", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	fmt.Fprintf(out, "Fetching archive for %s@%s\n", config.Repo, sha[:7])
+	if err := downloadAndExtract(ctx, config.Repo, sha, config.Path, tmpDir, config.FormatJSON, out); err != nil {
+		return fmt.Errorf("failed to download and extract: %w", err)
+	}
+
+	fmt.Fprintf(out, "Writing README with source information\n")
+	readme := fmt.Sprintf("Source: https://github.com/%s/tree/%s/%s\n", config.Repo, sha, config.Path)
+	if err := os.WriteFile(filepath.Join(tmpDir, "README.md"), []byte(readme), 0o644); err != nil {
+		return fmt.Errorf("failed to write README: %w", err)
+	}
+
+	fmt.Fprintf(out, "Moving extracted files to %s\n", config.Output)
+	if err := os.RemoveAll(config.Output); err != nil {
+		return fmt.Errorf("failed to remove existing output directory: %w", err)
+	}
+	if err := os.Rename(tmpDir, config.Output); err != nil {
+		return fmt.Errorf("failed to move files to output directory: %w", err)
+	}
+
+	fmt.Fprintf(out, "Successfully extracted archive to %s\n", config.Output)
+	return nil
+}
+
+// getLatestCommit fetches the latest commit SHA for a given repository and path
+func getLatestCommit(ctx context.Context, repo, path string) (string, error) {
+	url := fmt.Sprintf("https://api.github.com/repos/%s/commits?path=%s&per_page=1", repo, path)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return "", err
+	}
+
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("GitHub API returned status %d", resp.StatusCode)
+	}
+
+	var commits []GitHubCommit
+	if err := json.NewDecoder(resp.Body).Decode(&commits); err != nil {
+		return "", fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	if len(commits) == 0 {
+		return "", fmt.Errorf("no commits found for path %s", path)
+	}
+
+	return commits[0].SHA, nil
+}
+
+// downloadAndExtract downloads a GitHub archive and extracts files from a specific path
+func downloadAndExtract(ctx context.Context, repo, sha, extractPath, outputDir string, formatJSON bool, out io.Writer) error {
+	url := fmt.Sprintf("https://github.com/%s/archive/%s.tar.gz", repo, sha)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return err
+	}
+
+	client := &http.Client{Timeout: 5 * time.Minute}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("failed to download archive: status %d", resp.StatusCode)
+	}
+
+	gzr, err := gzip.NewReader(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to create gzip reader: %w", err)
+	}
+	defer gzr.Close()
+
+	tr := tar.NewReader(gzr)
+
+	repoName := strings.Split(repo, "/")[1]
+	prefix := fmt.Sprintf("%s-%s/%s", repoName, sha, extractPath)
+
+	fmt.Fprintf(out, "Extracting files from %s\n", prefix)
+
+	fileCount := 0
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return fmt.Errorf("failed to read tar header: %w", err)
+		}
+
+		if header.Typeflag != tar.TypeReg {
+			continue
+		}
+
+		if !strings.HasPrefix(header.Name, prefix) {
+			continue
+		}
+
+		if !strings.HasSuffix(header.Name, ".json") {
+			continue
+		}
+
+		relativePath := strings.TrimPrefix(header.Name, prefix)
+		outputPath := filepath.Join(outputDir, relativePath)
+
+		if err := os.MkdirAll(filepath.Dir(outputPath), 0o755); err != nil {
+			return fmt.Errorf("failed to create directory for %s: %w", outputPath, err)
+		}
+
+		data, err := io.ReadAll(tr)
+		if err != nil {
+			return fmt.Errorf("failed to read file %s: %w", header.Name, err)
+		}
+
+		if formatJSON {
+			var jsonData any
+			if err := json.Unmarshal(data, &jsonData); err != nil {
+				return fmt.Errorf("failed to parse JSON in %s: %w", header.Name, err)
+			}
+
+			formattedData, err := json.MarshalIndent(jsonData, "", "  ")
+			if err != nil {
+				return fmt.Errorf("failed to format JSON in %s: %w", header.Name, err)
+			}
+			data = append(formattedData, '\n')
+		}
+
+		if err := os.WriteFile(outputPath, data, 0o644); err != nil {
+			return fmt.Errorf("failed to write file %s: %w", outputPath, err)
+		}
+
+		fileCount++
+	}
+
+	fmt.Fprintf(out, "Extracted %d files\n", fileCount)
+	return nil
+}