From 3a920610f2b59eca47f79ca7e374696e4f4743a0 Mon Sep 17 00:00:00 2001 From: Willie Date: Mon, 9 Feb 2026 22:46:36 +0800 Subject: [PATCH] feat: add trash (soft-delete) for uninstall with 7-day retention Replace permanent deletion with soft-delete: uninstall now moves skills to a trash directory instead of using os.RemoveAll. Skills are retained for 7 days and automatically cleaned up during sync/uninstall operations. - Add internal/trash package (MoveToTrash, List, Cleanup, Restore, FindByName) - Add `skillshare trash list` and `skillshare trash restore ` commands - Show reinstall hint from metadata when uninstalling remote skills - Add trash status to `skillshare doctor` output - Opportunistic cleanup of expired items during sync and uninstall - Support both global (~/.config/skillshare/trash/) and project (.skillshare/trash/) modes - 10 unit tests + 10 integration tests - Update docs: uninstall, trash, doctor, FAQ, file-structure, sync, daily-workflow --- cmd/skillshare/doctor.go | 48 ++++ cmd/skillshare/main.go | 3 + cmd/skillshare/sync.go | 8 + cmd/skillshare/sync_project.go | 8 + cmd/skillshare/trash.go | 174 ++++++++++++ cmd/skillshare/uninstall.go | 29 +- cmd/skillshare/uninstall_project.go | 24 +- internal/trash/trash.go | 283 ++++++++++++++++++++ internal/trash/trash_test.go | 228 ++++++++++++++++ tests/integration/trash_test.go | 119 ++++++++ tests/integration/uninstall_test.go | 2 +- tests/integration/uninstall_trash_test.go | 120 +++++++++ website/docs/commands/doctor.md | 2 + website/docs/commands/sync.md | 4 + website/docs/commands/trash.md | 78 ++++++ website/docs/commands/uninstall.md | 32 ++- website/docs/concepts/source-and-targets.md | 20 ++ website/docs/reference/file-structure.md | 48 +++- website/docs/troubleshooting/faq.md | 46 ++++ website/docs/workflows/daily-workflow.md | 8 +- website/sidebars.ts | 1 + 21 files changed, 1264 insertions(+), 21 deletions(-) create mode 100644 cmd/skillshare/trash.go create mode 100644 internal/trash/trash.go create mode 100644 internal/trash/trash_test.go create mode 100644 tests/integration/trash_test.go create mode 100644 tests/integration/uninstall_trash_test.go create mode 100644 website/docs/commands/trash.md diff --git a/cmd/skillshare/doctor.go b/cmd/skillshare/doctor.go index 2e85ddbe4..057b81ca2 100644 --- a/cmd/skillshare/doctor.go +++ b/cmd/skillshare/doctor.go @@ -14,6 +14,7 @@ import ( "skillshare/internal/config" "skillshare/internal/sync" + "skillshare/internal/trash" "skillshare/internal/ui" "skillshare/internal/utils" ) @@ -75,6 +76,9 @@ func cmdDoctor(args []string) error { // Check backup status checkBackupStatus() + // Check trash status + checkTrashStatus() + // Check CLI and skill version checkVersionDoctor(cfg) @@ -443,6 +447,50 @@ func checkBackupStatus() { } } +// checkTrashStatus shows trash directory status +func checkTrashStatus() { + trashBase := trash.TrashDir() + if trashBase == "" { + return + } + + items := trash.List(trashBase) + if len(items) == 0 { + ui.Info("Trash: empty") + return + } + + totalSize := trash.TotalSize(trashBase) + sizeStr := formatBytes(totalSize) + + // Find oldest item age + oldest := items[len(items)-1] // List is sorted newest-first + age := time.Since(oldest.Date) + days := int(age.Hours() / 24) + + if days > 0 { + ui.Info("Trash: %d item(s) (%s), oldest %d day(s)", len(items), sizeStr, days) + } else { + ui.Info("Trash: %d item(s) (%s), oldest <1 day", len(items), sizeStr) + } +} + +// formatBytes formats bytes into a human-readable string. +func formatBytes(b int64) string { + const ( + kb = 1024 + mb = 1024 * kb + ) + switch { + case b >= mb: + return fmt.Sprintf("%.1f MB", float64(b)/float64(mb)) + case b >= kb: + return fmt.Sprintf("%.1f KB", float64(b)/float64(kb)) + default: + return fmt.Sprintf("%d B", b) + } +} + // checkVersionDoctor checks CLI and skill versions func checkVersionDoctor(cfg *config.Config) { ui.Header("Version") diff --git a/cmd/skillshare/main.go b/cmd/skillshare/main.go index 5dd4305d3..e73335613 100644 --- a/cmd/skillshare/main.go +++ b/cmd/skillshare/main.go @@ -33,6 +33,7 @@ var commands = map[string]func([]string) error{ "check": cmdCheck, "new": cmdNew, "search": cmdSearch, + "trash": cmdTrash, "ui": cmdUI, } @@ -160,6 +161,8 @@ func printUsage() { cmd("collect", "[target]", "Collect local skills from target(s) to source") cmd("backup", "", "Create backup of target(s)") cmd("restore", "", "Restore target from latest backup") + cmd("trash", "list", "List trashed skills") + cmd("trash", "restore ", "Restore a skill from trash") fmt.Println() // Git Remote diff --git a/cmd/skillshare/sync.go b/cmd/skillshare/sync.go index c84075973..71bea186d 100644 --- a/cmd/skillshare/sync.go +++ b/cmd/skillshare/sync.go @@ -7,6 +7,7 @@ import ( "skillshare/internal/backup" "skillshare/internal/config" "skillshare/internal/sync" + "skillshare/internal/trash" "skillshare/internal/ui" "skillshare/internal/utils" ) @@ -98,6 +99,13 @@ func cmdSync(args []string) error { return fmt.Errorf("some targets failed to sync") } + // Opportunistic cleanup of expired trash items + if !dryRun { + if n, _ := trash.Cleanup(trash.TrashDir(), 0); n > 0 { + ui.Info("Cleaned up %d expired trash item(s)", n) + } + } + return nil } diff --git a/cmd/skillshare/sync_project.go b/cmd/skillshare/sync_project.go index 7fe834692..7d95163cd 100644 --- a/cmd/skillshare/sync_project.go +++ b/cmd/skillshare/sync_project.go @@ -6,6 +6,7 @@ import ( "skillshare/internal/config" "skillshare/internal/sync" + "skillshare/internal/trash" "skillshare/internal/ui" ) @@ -91,6 +92,13 @@ func cmdSyncProject(args []string, root string) error { return fmt.Errorf("some targets failed to sync") } + // Opportunistic cleanup of expired trash items + if !dryRun { + if n, _ := trash.Cleanup(trash.ProjectTrashDir(root), 0); n > 0 { + ui.Info("Cleaned up %d expired trash item(s)", n) + } + } + return nil } diff --git a/cmd/skillshare/trash.go b/cmd/skillshare/trash.go new file mode 100644 index 000000000..6b6087953 --- /dev/null +++ b/cmd/skillshare/trash.go @@ -0,0 +1,174 @@ +package main + +import ( + "fmt" + "os" + "strings" + "time" + + "skillshare/internal/config" + "skillshare/internal/trash" + "skillshare/internal/ui" +) + +func cmdTrash(args []string) error { + mode, rest, err := parseModeArgs(args) + if err != nil { + return err + } + + cwd, err := os.Getwd() + if err != nil { + return fmt.Errorf("cannot determine working directory: %w", err) + } + + if mode == modeAuto { + if projectConfigExists(cwd) { + mode = modeProject + } else { + mode = modeGlobal + } + } + + applyModeLabel(mode) + + if len(rest) == 0 { + printTrashHelp() + return nil + } + + sub := rest[0] + subArgs := rest[1:] + + switch sub { + case "list", "ls": + return trashList(mode, cwd) + case "restore": + return trashRestore(mode, cwd, subArgs) + case "--help", "-h", "help": + printTrashHelp() + return nil + default: + printTrashHelp() + return fmt.Errorf("unknown subcommand: %s", sub) + } +} + +func trashList(mode runMode, cwd string) error { + trashBase := resolveTrashBase(mode, cwd) + items := trash.List(trashBase) + + if len(items) == 0 { + ui.Info("Trash is empty") + return nil + } + + ui.Header("Trash") + for _, item := range items { + age := time.Since(item.Date) + ageStr := formatAge(age) + sizeStr := formatBytes(item.Size) + ui.Info(" %s (%s, %s ago)", item.Name, sizeStr, ageStr) + } + + totalSize := trash.TotalSize(trashBase) + fmt.Println() + ui.Info("%d item(s), %s total", len(items), formatBytes(totalSize)) + ui.Info("Items are automatically cleaned up after 7 days") + + return nil +} + +func trashRestore(mode runMode, cwd string, args []string) error { + var name string + for _, arg := range args { + switch { + case arg == "--help" || arg == "-h": + printTrashHelp() + return nil + case strings.HasPrefix(arg, "-"): + return fmt.Errorf("unknown option: %s", arg) + default: + if name != "" { + return fmt.Errorf("unexpected argument: %s", arg) + } + name = arg + } + } + + if name == "" { + printTrashHelp() + return fmt.Errorf("skill name is required") + } + + trashBase := resolveTrashBase(mode, cwd) + entry := trash.FindByName(trashBase, name) + if entry == nil { + return fmt.Errorf("'%s' not found in trash", name) + } + + destDir, err := resolveSourceDir(mode, cwd) + if err != nil { + return err + } + + if err := trash.Restore(entry, destDir); err != nil { + return err + } + + ui.Success("Restored: %s", name) + age := time.Since(entry.Date) + ui.Info("Trashed %s ago, now back in %s", formatAge(age), destDir) + ui.Info("Run 'skillshare sync' to update targets") + + return nil +} + +func resolveTrashBase(mode runMode, cwd string) string { + if mode == modeProject { + return trash.ProjectTrashDir(cwd) + } + return trash.TrashDir() +} + +func resolveSourceDir(mode runMode, cwd string) (string, error) { + if mode == modeProject { + return fmt.Sprintf("%s/.skillshare/skills", cwd), nil + } + cfg, err := config.Load() + if err != nil { + return "", fmt.Errorf("failed to load config: %w", err) + } + return cfg.Source, nil +} + +func formatAge(d time.Duration) string { + switch { + case d < time.Hour: + return fmt.Sprintf("%dm", int(d.Minutes())) + case d < 24*time.Hour: + return fmt.Sprintf("%dh", int(d.Hours())) + default: + return fmt.Sprintf("%dd", int(d.Hours()/24)) + } +} + +func printTrashHelp() { + fmt.Println(`Usage: skillshare trash [options] + +Manage uninstalled skills in the trash. + +Commands: + list, ls List trashed skills + restore Restore most recent trashed version to source + +Options: + --project, -p Use project-level trash + --global, -g Use global trash + --help, -h Show this help + +Examples: + skillshare trash list # List trashed skills + skillshare trash restore my-skill # Restore from trash + skillshare trash restore my-skill -p # Restore in project mode`) +} diff --git a/cmd/skillshare/uninstall.go b/cmd/skillshare/uninstall.go index fcca473df..22449ced5 100644 --- a/cmd/skillshare/uninstall.go +++ b/cmd/skillshare/uninstall.go @@ -10,6 +10,7 @@ import ( "skillshare/internal/config" "skillshare/internal/install" + "skillshare/internal/trash" "skillshare/internal/ui" ) @@ -146,8 +147,11 @@ func confirmUninstall(target *uninstallTarget) (bool, error) { return input == "y" || input == "yes", nil } -// performUninstall removes the skill and cleans up +// performUninstall moves the skill to trash and cleans up func performUninstall(target *uninstallTarget, cfg *config.Config) error { + // Read metadata before moving (for reinstall hint) + meta, _ := install.ReadMeta(target.path) + // For tracked repos, clean up .gitignore if target.isTrackedRepo { if removed, err := install.RemoveFromGitIgnore(cfg.Source, target.name); err != nil { @@ -157,8 +161,9 @@ func performUninstall(target *uninstallTarget, cfg *config.Config) error { } } - if err := os.RemoveAll(target.path); err != nil { - return fmt.Errorf("failed to remove: %w", err) + trashPath, err := trash.MoveToTrash(target.path, target.name, trash.TrashDir()) + if err != nil { + return fmt.Errorf("failed to move to trash: %w", err) } if target.isTrackedRepo { @@ -166,9 +171,18 @@ func performUninstall(target *uninstallTarget, cfg *config.Config) error { } else { ui.Success("Uninstalled: %s", target.name) } + ui.Info("Moved to trash (7 days): %s", trashPath) + if meta != nil && meta.Source != "" { + ui.Info("Reinstall: skillshare install %s", meta.Source) + } fmt.Println() ui.Info("Run 'skillshare sync' to update all targets") + // Opportunistic cleanup of expired trash items + if n, _ := trash.Cleanup(trash.TrashDir(), 0); n > 0 { + ui.Info("Cleaned up %d expired trash item(s)", n) + } + return nil } @@ -227,10 +241,13 @@ func cmdUninstall(args []string) error { // Handle dry-run if opts.dryRun { - ui.Warning("[dry-run] would remove %s", target.path) + ui.Warning("[dry-run] would move to trash: %s", target.path) if target.isTrackedRepo { ui.Warning("[dry-run] would remove %s from .gitignore", target.name) } + if meta, err := install.ReadMeta(target.path); err == nil && meta != nil && meta.Source != "" { + ui.Info("[dry-run] Reinstall: skillshare install %s", meta.Source) + } return nil } @@ -264,6 +281,8 @@ func printUninstallHelp() { fmt.Println(`Usage: skillshare uninstall [options] Remove a skill or tracked repository from the source directory. +Skills are moved to trash and kept for 7 days before automatic cleanup. +If the skill was installed from a remote source, a reinstall command is shown. For tracked repositories (_repo-name): - Checks for uncommitted changes (requires --force to override) @@ -278,7 +297,7 @@ Options: --help, -h Show this help Examples: - skillshare uninstall my-skill # Remove a skill + skillshare uninstall my-skill # Remove a skill (moved to trash) skillshare uninstall my-skill --force # Skip confirmation skillshare uninstall _team-repo # Remove tracked repository skillshare uninstall team-repo # _ prefix is optional diff --git a/cmd/skillshare/uninstall_project.go b/cmd/skillshare/uninstall_project.go index 986309d7b..078d9cd95 100644 --- a/cmd/skillshare/uninstall_project.go +++ b/cmd/skillshare/uninstall_project.go @@ -9,6 +9,7 @@ import ( "skillshare/internal/config" "skillshare/internal/install" + "skillshare/internal/trash" "skillshare/internal/ui" ) @@ -46,8 +47,11 @@ func cmdUninstallProject(args []string, root string) error { isTracked := install.IsGitRepo(skillPath) if opts.dryRun { - ui.Warning("[dry-run] would remove %s", skillPath) + ui.Warning("[dry-run] would move to trash: %s", skillPath) ui.Warning("[dry-run] would update .skillshare/config.yaml and .skillshare/.gitignore") + if meta, err := install.ReadMeta(skillPath); err == nil && meta != nil && meta.Source != "" { + ui.Info("[dry-run] Reinstall: skillshare install %s --project", meta.Source) + } return nil } @@ -71,8 +75,12 @@ func cmdUninstallProject(args []string, root string) error { } } - if err := os.RemoveAll(skillPath); err != nil { - return fmt.Errorf("failed to remove: %w", err) + // Read metadata before moving (for reinstall hint) + meta, _ := install.ReadMeta(skillPath) + + trashPath, err := trash.MoveToTrash(skillPath, skillName, trash.ProjectTrashDir(root)) + if err != nil { + return fmt.Errorf("failed to move to trash: %w", err) } cfg, err := config.LoadProject(root) @@ -100,7 +108,17 @@ func cmdUninstallProject(args []string, root string) error { } else { ui.Success("Uninstalled: %s", skillName) } + ui.Info("Moved to trash (7 days): %s", trashPath) + if meta != nil && meta.Source != "" { + ui.Info("Reinstall: skillshare install %s --project", meta.Source) + } ui.Info("Run 'skillshare sync' to clean up symlinks") + + // Opportunistic cleanup of expired trash items + if n, _ := trash.Cleanup(trash.ProjectTrashDir(root), 0); n > 0 { + ui.Info("Cleaned up %d expired trash item(s)", n) + } + return nil } diff --git a/internal/trash/trash.go b/internal/trash/trash.go new file mode 100644 index 000000000..7d89a34b7 --- /dev/null +++ b/internal/trash/trash.go @@ -0,0 +1,283 @@ +package trash + +import ( + "fmt" + "io" + "os" + "path/filepath" + "sort" + "time" +) + +const defaultMaxAge = 7 * 24 * time.Hour // 7 days + +// TrashDir returns the global trash directory path. +func TrashDir() string { + home, err := os.UserHomeDir() + if err != nil { + return "" + } + return filepath.Join(home, ".config", "skillshare", "trash") +} + +// ProjectTrashDir returns the project-level trash directory path. +func ProjectTrashDir(root string) string { + return filepath.Join(root, ".skillshare", "trash") +} + +// TrashEntry holds information about a trashed item. +type TrashEntry struct { + Name string // Original skill name + Timestamp string // Timestamp portion of dir name + Path string // Full path to trashed directory + Date time.Time // Parsed or stat-based date + Size int64 // Total size in bytes +} + +// MoveToTrash moves a skill directory to the trash. +// Uses os.Rename for atomic same-device moves, falls back to copy+delete. +func MoveToTrash(srcPath, name, trashBase string) (string, error) { + timestamp := time.Now().Format("2006-01-02_15-04-05") + trashName := name + "_" + timestamp + trashPath := filepath.Join(trashBase, trashName) + + if err := os.MkdirAll(trashBase, 0755); err != nil { + return "", fmt.Errorf("failed to create trash directory: %w", err) + } + + // Try atomic rename first (same device) + if err := os.Rename(srcPath, trashPath); err == nil { + return trashPath, nil + } + + // Fallback: copy then delete (cross-device) + if err := copyDir(srcPath, trashPath); err != nil { + return "", fmt.Errorf("failed to move to trash: %w", err) + } + + if err := os.RemoveAll(srcPath); err != nil { + return trashPath, fmt.Errorf("copied to trash but failed to remove original: %w", err) + } + + return trashPath, nil +} + +// List returns all trashed items sorted by date (newest first). +func List(trashBase string) []TrashEntry { + entries, err := os.ReadDir(trashBase) + if err != nil { + return nil + } + + var items []TrashEntry + for _, entry := range entries { + if !entry.IsDir() { + continue + } + + dirName := entry.Name() + entryPath := filepath.Join(trashBase, dirName) + + // Parse name and timestamp from "skillname_YYYY-MM-DD_HH-MM-SS" + name, ts := parseTrashName(dirName) + if name == "" { + continue + } + + date, err := time.Parse("2006-01-02_15-04-05", ts) + if err != nil { + // Fallback to file mod time + if info, serr := entry.Info(); serr == nil { + date = info.ModTime() + } + } + + items = append(items, TrashEntry{ + Name: name, + Timestamp: ts, + Path: entryPath, + Date: date, + Size: dirSize(entryPath), + }) + } + + sort.Slice(items, func(i, j int) bool { + return items[i].Date.After(items[j].Date) + }) + + return items +} + +// Cleanup removes trashed items older than maxAge. +// Returns the number of items removed. +func Cleanup(trashBase string, maxAge time.Duration) (int, error) { + if maxAge == 0 { + maxAge = defaultMaxAge + } + + items := List(trashBase) + cutoff := time.Now().Add(-maxAge) + removed := 0 + + for _, item := range items { + if item.Date.Before(cutoff) { + if err := os.RemoveAll(item.Path); err != nil { + return removed, fmt.Errorf("failed to clean up %s: %w", item.Name, err) + } + removed++ + } + } + + return removed, nil +} + +// TotalSize returns the total size of all trashed items in bytes. +func TotalSize(trashBase string) int64 { + items := List(trashBase) + var total int64 + for _, item := range items { + total += item.Size + } + return total +} + +// FindByName returns the most recent trashed item matching the given skill name. +// Returns nil if not found. +func FindByName(trashBase, name string) *TrashEntry { + items := List(trashBase) + for i := range items { + if items[i].Name == name { + return &items[i] // List is sorted newest-first + } + } + return nil +} + +// Restore moves a trashed skill back to the destination directory. +// Returns an error if the destination already exists. +func Restore(entry *TrashEntry, destDir string) error { + destPath := filepath.Join(destDir, entry.Name) + + if _, err := os.Stat(destPath); err == nil { + return fmt.Errorf("'%s' already exists in %s (use --force on uninstall to replace)", entry.Name, destDir) + } + + // Try atomic rename first + if err := os.Rename(entry.Path, destPath); err == nil { + return nil + } + + // Fallback: copy then delete + if err := copyDir(entry.Path, destPath); err != nil { + return fmt.Errorf("failed to restore: %w", err) + } + + if err := os.RemoveAll(entry.Path); err != nil { + return fmt.Errorf("restored but failed to remove trash entry: %w", err) + } + + return nil +} + +// parseTrashName splits "skillname_YYYY-MM-DD_HH-MM-SS" into name and timestamp. +func parseTrashName(dirName string) (string, string) { + // Timestamp format: YYYY-MM-DD_HH-MM-SS (19 chars) + const tsLen = 19 // "2006-01-02_15-04-05" + // Need at least "x_" + timestamp + if len(dirName) < tsLen+2 { + return "", "" + } + + // The timestamp is always the last 19 characters, preceded by "_" + sep := len(dirName) - tsLen - 1 + if dirName[sep] != '_' { + return "", "" + } + + name := dirName[:sep] + ts := dirName[sep+1:] + + // Validate timestamp format + if _, err := time.Parse("2006-01-02_15-04-05", ts); err != nil { + return "", "" + } + + return name, ts +} + +// dirSize calculates total size of a directory. +func dirSize(path string) int64 { + var size int64 + filepath.Walk(path, func(_ string, info os.FileInfo, err error) error { + if err != nil { + return nil + } + if !info.IsDir() { + size += info.Size() + } + return nil + }) + return size +} + +// copyDir copies a directory recursively. +func copyDir(src, dst string) error { + if err := os.MkdirAll(dst, 0755); err != nil { + return err + } + + entries, err := os.ReadDir(src) + if err != nil { + return err + } + + for _, entry := range entries { + srcPath := filepath.Join(src, entry.Name()) + dstPath := filepath.Join(dst, entry.Name()) + + info, err := os.Lstat(srcPath) + if err != nil { + continue + } + + // Skip symlinks + if info.Mode()&os.ModeSymlink != 0 { + continue + } + + if info.IsDir() { + if err := copyDir(srcPath, dstPath); err != nil { + return err + } + } else if info.Mode().IsRegular() { + if err := copyFile(srcPath, dstPath); err != nil { + return err + } + } + } + + return nil +} + +// copyFile copies a single file. +func copyFile(src, dst string) error { + srcFile, err := os.Open(src) + if err != nil { + return err + } + defer srcFile.Close() + + srcInfo, err := srcFile.Stat() + if err != nil { + return err + } + + dstFile, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, srcInfo.Mode()) + if err != nil { + return err + } + defer dstFile.Close() + + _, err = io.Copy(dstFile, srcFile) + return err +} diff --git a/internal/trash/trash_test.go b/internal/trash/trash_test.go new file mode 100644 index 000000000..92f62264f --- /dev/null +++ b/internal/trash/trash_test.go @@ -0,0 +1,228 @@ +package trash + +import ( + "os" + "path/filepath" + "testing" + "time" +) + +func TestMoveToTrash(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + srcDir := filepath.Join(tmpDir, "source", "my-skill") + + // Create source skill + os.MkdirAll(srcDir, 0755) + os.WriteFile(filepath.Join(srcDir, "SKILL.md"), []byte("# Test"), 0644) + + trashPath, err := MoveToTrash(srcDir, "my-skill", trashBase) + if err != nil { + t.Fatalf("MoveToTrash failed: %v", err) + } + + // Source should be gone + if _, err := os.Stat(srcDir); !os.IsNotExist(err) { + t.Error("source should be removed after MoveToTrash") + } + + // Trash should contain the skill + if _, err := os.Stat(filepath.Join(trashPath, "SKILL.md")); err != nil { + t.Error("trashed skill should contain SKILL.md") + } + + // Trash path should be under trashBase + if rel, err := filepath.Rel(trashBase, trashPath); err != nil || rel == "" { + t.Error("trash path should be under trashBase") + } +} + +func TestList(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + + // Create two trashed items + os.MkdirAll(filepath.Join(trashBase, "skill-a_2026-01-01_10-00-00"), 0755) + os.WriteFile(filepath.Join(trashBase, "skill-a_2026-01-01_10-00-00", "SKILL.md"), []byte("a"), 0644) + os.MkdirAll(filepath.Join(trashBase, "skill-b_2026-01-02_10-00-00"), 0755) + os.WriteFile(filepath.Join(trashBase, "skill-b_2026-01-02_10-00-00", "SKILL.md"), []byte("b"), 0644) + + items := List(trashBase) + if len(items) != 2 { + t.Fatalf("expected 2 items, got %d", len(items)) + } + + // Newest first + if items[0].Name != "skill-b" { + t.Errorf("expected newest first, got %s", items[0].Name) + } + if items[1].Name != "skill-a" { + t.Errorf("expected skill-a second, got %s", items[1].Name) + } +} + +func TestList_Empty(t *testing.T) { + items := List("/nonexistent/path") + if len(items) != 0 { + t.Errorf("expected 0 items for nonexistent path, got %d", len(items)) + } +} + +func TestList_SkillNameWithUnderscore(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + + // Tracked repo with _ prefix + os.MkdirAll(filepath.Join(trashBase, "_team-repo_2026-01-01_10-00-00"), 0755) + + items := List(trashBase) + if len(items) != 1 { + t.Fatalf("expected 1 item, got %d", len(items)) + } + if items[0].Name != "_team-repo" { + t.Errorf("expected _team-repo, got %s", items[0].Name) + } +} + +func TestCleanup(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + + // Create an old item (8 days ago) + old := time.Now().Add(-8 * 24 * time.Hour).Format("2006-01-02_15-04-05") + os.MkdirAll(filepath.Join(trashBase, "old-skill_"+old), 0755) + + // Create a recent item (1 day ago) + recent := time.Now().Add(-1 * 24 * time.Hour).Format("2006-01-02_15-04-05") + os.MkdirAll(filepath.Join(trashBase, "new-skill_"+recent), 0755) + + removed, err := Cleanup(trashBase, 7*24*time.Hour) + if err != nil { + t.Fatalf("Cleanup failed: %v", err) + } + + if removed != 1 { + t.Errorf("expected 1 removed, got %d", removed) + } + + items := List(trashBase) + if len(items) != 1 { + t.Fatalf("expected 1 item remaining, got %d", len(items)) + } + if items[0].Name != "new-skill" { + t.Errorf("expected new-skill to remain, got %s", items[0].Name) + } +} + +func TestTotalSize(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + + os.MkdirAll(filepath.Join(trashBase, "skill_2026-01-01_10-00-00"), 0755) + os.WriteFile(filepath.Join(trashBase, "skill_2026-01-01_10-00-00", "SKILL.md"), []byte("hello"), 0644) + + size := TotalSize(trashBase) + if size != 5 { + t.Errorf("expected size 5, got %d", size) + } +} + +func TestFindByName(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + + os.MkdirAll(filepath.Join(trashBase, "my-skill_2026-01-01_10-00-00"), 0755) + os.MkdirAll(filepath.Join(trashBase, "my-skill_2026-01-02_10-00-00"), 0755) + os.MkdirAll(filepath.Join(trashBase, "other_2026-01-01_10-00-00"), 0755) + + // Should return the newest match + entry := FindByName(trashBase, "my-skill") + if entry == nil { + t.Fatal("expected to find my-skill") + } + if entry.Timestamp != "2026-01-02_10-00-00" { + t.Errorf("expected newest entry, got %s", entry.Timestamp) + } + + // Not found + if FindByName(trashBase, "nonexistent") != nil { + t.Error("expected nil for nonexistent skill") + } +} + +func TestRestore(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + destDir := filepath.Join(tmpDir, "skills") + os.MkdirAll(destDir, 0755) + + // Trash a skill first + srcDir := filepath.Join(tmpDir, "src", "restore-me") + os.MkdirAll(srcDir, 0755) + os.WriteFile(filepath.Join(srcDir, "SKILL.md"), []byte("# Restore"), 0644) + MoveToTrash(srcDir, "restore-me", trashBase) + + entry := FindByName(trashBase, "restore-me") + if entry == nil { + t.Fatal("expected to find restore-me in trash") + } + + if err := Restore(entry, destDir); err != nil { + t.Fatalf("Restore failed: %v", err) + } + + // Should be back in dest + restored := filepath.Join(destDir, "restore-me", "SKILL.md") + if _, err := os.Stat(restored); err != nil { + t.Error("restored skill should contain SKILL.md") + } + + // Trash entry should be gone + if FindByName(trashBase, "restore-me") != nil { + t.Error("trash entry should be removed after restore") + } +} + +func TestRestore_AlreadyExists(t *testing.T) { + tmpDir := t.TempDir() + trashBase := filepath.Join(tmpDir, "trash") + destDir := filepath.Join(tmpDir, "skills") + + // Create existing skill in dest + os.MkdirAll(filepath.Join(destDir, "conflict"), 0755) + + // Create trash entry + os.MkdirAll(filepath.Join(trashBase, "conflict_2026-01-01_10-00-00"), 0755) + + entry := FindByName(trashBase, "conflict") + if entry == nil { + t.Fatal("expected to find conflict in trash") + } + + err := Restore(entry, destDir) + if err == nil { + t.Error("expected error when dest already exists") + } +} + +func TestParseTrashName(t *testing.T) { + tests := []struct { + input string + wantName string + wantTS string + }{ + {"my-skill_2026-01-01_10-00-00", "my-skill", "2026-01-01_10-00-00"}, + {"_team-repo_2026-01-01_10-00-00", "_team-repo", "2026-01-01_10-00-00"}, + {"a_b_c_2026-12-31_23-59-59", "a_b_c", "2026-12-31_23-59-59"}, + {"short", "", ""}, // too short + {"no-timestamp_abc", "", ""}, // invalid timestamp + } + + for _, tt := range tests { + name, ts := parseTrashName(tt.input) + if name != tt.wantName || ts != tt.wantTS { + t.Errorf("parseTrashName(%q) = (%q, %q), want (%q, %q)", + tt.input, name, ts, tt.wantName, tt.wantTS) + } + } +} diff --git a/tests/integration/trash_test.go b/tests/integration/trash_test.go new file mode 100644 index 000000000..b3ef0abbb --- /dev/null +++ b/tests/integration/trash_test.go @@ -0,0 +1,119 @@ +package integration + +import ( + "os" + "path/filepath" + "testing" + + "skillshare/internal/testutil" +) + +func TestTrash_List_Empty(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + result := sb.RunCLI("trash", "list") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "empty") +} + +func TestTrash_List_ShowsItems(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("list-skill", map[string]string{"SKILL.md": "# List"}) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + // Uninstall to populate trash + sb.RunCLI("uninstall", "list-skill", "--force") + + result := sb.RunCLI("trash", "list") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "list-skill") + result.AssertAnyOutputContains(t, "1 item") +} + +func TestTrash_Restore_Success(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("restore-me", map[string]string{"SKILL.md": "# Restore Me"}) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + // Uninstall + sb.RunCLI("uninstall", "restore-me", "--force") + + // Verify gone from source + if sb.FileExists(filepath.Join(sb.SourcePath, "restore-me")) { + t.Fatal("skill should be in trash, not source") + } + + // Restore + result := sb.RunCLI("trash", "restore", "restore-me") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "Restored") + + // Should be back in source + if !sb.FileExists(filepath.Join(sb.SourcePath, "restore-me", "SKILL.md")) { + t.Error("skill should be restored to source") + } + + // Trash should be empty now + trashDir := filepath.Join(sb.Home, ".config", "skillshare", "trash") + entries, _ := os.ReadDir(trashDir) + if len(entries) != 0 { + t.Errorf("trash should be empty after restore, has %d entries", len(entries)) + } +} + +func TestTrash_Restore_NotFound(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + result := sb.RunCLI("trash", "restore", "nonexistent") + result.AssertFailure(t) + result.AssertAnyOutputContains(t, "not found in trash") +} + +func TestTrash_Restore_AlreadyExists(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("conflict", map[string]string{"SKILL.md": "# V1"}) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + // Uninstall + sb.RunCLI("uninstall", "conflict", "--force") + + // Recreate a skill with the same name + sb.CreateSkill("conflict", map[string]string{"SKILL.md": "# V2"}) + + // Restore should fail + result := sb.RunCLI("trash", "restore", "conflict") + result.AssertFailure(t) + result.AssertAnyOutputContains(t, "already exists") +} + +func TestTrash_Help(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + result := sb.RunCLI("trash", "--help") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "restore") + result.AssertAnyOutputContains(t, "list") +} diff --git a/tests/integration/uninstall_test.go b/tests/integration/uninstall_test.go index c1418cfc1..188dfd83b 100644 --- a/tests/integration/uninstall_test.go +++ b/tests/integration/uninstall_test.go @@ -61,7 +61,7 @@ targets: {} result.AssertSuccess(t) result.AssertOutputContains(t, "dry-run") - result.AssertOutputContains(t, "would remove") + result.AssertOutputContains(t, "would move to trash") // Verify skill was NOT removed skillPath := filepath.Join(sb.SourcePath, "dry-run-skill") diff --git a/tests/integration/uninstall_trash_test.go b/tests/integration/uninstall_trash_test.go new file mode 100644 index 000000000..da7380afe --- /dev/null +++ b/tests/integration/uninstall_trash_test.go @@ -0,0 +1,120 @@ +package integration + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "skillshare/internal/testutil" +) + +func TestUninstall_MovesToTrash(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("trash-me", map[string]string{"SKILL.md": "# Trash Me"}) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + result := sb.RunCLI("uninstall", "trash-me", "--force") + result.AssertSuccess(t) + result.AssertOutputContains(t, "Moved to trash") + + // Source should be gone + if sb.FileExists(filepath.Join(sb.SourcePath, "trash-me")) { + t.Error("skill should be removed from source") + } + + // Trash directory should contain the skill + trashDir := filepath.Join(sb.Home, ".config", "skillshare", "trash") + entries, err := os.ReadDir(trashDir) + if err != nil { + t.Fatalf("trash directory should exist: %v", err) + } + if len(entries) != 1 { + t.Fatalf("expected 1 trash entry, got %d", len(entries)) + } + + // Trashed skill should contain SKILL.md + trashedSkill := filepath.Join(trashDir, entries[0].Name(), "SKILL.md") + if _, err := os.Stat(trashedSkill); err != nil { + t.Error("trashed skill should contain SKILL.md") + } +} + +func TestUninstall_WithMeta_PrintsReinstallHint(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("remote-skill", map[string]string{ + "SKILL.md": "# Remote Skill", + ".skillshare-meta.json": `{ + "source": "github.com/user/skills/remote-skill", + "type": "github", + "installed_at": "2026-01-15T10:30:00Z" +}`, + }) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + result := sb.RunCLI("uninstall", "remote-skill", "--force") + result.AssertSuccess(t) + result.AssertOutputContains(t, "Reinstall: skillshare install github.com/user/skills/remote-skill") +} + +func TestUninstall_LocalSkill_NoReinstallHint(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + // Local skill without metadata + sb.CreateSkill("local-skill", map[string]string{"SKILL.md": "# Local"}) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + result := sb.RunCLI("uninstall", "local-skill", "--force") + result.AssertSuccess(t) + result.AssertOutputContains(t, "Moved to trash") + + // Should NOT contain reinstall hint + combined := result.Stdout + result.Stderr + if strings.Contains(combined, "Reinstall:") { + t.Error("local skill without meta should not show reinstall hint") + } +} + +func TestUninstall_DryRun_ShowsTrashPreview(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("preview-skill", map[string]string{ + "SKILL.md": "# Preview", + ".skillshare-meta.json": `{ + "source": "github.com/org/repo/preview-skill", + "type": "github", + "installed_at": "2026-01-15T10:30:00Z" +}`, + }) + sb.WriteConfig(`source: ` + sb.SourcePath + ` +targets: {} +`) + + result := sb.RunCLI("uninstall", "preview-skill", "--dry-run") + result.AssertSuccess(t) + result.AssertOutputContains(t, "would move to trash") + result.AssertOutputContains(t, "Reinstall:") + + // Skill should still exist + if !sb.FileExists(filepath.Join(sb.SourcePath, "preview-skill")) { + t.Error("dry-run should not move skill to trash") + } + + // Trash should be empty + trashDir := filepath.Join(sb.Home, ".config", "skillshare", "trash") + if _, err := os.Stat(trashDir); err == nil { + t.Error("trash directory should not be created during dry-run") + } +} diff --git a/website/docs/commands/doctor.md b/website/docs/commands/doctor.md index 0cbba4da4..533713193 100644 --- a/website/docs/commands/doctor.md +++ b/website/docs/commands/doctor.md @@ -67,6 +67,7 @@ For each target: - Skills without `SKILL.md` files - Last backup timestamp +- Trash status (item count, total size, oldest item age) - Broken symlinks in targets ## Common Issues @@ -135,6 +136,7 @@ Version Run: skillshare upgrade --skill && skillshare sync Backups: last backup 2026-01-18_09-00-00 (3 days ago) +ℹ Trash: 2 item(s) (45.2 KB), oldest 3 day(s) ℹ Update available: 1.2.0 -> 1.3.0 brew upgrade skillshare OR curl -fsSL .../install.sh | sh diff --git a/website/docs/commands/sync.md b/website/docs/commands/sync.md index 16e273ad5..7ba14124d 100644 --- a/website/docs/commands/sync.md +++ b/website/docs/commands/sync.md @@ -6,6 +6,10 @@ sidebar_position: 2 Push skills from source to all targets. +:::info Why is sync a separate command? +Operations like `install` and `uninstall` only modify source — sync propagates to targets. This lets you batch changes, preview with `--dry-run`, and control when targets update. See [Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step). +::: + ## Command Overview | Type | Command | Direction | diff --git a/website/docs/commands/trash.md b/website/docs/commands/trash.md new file mode 100644 index 000000000..908aefdc5 --- /dev/null +++ b/website/docs/commands/trash.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 4 +--- + +# trash + +Manage uninstalled skills in the trash directory. + +```bash +skillshare trash list # List trashed skills +skillshare trash restore my-skill # Restore from trash +skillshare trash restore my-skill -p # Restore in project mode +``` + +## Subcommands + +### list + +Show all skills currently in the trash: + +```bash +skillshare trash list +``` + +``` +Trash + my-skill (1.2 KB, 2d ago) + old-helper (800 B, 5d ago) + +2 item(s), 2.0 KB total +Items are automatically cleaned up after 7 days +``` + +### restore + +Restore the most recent trashed version of a skill back to the source directory: + +```bash +skillshare trash restore my-skill +``` + +``` +✓ Restored: my-skill +ℹ Trashed 2d ago, now back in ~/.config/skillshare/skills +ℹ Run 'skillshare sync' to update targets +``` + +If a skill with the same name already exists in source, restore will fail. Uninstall the existing skill first or use a different name. + +## Backup vs Trash + +These two safety mechanisms protect different things: + +| | backup | trash | +|---|---|---| +| **Protects** | target directories (sync snapshots) | source skills (uninstall) | +| **Location** | `~/.config/skillshare/backups/` | `~/.config/skillshare/trash/` | +| **Triggered by** | `sync`, `target remove` | `uninstall` | +| **Restore with** | `skillshare restore ` | `skillshare trash restore ` | +| **Auto-cleanup** | manual (`backup --cleanup`) | 7 days | + +## Options + +| Flag | Description | +|------|-------------| +| `--project, -p` | Use project-level trash (`.skillshare/trash/`) | +| `--global, -g` | Use global trash | +| `--help, -h` | Show help | + +## Auto-Cleanup + +Expired trash items (older than 7 days) are automatically cleaned up when you run `uninstall` or `sync`. No cron or scheduled task is needed. + +## Related + +- [uninstall](/docs/commands/uninstall) — Remove skills (moves to trash) +- [backup](/docs/commands/backup) — Backup target directories +- [restore](/docs/commands/restore) — Restore targets from backup diff --git a/website/docs/commands/uninstall.md b/website/docs/commands/uninstall.md index 57307fd98..cc372c1c8 100644 --- a/website/docs/commands/uninstall.md +++ b/website/docs/commands/uninstall.md @@ -4,7 +4,7 @@ sidebar_position: 3 # uninstall -Remove a skill or tracked repository from the source directory. +Remove a skill or tracked repository from the source directory. Skills are moved to trash and kept for 7 days before automatic cleanup. ```bash skillshare uninstall my-skill # Remove a skill @@ -35,8 +35,8 @@ skillshare uninstall my-skill --force # Skip confirmation │ ▼ ┌─────────────────────────────────────────────────────────────────┐ -│ 3. Remove from source │ -│ → Deleted: ~/.config/skillshare/skills/my-skill/ │ +│ 3. Move to trash (kept 7 days) │ +│ → ~/.config/skillshare/trash/my-skill_/ │ └─────────────────────────────────────────────────────────────────┘ ``` @@ -78,6 +78,29 @@ skillshare uninstall team-repo skillshare uninstall my-skill --force ``` +## Safety + +Uninstalled skills are **moved to trash**, not permanently deleted: + +- **Location:** `~/.config/skillshare/trash/` (global) or `.skillshare/trash/` (project) +- **Retention:** 7 days, then automatically cleaned up +- **Reinstall hint:** If the skill was installed from a remote source, the reinstall command is shown +- **Restore:** Use `skillshare trash restore ` to recover from trash + +``` +✓ Uninstalled: my-skill +ℹ Moved to trash (7 days): ~/.config/skillshare/trash/my-skill_2026-01-20_15-30-00 +ℹ Reinstall: skillshare install github.com/user/repo/my-skill +``` + +To restore an accidentally uninstalled skill: + +```bash +skillshare trash list # See what's in trash +skillshare trash restore my-skill # Restore to source +skillshare sync # Sync back to targets +``` + ## After Uninstalling Run `skillshare sync` to remove the skill from all targets: @@ -98,7 +121,7 @@ skillshare uninstall team-skills -p -f # Force remove with uncommitted change ``` In project mode, uninstall: -- Removes the skill directory from `.skillshare/skills/` +- Moves the skill directory to `.skillshare/trash/` (kept 7 days) - Removes the skill's entry from `.skillshare/config.yaml` `skills:` list (for remote skills) - Removes the entry from `.skillshare/.gitignore` (for remote/tracked skills) - For tracked repos: checks for uncommitted changes (use `--force` to override) @@ -114,4 +137,5 @@ git add .skillshare/ && git commit -m "Remove pdf skill" - [install](/docs/commands/install) — Install skills - [list](/docs/commands/list) — List installed skills +- [trash](/docs/commands/trash) — Manage trashed skills - [Project Skills](/docs/concepts/project-skills) — Project mode concepts diff --git a/website/docs/concepts/source-and-targets.md b/website/docs/concepts/source-and-targets.md index 0998543e5..d773a146d 100644 --- a/website/docs/concepts/source-and-targets.md +++ b/website/docs/concepts/source-and-targets.md @@ -57,6 +57,26 @@ Skillshare introduces a **source directory** that syncs to all **targets**: --- +## Why Sync is a Separate Step + +Operations like `install`, `update`, and `uninstall` only modify the **source** directory. A separate `sync` step propagates changes to all targets. This two-phase design is intentional: + +**Preview before propagating** — Run `sync --dry-run` to review what will change across all targets before applying. Especially useful after `uninstall` or `--force` operations. + +**Batch multiple changes** — Install 5 skills, then sync once. Without separation, each install would trigger a full scan and symlink update across all targets. + +**Safe by default** — Source changes are staged, not immediately live. You stay in control of when targets update. Additionally, `uninstall` moves skills to a trash directory (kept 7 days) instead of permanently deleting them, so accidental removals are recoverable. + +:::tip Exception: pull +`pull` automatically runs sync after `git pull`. Since its intent is "bring everything up to date from remote," auto-syncing matches the expected behavior. +::: + +:::info When sync is NOT needed +Editing an existing skill doesn't require sync — symlinks mean changes are instantly visible in all targets. You only need sync when the set of skills changes (add, remove, rename) or when targets/modes change. +::: + +--- + ## Source Directory **Default location:** `~/.config/skillshare/skills/` diff --git a/website/docs/reference/file-structure.md b/website/docs/reference/file-structure.md index a0201d962..c9ef66bdb 100644 --- a/website/docs/reference/file-structure.md +++ b/website/docs/reference/file-structure.md @@ -25,12 +25,17 @@ Directory layout and file locations for skillshare. │ └── backend/ │ └── api/ │ └── SKILL.md -└── backups/ # Backup directory - ├── 2026-01-20_15-30-00/ - │ ├── claude/ - │ └── cursor/ - └── 2026-01-19_10-00-00/ - └── claude/ +├── backups/ # Backup directory +│ ├── 2026-01-20_15-30-00/ +│ │ ├── claude/ +│ │ └── cursor/ +│ └── 2026-01-19_10-00-00/ +│ └── claude/ +└── trash/ # Uninstalled skills (7-day retention) + ├── my-skill_2026-01-20_15-30-00/ + │ └── SKILL.md + └── old-skill_2026-01-19_10-00-00/ + └── SKILL.md ``` --- @@ -155,6 +160,35 @@ Backups are created: --- +## Trash Directory + +### Location + +``` +~/.config/skillshare/trash/ +``` + +**Project mode:** +``` +/.skillshare/trash/ +``` + +### Structure + +``` +trash/ +└── _/ # skill-name_YYYY-MM-DD_HH-MM-SS + ├── SKILL.md + └── ... # All original files preserved +``` + +Trashed skills are: +- Created by `skillshare uninstall` +- Retained for 7 days, then automatically cleaned up +- Named with the original skill name and a timestamp + +--- + ## Target Directories Targets are AI CLI skill directories. After sync, they contain symlinks to source: @@ -223,6 +257,7 @@ _team-skills__frontend__ui/SKILL.md | Config | `~/.config/skillshare/config.yaml` | | Source | `~/.config/skillshare/skills/` | | Backups | `~/.config/skillshare/backups/` | +| Trash | `~/.config/skillshare/trash/` | | Link type | Symlinks | ### Windows @@ -232,6 +267,7 @@ _team-skills__frontend__ui/SKILL.md | Config | `%USERPROFILE%\.config\skillshare\config.yaml` | | Source | `%USERPROFILE%\.config\skillshare\skills\` | | Backups | `%USERPROFILE%\.config\skillshare\backups\` | +| Trash | `%USERPROFILE%\.config\skillshare\trash\` | | Link type | NTFS Junctions | --- diff --git a/website/docs/troubleshooting/faq.md b/website/docs/troubleshooting/faq.md index 8869c498f..8764a32a1 100644 --- a/website/docs/troubleshooting/faq.md +++ b/website/docs/troubleshooting/faq.md @@ -60,6 +60,19 @@ skillshare init --remote git@github.com:you/private-skills.git ## Sync +### Why do I need to run `sync` after every install/update? + +Sync is intentionally a separate step. Operations like `install`, `update`, and `uninstall` only modify the **source** directory — `sync` propagates those changes to all targets. + +This lets you: +- **Batch changes** — Install 5 skills, then sync once instead of 5 times +- **Preview first** — Run `sync --dry-run` before applying +- **Stay in control** — You decide when targets update + +**Note:** `pull` is the only command that auto-syncs, because its intent is "bring everything up to date." + +See [Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step) for the full design rationale. + ### How do I sync across multiple machines? Use git-based cross-machine sync: @@ -88,6 +101,39 @@ Or restore from backup: skillshare restore claude ``` +### What if I accidentally uninstall a skill? + +Uninstalled skills are moved to trash and kept for 7 days. Restore with: + +```bash +skillshare trash list # See what's in trash +skillshare trash restore my-skill # Restore to source +skillshare sync # Sync back to targets +``` + +If the skill was installed from a remote source, you can also reinstall: + +```bash +skillshare install github.com/user/repo/my-skill +skillshare sync +``` + +For project mode, trash is at `.skillshare/trash/` within the project directory. Use `-p` flag with trash commands. + +Run `skillshare doctor` to see current trash status (item count, size, age). + +### What's the difference between backup and trash? + +| | backup | trash | +|---|---|---| +| **Protects** | target directories (sync snapshots) | source skills (uninstall) | +| **Location** | `~/.config/skillshare/backups/` | `~/.config/skillshare/trash/` | +| **Triggered by** | `sync`, `target remove` | `uninstall` | +| **Restore with** | `skillshare restore ` | `skillshare trash restore ` | +| **Auto-cleanup** | manual (`backup --cleanup`) | 7 days | + +They are complementary — backup protects targets from sync changes, trash protects source skills from accidental deletion. + --- ## Targets diff --git a/website/docs/workflows/daily-workflow.md b/website/docs/workflows/daily-workflow.md index 989015d82..929f79447 100644 --- a/website/docs/workflows/daily-workflow.md +++ b/website/docs/workflows/daily-workflow.md @@ -50,15 +50,19 @@ Because targets are symlinked, this edits the source file directly. After editing, sync is **usually not needed** because of symlinks. However, run sync when: -- You've added new skills +- You've installed or removed skills - You've changed sync mode -- You've added new targets +- You've added or removed targets - You see "out of sync" in status ```bash skillshare sync ``` +:::tip Why is sync a separate step? +Sync is intentionally decoupled from install/update/uninstall. This lets you batch multiple changes (e.g., install 3 skills → sync once), preview with `--dry-run` before propagating, and keep full control of when targets update. See [Source & Targets: Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step) for details. +::: + ### Preview first ```bash diff --git a/website/sidebars.ts b/website/sidebars.ts index eecdb0b56..7017ac715 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -95,6 +95,7 @@ const sidebars: SidebarsConfig = { 'commands/collect', 'commands/backup', 'commands/restore', + 'commands/trash', 'commands/push', 'commands/pull', ],