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 <name>` 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
This commit is contained in:
Willie
2026-02-09 22:46:36 +08:00
parent d2e0065553
commit 3a920610f2
21 changed files with 1264 additions and 21 deletions
+48
View File
@@ -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")
+3
View File
@@ -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", "<target>", "Restore target from latest backup")
cmd("trash", "list", "List trashed skills")
cmd("trash", "restore <name>", "Restore a skill from trash")
fmt.Println()
// Git Remote
+8
View File
@@ -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
}
+8
View File
@@ -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
}
+174
View File
@@ -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 <command> [options]
Manage uninstalled skills in the trash.
Commands:
list, ls List trashed skills
restore <name> 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`)
}
+24 -5
View File
@@ -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 <name> [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
+21 -3
View File
@@ -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
}
+283
View File
@@ -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
}
+228
View File
@@ -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)
}
}
}
+119
View File
@@ -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")
}
+1 -1
View File
@@ -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")
+120
View File
@@ -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")
}
}
+2
View File
@@ -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
+4
View File
@@ -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 |
+78
View File
@@ -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 <target>` | `skillshare trash restore <name>` |
| **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
+28 -4
View File
@@ -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_<timestamp>/ │
└─────────────────────────────────────────────────────────────────┘
```
@@ -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 <name>` 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
@@ -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/`
+42 -6
View File
@@ -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:**
```
<project>/.skillshare/trash/
```
### Structure
```
trash/
└── <skill-name>_<timestamp>/ # 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 |
---
+46
View File
@@ -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 <target>` | `skillshare trash restore <name>` |
| **Auto-cleanup** | manual (`backup --cleanup`) | 7 days |
They are complementary — backup protects targets from sync changes, trash protects source skills from accidental deletion.
---
## Targets
+6 -2
View File
@@ -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
+1
View File
@@ -95,6 +95,7 @@ const sidebars: SidebarsConfig = {
'commands/collect',
'commands/backup',
'commands/restore',
'commands/trash',
'commands/push',
'commands/pull',
],