feat(agents): wire backup/restore and update CLI help text (Phase 4)

backup/restore:
- "backup agents" backs up agent target paths (entry name: <target>-agents)
- "restore agents <target>" restores from agent backup
- Default backup unchanged (skills only)

help text:
- Updated 9 commands with agents positional in Usage and Examples:
  list, sync, update, uninstall, collect, trash, backup, restore,
  status, diff

5 new integration tests (backup/restore round-trip, dry-run, default
unchanged, project mode rejected), all passing.
This commit is contained in:
Willie
2026-04-07 18:05:40 +08:00
parent c2b9a1537d
commit 95c46ca822
11 changed files with 284 additions and 19 deletions
+23 -5
View File
@@ -25,6 +25,9 @@ func cmdBackup(args []string) error {
return fmt.Errorf("backup is not supported in project mode")
}
// Extract kind filter (e.g. "skillshare backup agents").
kind, args := parseKindArg(args)
start := time.Now()
var targetName string
doList := false
@@ -63,7 +66,11 @@ func cmdBackup(args []string) error {
return backupCleanup()
}
err = createBackup(targetName, dryRun)
if kind == kindAgents {
err = createAgentBackup(targetName, dryRun)
} else {
err = createBackup(targetName, dryRun)
}
if !dryRun {
e := oplog.NewEntry("backup", statusFromErr(err), time.Since(start))
@@ -326,7 +333,11 @@ func cmdRestore(args []string) error {
return fmt.Errorf("restore is not supported in project mode")
}
// Extract kind filter (e.g. "skillshare restore agents").
kind, args := parseKindArg(args)
start := time.Now()
_ = start // used below
var targetName string
var fromTimestamp string
@@ -357,6 +368,11 @@ func cmdRestore(args []string) error {
}
}
// Agent restore uses agent-specific backup entries (name suffixed with "-agents")
if kind == kindAgents {
return restoreAgentBackup(targetName, fromTimestamp, force, dryRun)
}
// No target specified → TUI dispatch (or plain text fallback)
if targetName == "" && fromTimestamp == "" && !dryRun {
return restoreTUIDispatch(noTUI)
@@ -537,7 +553,7 @@ func previewRestoreFromLatest(targetName, targetPath string, opts backup.Restore
}
func printBackupHelp() {
fmt.Println(`Usage: skillshare backup [target] [options]
fmt.Println(`Usage: skillshare backup [agents] [target] [options]
Create a snapshot of target skill directories.
Without arguments, backs up all targets.
@@ -557,11 +573,12 @@ Examples:
skillshare backup claude # Backup only claude
skillshare backup --list # List all backups
skillshare backup --cleanup # Remove old backups
skillshare backup --cleanup --dry-run # Preview cleanup`)
skillshare backup --cleanup --dry-run # Preview cleanup
skillshare backup agents # Backup all agent targets`)
}
func printRestoreHelp() {
fmt.Println(`Usage: skillshare restore [target] [options]
fmt.Println(`Usage: skillshare restore [agents] [target] [options]
Restore target skills from a backup snapshot.
Without arguments, launches an interactive TUI.
@@ -581,5 +598,6 @@ Examples:
skillshare restore claude # Restore claude from latest backup
skillshare restore claude --from 2024-01-15_14-30-45
skillshare restore claude --dry-run # Preview restore
skillshare restore --no-tui # List backups (no TUI)`)
skillshare restore --no-tui # List backups (no TUI)
skillshare restore agents claude # Restore agents claude target`)
}
+94
View File
@@ -0,0 +1,94 @@
package main
import (
"fmt"
"skillshare/internal/backup"
"skillshare/internal/config"
"skillshare/internal/ui"
)
// createAgentBackup backs up agent target directories.
// Agent backups use "<target>-agents" as the backup entry name.
func createAgentBackup(targetName string, dryRun bool) error {
cfg, err := config.Load()
if err != nil {
return err
}
builtinAgents := config.DefaultAgentTargets()
ui.Header("Creating agent backup")
if dryRun {
ui.Warning("Dry run mode - no backups will be created")
}
created := 0
for name := range cfg.Targets {
if targetName != "" && name != targetName {
continue
}
agentPath := resolveAgentTargetPath(cfg.Targets[name], builtinAgents, name)
if agentPath == "" {
continue
}
entryName := name + "-agents"
if dryRun {
ui.Info("%s: would backup agents from %s", entryName, agentPath)
continue
}
backupPath, backupErr := backup.Create(entryName, agentPath)
if backupErr != nil {
ui.Warning("Failed to backup %s: %v", entryName, backupErr)
continue
}
if backupPath != "" {
ui.StepDone(entryName, backupPath)
created++
} else {
ui.StepSkip(entryName, "nothing to backup")
}
}
if created == 0 && !dryRun {
ui.Info("No agent targets to backup")
}
return nil
}
// restoreAgentBackup restores agent target directories from backup.
func restoreAgentBackup(targetName, fromTimestamp string, force, dryRun bool) error {
if targetName == "" {
return fmt.Errorf("usage: skillshare restore agents <target> [--from <timestamp>] [--force] [--dry-run]")
}
cfg, err := config.Load()
if err != nil {
return err
}
builtinAgents := config.DefaultAgentTargets()
agentPath := resolveAgentTargetPath(cfg.Targets[targetName], builtinAgents, targetName)
if agentPath == "" {
return fmt.Errorf("target '%s' has no agent path configured", targetName)
}
entryName := targetName + "-agents"
ui.Header(fmt.Sprintf("Restoring agents for %s", targetName))
if dryRun {
ui.Warning("Dry run mode - no changes will be made")
ui.Info("Would restore %s to %s", entryName, agentPath)
return nil
}
opts := backup.RestoreOptions{Force: force}
if fromTimestamp != "" {
return restoreFromTimestamp(entryName, agentPath, fromTimestamp, opts)
}
return restoreFromLatest(entryName, agentPath, opts)
}
+3 -2
View File
@@ -309,7 +309,7 @@ func showCollectNextSteps(source string) {
}
func printCollectHelp() {
fmt.Println(`Usage: skillshare collect [target] [options]
fmt.Println(`Usage: skillshare collect [agents] [target] [options]
Collect local skills from target(s) to source directory.
@@ -328,5 +328,6 @@ Options:
Examples:
skillshare collect claude Collect from Claude target
skillshare collect --all Collect from all targets
skillshare collect --dry-run Preview what would be collected`)
skillshare collect --dry-run Preview what would be collected
skillshare collect agents Collect from agents targets`)
}
+3 -2
View File
@@ -1050,7 +1050,7 @@ func pluralS(n int) string {
}
func printDiffHelp() {
fmt.Println(`Usage: skillshare diff [target] [options]
fmt.Println(`Usage: skillshare diff [agents|all] [target] [options]
Show differences between source skills and target directories.
Previews what 'sync' would change without modifying anything.
@@ -1072,5 +1072,6 @@ Examples:
skillshare diff claude # Diff a single target
skillshare diff -p # Diff project-mode targets
skillshare diff --stat # Show file-level stat
skillshare diff --patch # Show full text diff`)
skillshare diff --patch # Show full text diff
skillshare diff agents # Diff agents targets only`)
}
+4 -2
View File
@@ -785,7 +785,7 @@ func abbreviateSource(source string) string {
}
func printListHelp() {
fmt.Println(`Usage: skillshare list [pattern] [options]
fmt.Println(`Usage: skillshare list [agents|all] [pattern] [options]
List all installed skills in the source directory.
An optional pattern filters skills by name, path, or source (case-insensitive).
@@ -806,5 +806,7 @@ Examples:
skillshare list --type local
skillshare list react --type github --sort newest
skillshare list --json | jq '.[].name'
skillshare list --verbose`)
skillshare list --verbose
skillshare list agents # List agents only
skillshare list all # List skills + agents`)
}
+4 -2
View File
@@ -531,7 +531,7 @@ func checkSkillVersion(cfg *config.Config) {
}
func printStatusHelp() {
fmt.Println(`Usage: skillshare status [options]
fmt.Println(`Usage: skillshare status [agents|all] [options]
Show status of source, skills, and all targets.
@@ -544,5 +544,7 @@ Options:
Examples:
skillshare status Show current state
skillshare status --json Output as JSON
skillshare status -p Show project status`)
skillshare status -p Show project status
skillshare status agents Show agents status only
skillshare status all Show skills + agents status`)
}
+4 -2
View File
@@ -783,7 +783,7 @@ func syncSymlinkMode(name string, target config.TargetConfig, source string, dry
}
func printSyncHelp() {
fmt.Println(`Usage: skillshare sync [options]
fmt.Println(`Usage: skillshare sync [agents|all] [options]
Sync skills from source to all configured targets.
@@ -803,5 +803,7 @@ Examples:
skillshare sync Sync skills to all targets
skillshare sync --dry-run Preview sync changes
skillshare sync --all Sync skills and extras
skillshare sync -p Sync project-level skills`)
skillshare sync -p Sync project-level skills
skillshare sync agents Sync agents only
skillshare sync all Sync skills and agents`)
}
+4 -2
View File
@@ -315,7 +315,7 @@ func logTrashOp(cfgPath string, action string, count int, name string, start tim
}
func printTrashHelp() {
fmt.Println(`Usage: skillshare trash <command> [options]
fmt.Println(`Usage: skillshare trash [agents] <command> [options]
Manage uninstalled skills in the trash.
@@ -337,5 +337,7 @@ Examples:
skillshare trash restore my-skill # Restore from trash
skillshare trash restore my-skill -p # Restore in project mode
skillshare trash delete my-skill # Permanently delete from trash
skillshare trash empty # Empty the trash`)
skillshare trash empty # Empty the trash
skillshare trash agents list # List trashed agents
skillshare trash agents restore tutor # Restore an agent from trash`)
}
+4 -1
View File
@@ -1163,6 +1163,7 @@ func logUninstallOp(cfgPath string, names []string, succeeded int, start time.Ti
func printUninstallHelp() {
fmt.Println(`Usage: skillshare uninstall <name>... [options]
skillshare uninstall [agents] <name|--all> [options]
skillshare uninstall --group <group> [options]
skillshare uninstall --all [options]
@@ -1198,5 +1199,7 @@ Examples:
skillshare uninstall --group frontend -n # Preview group removal
skillshare uninstall x -G backend --force # Mix names and groups
skillshare uninstall _team-repo # Remove tracked repository
skillshare uninstall team-repo # _ prefix is optional`)
skillshare uninstall team-repo # _ prefix is optional
skillshare uninstall agents tutor # Uninstall an agent
skillshare uninstall agents --all # Uninstall all agents`)
}
+6 -1
View File
@@ -493,6 +493,7 @@ func logUpdateOp(cfgPath string, names []string, opts *updateOptions, mode strin
func printUpdateHelp() {
fmt.Println(`Usage: skillshare update <name>... [options]
skillshare update [agents] <name|--all> [options]
skillshare update --group <group> [options]
skillshare update --all [options]
@@ -540,5 +541,9 @@ Examples:
skillshare update --all -T high # Use HIGH threshold for this run
skillshare update --all --dry-run # Preview updates
skillshare update _team --force # Discard changes and update
skillshare update --all --prune # Update all + remove stale skills`)
skillshare update --all --prune # Update all + remove stale skills
skillshare update agents --all # Update all agents
skillshare update agents tutor # Update a single agent
Note: --group is not supported for agents.`)
}
+135
View File
@@ -0,0 +1,135 @@
//go:build !online
package integration
import (
"os"
"path/filepath"
"testing"
"skillshare/internal/testutil"
)
func TestBackup_Agents_CreatesBackup(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
createAgentSource(t, sb, map[string]string{
"tutor.md": "# Tutor agent",
})
claudeAgents := createAgentTarget(t, sb, "claude")
sb.WriteConfig(`source: ` + sb.SourcePath + `
targets:
claude:
skills:
path: ` + sb.CreateTarget("claude") + `
agents:
path: ` + claudeAgents + `
`)
// Sync agents first so there's something to backup
sb.RunCLI("sync", "agents")
result := sb.RunCLI("backup", "agents")
result.AssertSuccess(t)
result.AssertAnyOutputContains(t, "agent backup")
}
func TestBackup_Agents_DryRun(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
createAgentSource(t, sb, map[string]string{
"tutor.md": "# Tutor agent",
})
claudeAgents := createAgentTarget(t, sb, "claude")
sb.WriteConfig(`source: ` + sb.SourcePath + `
targets:
claude:
skills:
path: ` + sb.CreateTarget("claude") + `
agents:
path: ` + claudeAgents + `
`)
sb.RunCLI("sync", "agents")
result := sb.RunCLI("backup", "agents", "--dry-run")
result.AssertSuccess(t)
result.AssertAnyOutputContains(t, "Dry run")
}
func TestBackup_Agents_RestoreRoundTrip(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
createAgentSource(t, sb, map[string]string{
"tutor.md": "# Tutor agent",
})
claudeAgents := createAgentTarget(t, sb, "claude")
sb.WriteConfig(`source: ` + sb.SourcePath + `
targets:
claude:
skills:
path: ` + sb.CreateTarget("claude") + `
agents:
path: ` + claudeAgents + `
`)
// Sync then backup
sb.RunCLI("sync", "agents")
sb.RunCLI("backup", "agents")
// Verify symlink exists
linkPath := filepath.Join(claudeAgents, "tutor.md")
if _, err := os.Lstat(linkPath); err != nil {
t.Fatalf("expected agent symlink at %s", linkPath)
}
// Delete the agent from target
os.Remove(linkPath)
if _, err := os.Lstat(linkPath); !os.IsNotExist(err) {
t.Fatal("symlink should be removed")
}
// Restore
result := sb.RunCLI("restore", "agents", "claude", "--force")
result.AssertSuccess(t)
result.AssertAnyOutputContains(t, "Restored")
}
func TestBackup_Default_DoesNotBackupAgents(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
sb.CreateSkill("my-skill", map[string]string{
"SKILL.md": "---\nname: my-skill\n---\n# Content",
})
claudeSkills := sb.CreateTarget("claude")
sb.WriteConfig(`source: ` + sb.SourcePath + `
targets:
claude:
skills:
path: ` + claudeSkills + `
`)
// Default backup should only backup skills, not mention agents
result := sb.RunCLI("backup")
result.AssertSuccess(t)
result.AssertOutputNotContains(t, "agent")
}
func TestRestore_Agents_ProjectModeRejected(t *testing.T) {
sb := testutil.NewSandbox(t)
defer sb.Cleanup()
sb.WriteConfig(`source: ` + sb.SourcePath + "\ntargets: {}\n")
result := sb.RunCLI("restore", "-p", "agents", "claude")
result.AssertFailure(t)
result.AssertAnyOutputContains(t, "not supported in project mode")
}