feat(sync): add extras sync engine — walk, symlink/copy, prune

This commit is contained in:
Willie
2026-03-04 12:16:32 +08:00
parent 035c9fe3f7
commit fbccdb9628
2 changed files with 681 additions and 0 deletions
+318
View File
@@ -0,0 +1,318 @@
package sync
import (
"fmt"
"os"
"path/filepath"
"sort"
"strings"
)
// ExtraResult holds the result of an extras sync operation.
type ExtraResult struct {
Synced int // Files synced (new + already correct)
Skipped int // Files skipped (local conflict, no --force)
Pruned int // Orphan files removed
Errors []string // Non-fatal error messages
}
// DiscoverExtraFiles recursively walks sourcePath and returns relative paths
// of all regular files. Directories named ".git" are skipped. Results are
// sorted for deterministic output.
func DiscoverExtraFiles(sourcePath string) ([]string, error) {
info, err := os.Stat(sourcePath)
if err != nil {
if os.IsNotExist(err) {
return nil, fmt.Errorf("extras source directory does not exist: %s", sourcePath)
}
return nil, fmt.Errorf("failed to stat extras source: %w", err)
}
if !info.IsDir() {
return nil, fmt.Errorf("extras source is not a directory: %s", sourcePath)
}
var files []string
err = filepath.Walk(sourcePath, func(path string, fi os.FileInfo, walkErr error) error {
if walkErr != nil {
return nil // skip inaccessible paths
}
if fi.IsDir() {
if fi.Name() == ".git" {
return filepath.SkipDir
}
return nil
}
rel, relErr := filepath.Rel(sourcePath, path)
if relErr != nil {
return nil
}
files = append(files, rel)
return nil
})
if err != nil {
return nil, fmt.Errorf("failed to walk extras source: %w", err)
}
sort.Strings(files)
return files, nil
}
// SyncExtra synchronises extra files from sourcePath into targetPath.
//
// Supported modes:
// - "merge" (default): per-file symlink from target to source
// - "copy": per-file copy
// - "symlink": entire directory symlink
//
// When dryRun is true the function counts what would happen but makes no
// filesystem changes.
func SyncExtra(sourcePath, targetPath, mode string, dryRun, force bool) (*ExtraResult, error) {
if mode == "" {
mode = "merge"
}
switch mode {
case "symlink":
return syncExtraSymlinkMode(sourcePath, targetPath, dryRun, force)
case "merge", "copy":
return syncExtraPerFile(sourcePath, targetPath, mode, dryRun, force)
default:
return nil, fmt.Errorf("unsupported extras sync mode: %q", mode)
}
}
// syncExtraSymlinkMode symlinks the entire source directory to the target path.
func syncExtraSymlinkMode(sourcePath, targetPath string, dryRun, force bool) (*ExtraResult, error) {
result := &ExtraResult{}
absSrc, err := filepath.Abs(sourcePath)
if err != nil {
return nil, fmt.Errorf("failed to resolve source path: %w", err)
}
// Check existing target
info, lstatErr := os.Lstat(targetPath)
if lstatErr == nil {
// Something exists at targetPath
if info.Mode()&os.ModeSymlink != 0 {
// Already a symlink — check if correct
dest, readErr := os.Readlink(targetPath)
if readErr == nil {
absDest, _ := filepath.Abs(dest)
if absDest == absSrc {
result.Synced = 1
return result, nil
}
}
// Wrong symlink
if !force {
result.Skipped = 1
return result, nil
}
if !dryRun {
os.Remove(targetPath)
}
} else {
// Real file/dir
if !force {
result.Skipped = 1
return result, nil
}
if !dryRun {
os.RemoveAll(targetPath)
}
}
}
if dryRun {
result.Synced = 1
return result, nil
}
if err := os.MkdirAll(filepath.Dir(targetPath), 0755); err != nil {
return nil, fmt.Errorf("failed to create parent directory: %w", err)
}
if err := os.Symlink(absSrc, targetPath); err != nil {
return nil, fmt.Errorf("failed to create directory symlink: %w", err)
}
result.Synced = 1
return result, nil
}
// syncExtraPerFile handles merge (symlink) and copy modes on a per-file basis.
func syncExtraPerFile(sourcePath, targetPath, mode string, dryRun, force bool) (*ExtraResult, error) {
result := &ExtraResult{}
files, err := DiscoverExtraFiles(sourcePath)
if err != nil {
return nil, err
}
absSrc, err := filepath.Abs(sourcePath)
if err != nil {
return nil, fmt.Errorf("failed to resolve source path: %w", err)
}
for _, rel := range files {
srcFile := filepath.Join(absSrc, rel)
tgtFile := filepath.Join(targetPath, rel)
synced, skipped, syncErr := syncOneExtraFile(srcFile, tgtFile, mode, dryRun, force)
if syncErr != nil {
result.Errors = append(result.Errors, fmt.Sprintf("%s: %v", rel, syncErr))
continue
}
result.Synced += synced
result.Skipped += skipped
}
// Prune orphans (only when not dry-run)
if !dryRun {
pruned, pruneErrors := pruneExtraOrphans(targetPath, absSrc, mode)
result.Pruned = pruned
result.Errors = append(result.Errors, pruneErrors...)
}
return result, nil
}
// syncOneExtraFile syncs a single file. Returns (synced, skipped, error).
func syncOneExtraFile(srcFile, tgtFile, mode string, dryRun, force bool) (int, int, error) {
// Ensure parent directory exists
if !dryRun {
if err := os.MkdirAll(filepath.Dir(tgtFile), 0755); err != nil {
return 0, 0, fmt.Errorf("failed to create parent dir: %w", err)
}
}
// Check if target already exists
info, lstatErr := os.Lstat(tgtFile)
if lstatErr == nil {
// Target exists
if mode == "merge" && info.Mode()&os.ModeSymlink != 0 {
// It's a symlink — check if it points to our source
dest, readErr := os.Readlink(tgtFile)
if readErr == nil {
absDest, _ := filepath.Abs(dest)
if absDest == srcFile {
// Already correct symlink
return 1, 0, nil
}
}
// Wrong symlink — treat as conflict
}
if mode == "copy" && info.Mode()&os.ModeSymlink == 0 && !info.IsDir() {
// Regular file exists in copy mode — check content match
// For simplicity, treat existing non-symlink file as conflict
}
// Conflict: target exists and is not our symlink
if !force {
return 0, 1, nil
}
// Force: remove and replace
if !dryRun {
if err := os.Remove(tgtFile); err != nil {
return 0, 0, fmt.Errorf("failed to remove conflicting file: %w", err)
}
}
}
if dryRun {
return 1, 0, nil
}
switch mode {
case "merge":
if err := os.Symlink(srcFile, tgtFile); err != nil {
return 0, 0, fmt.Errorf("failed to create symlink: %w", err)
}
case "copy":
if err := copyExtraFile(srcFile, tgtFile); err != nil {
return 0, 0, fmt.Errorf("failed to copy file: %w", err)
}
}
return 1, 0, nil
}
// pruneExtraOrphans walks the target directory and removes files that have no
// corresponding source. In merge mode only symlinks are pruned; user-created
// local files are preserved. Empty parent directories are cleaned up.
// Hidden files (names starting with ".") are skipped.
func pruneExtraOrphans(targetPath, absSourcePath, mode string) (pruned int, errors []string) {
// Collect paths to prune (walk first, delete after to avoid mutation during walk)
var toRemove []string
_ = filepath.Walk(targetPath, func(path string, info os.FileInfo, walkErr error) error {
if walkErr != nil {
return nil
}
if info.IsDir() {
if info.Name() == ".git" {
return filepath.SkipDir
}
return nil
}
// Skip hidden files
if strings.HasPrefix(info.Name(), ".") {
return nil
}
rel, relErr := filepath.Rel(targetPath, path)
if relErr != nil {
return nil
}
// Check if corresponding source file exists
srcFile := filepath.Join(absSourcePath, rel)
if _, statErr := os.Stat(srcFile); statErr == nil {
return nil // source exists, keep it
}
// Source doesn't exist — candidate for pruning
if mode == "merge" {
// In merge mode, only prune symlinks (don't delete user's local files)
if info.Mode()&os.ModeSymlink == 0 {
return nil
}
}
toRemove = append(toRemove, path)
return nil
})
for _, path := range toRemove {
if err := os.Remove(path); err != nil {
errors = append(errors, fmt.Sprintf("prune %s: %v", path, err))
continue
}
pruned++
// Clean empty parent directories up to targetPath
cleanEmptyParents(filepath.Dir(path), targetPath)
}
return pruned, errors
}
// cleanEmptyParents removes empty directories from dir up to (but not
// including) stopAt.
func cleanEmptyParents(dir, stopAt string) {
for dir != stopAt && dir != filepath.Dir(dir) {
entries, err := os.ReadDir(dir)
if err != nil || len(entries) > 0 {
break
}
os.Remove(dir)
dir = filepath.Dir(dir)
}
}
// copyExtraFile copies a single file from src to dst, preserving permissions.
func copyExtraFile(src, dst string) error {
return copyFile(src, dst)
}
+363
View File
@@ -0,0 +1,363 @@
package sync
import (
"os"
"path/filepath"
"testing"
)
// setupExtrasTest creates source and target directories under a temp root.
// It writes the given files (relative paths) into the source directory.
func setupExtrasTest(t *testing.T, files map[string]string) (srcDir, tgtDir string) {
t.Helper()
tmp := t.TempDir()
srcDir = filepath.Join(tmp, "extras-source")
tgtDir = filepath.Join(tmp, "extras-target")
os.MkdirAll(srcDir, 0755)
os.MkdirAll(tgtDir, 0755)
for rel, content := range files {
full := filepath.Join(srcDir, rel)
os.MkdirAll(filepath.Dir(full), 0755)
if err := os.WriteFile(full, []byte(content), 0644); err != nil {
t.Fatalf("write %s: %v", rel, err)
}
}
return
}
// --- DiscoverExtraFiles tests ---
func TestDiscoverExtraFiles(t *testing.T) {
src, _ := setupExtrasTest(t, map[string]string{
"flat.txt": "hello",
"nested/deep.md": "# deep",
".git/config": "should be skipped",
".git/hooks/pre-ci": "skip",
})
files, err := DiscoverExtraFiles(src)
if err != nil {
t.Fatal(err)
}
// Should find flat.txt and nested/deep.md, skip .git/**
if len(files) != 2 {
t.Fatalf("expected 2 files, got %d: %v", len(files), files)
}
expected := map[string]bool{
"flat.txt": true,
filepath.Join("nested", "deep.md"): true,
}
for _, f := range files {
if !expected[f] {
t.Errorf("unexpected file: %q", f)
}
}
}
// --- SyncExtra merge mode tests ---
func TestSyncExtra_MergeMode(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"rules.md": "# Rules",
"config.yml": "key: value",
})
result, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if result.Synced != 2 {
t.Errorf("expected 2 synced, got %d", result.Synced)
}
// Verify symlinks exist and point to source
for _, rel := range []string{"rules.md", "config.yml"} {
tgtPath := filepath.Join(tgt, rel)
info, lErr := os.Lstat(tgtPath)
if lErr != nil {
t.Errorf("expected file %s to exist: %v", rel, lErr)
continue
}
if info.Mode()&os.ModeSymlink == 0 {
t.Errorf("expected %s to be a symlink", rel)
}
dest, _ := os.Readlink(tgtPath)
absDest, _ := filepath.Abs(dest)
absSrc, _ := filepath.Abs(filepath.Join(src, rel))
if absDest != absSrc {
t.Errorf("symlink %s points to %s, expected %s", rel, absDest, absSrc)
}
}
}
// --- SyncExtra copy mode tests ---
func TestSyncExtra_CopyMode(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"readme.txt": "hello world",
})
result, err := SyncExtra(src, tgt, "copy", false, false)
if err != nil {
t.Fatal(err)
}
if result.Synced != 1 {
t.Errorf("expected 1 synced, got %d", result.Synced)
}
// Verify it's a real file, not a symlink
tgtPath := filepath.Join(tgt, "readme.txt")
info, err := os.Lstat(tgtPath)
if err != nil {
t.Fatal(err)
}
if info.Mode()&os.ModeSymlink != 0 {
t.Error("expected a real file, got a symlink")
}
content, err := os.ReadFile(tgtPath)
if err != nil {
t.Fatal(err)
}
if string(content) != "hello world" {
t.Errorf("expected 'hello world', got %q", string(content))
}
}
// --- Conflict tests ---
func TestSyncExtra_ConflictSkipped(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"conflict.md": "from source",
})
// Pre-create a local file at the target
os.WriteFile(filepath.Join(tgt, "conflict.md"), []byte("local version"), 0644)
result, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if result.Skipped != 1 {
t.Errorf("expected 1 skipped, got %d", result.Skipped)
}
if result.Synced != 0 {
t.Errorf("expected 0 synced, got %d", result.Synced)
}
// Original local content should be preserved
content, _ := os.ReadFile(filepath.Join(tgt, "conflict.md"))
if string(content) != "local version" {
t.Errorf("expected local content preserved, got %q", string(content))
}
}
func TestSyncExtra_ConflictForce(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"conflict.md": "from source",
})
// Pre-create a local file at the target
os.WriteFile(filepath.Join(tgt, "conflict.md"), []byte("local version"), 0644)
result, err := SyncExtra(src, tgt, "merge", false, true)
if err != nil {
t.Fatal(err)
}
if result.Synced != 1 {
t.Errorf("expected 1 synced (force replaced), got %d", result.Synced)
}
if result.Skipped != 0 {
t.Errorf("expected 0 skipped, got %d", result.Skipped)
}
// Should now be a symlink
info, _ := os.Lstat(filepath.Join(tgt, "conflict.md"))
if info.Mode()&os.ModeSymlink == 0 {
t.Error("expected symlink after force replace")
}
}
// --- Nested directories test ---
func TestSyncExtra_NestedDirectories(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
filepath.Join("a", "b", "deep.md"): "deep content",
})
result, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if result.Synced != 1 {
t.Errorf("expected 1 synced, got %d", result.Synced)
}
deepTarget := filepath.Join(tgt, "a", "b", "deep.md")
info, err := os.Lstat(deepTarget)
if err != nil {
t.Fatalf("expected nested file to exist: %v", err)
}
if info.Mode()&os.ModeSymlink == 0 {
t.Error("expected symlink for nested file")
}
}
// --- Empty source test ---
func TestSyncExtra_EmptySource(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{})
result, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if result.Synced != 0 {
t.Errorf("expected 0 synced for empty source, got %d", result.Synced)
}
}
// --- Source does not exist test ---
func TestSyncExtra_SourceNotExist(t *testing.T) {
tgt := t.TempDir()
_, err := SyncExtra("/nonexistent/extras/source", tgt, "merge", false, false)
if err == nil {
t.Error("expected error for non-existent source")
}
}
// --- Dry run test ---
func TestSyncExtra_DryRun(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"alpha.md": "a",
"beta.md": "b",
})
result, err := SyncExtra(src, tgt, "merge", true, false)
if err != nil {
t.Fatal(err)
}
if result.Synced != 2 {
t.Errorf("expected 2 synced in dry-run count, got %d", result.Synced)
}
// Verify no files were actually created
entries, _ := os.ReadDir(tgt)
if len(entries) != 0 {
t.Errorf("expected empty target in dry-run, got %d entries", len(entries))
}
}
// --- Idempotent test ---
func TestSyncExtra_Idempotent(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"stable.md": "content",
})
// First sync
r1, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if r1.Synced != 1 {
t.Fatalf("first sync: expected 1 synced, got %d", r1.Synced)
}
// Second sync — should still report synced (already correct)
r2, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if r2.Synced != 1 {
t.Errorf("second sync: expected 1 synced (idempotent), got %d", r2.Synced)
}
if r2.Skipped != 0 {
t.Errorf("second sync: expected 0 skipped, got %d", r2.Skipped)
}
}
// --- Prune orphans test ---
func TestSyncExtra_PrunesOrphans(t *testing.T) {
src, tgt := setupExtrasTest(t, map[string]string{
"keep.md": "keep this",
"remove.md": "will be removed from source",
})
// First sync both files
_, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
// Remove "remove.md" from source
os.Remove(filepath.Join(src, "remove.md"))
// Sync again — should prune orphan
result, err := SyncExtra(src, tgt, "merge", false, false)
if err != nil {
t.Fatal(err)
}
if result.Pruned != 1 {
t.Errorf("expected 1 pruned, got %d", result.Pruned)
}
// Verify orphan was removed
if _, err := os.Lstat(filepath.Join(tgt, "remove.md")); !os.IsNotExist(err) {
t.Error("expected orphan symlink to be removed")
}
// Verify kept file still exists
if _, err := os.Lstat(filepath.Join(tgt, "keep.md")); err != nil {
t.Error("expected keep.md to still exist")
}
}
// --- Symlink mode (entire directory) test ---
func TestSyncExtra_SymlinkMode(t *testing.T) {
src, _ := setupExtrasTest(t, map[string]string{
"file.txt": "content",
})
tmp := t.TempDir()
tgt := filepath.Join(tmp, "extras-link")
result, err := SyncExtra(src, tgt, "symlink", false, false)
if err != nil {
t.Fatal(err)
}
if result.Synced != 1 {
t.Errorf("expected 1 synced, got %d", result.Synced)
}
// Verify target is a symlink to the source directory
info, err := os.Lstat(tgt)
if err != nil {
t.Fatal(err)
}
if info.Mode()&os.ModeSymlink == 0 {
t.Error("expected target to be a symlink")
}
dest, _ := os.Readlink(tgt)
absDest, _ := filepath.Abs(dest)
absSrc, _ := filepath.Abs(src)
if absDest != absSrc {
t.Errorf("symlink points to %s, expected %s", absDest, absSrc)
}
// Verify files are accessible through the symlink
content, err := os.ReadFile(filepath.Join(tgt, "file.txt"))
if err != nil {
t.Fatal(err)
}
if string(content) != "content" {
t.Errorf("expected 'content', got %q", string(content))
}
}