Files
1419b62499 fix(sync): never delete or re-point entries skillshare did not create (#914)
* fix(sync): never delete or re-point entries skillshare did not create

On Windows, a plain `init` followed by `sync` deleted things in
~/.claude/skills that skillshare never created, with no backup and no
prompt. It also re-pointed another tool's junction. Seen in a sandbox
run of v0.30.7:

- prune removed real folders whose names only look like skillshare's
  flat naming (team__shared, _drafts), via the name heuristic
- prune removed a broken link that another tool or the user made
- merge sync deleted and re-created a same-name link that pointed into
  another manager's store
- init's import deleted original folders that matched the source
  byte for byte

The manifest already records what skillshare made, so use it:

- prune keeps a look-alike folder that is not in the manifest and warns
  once per sync; --force still removes it
- prune removes a broken external link only if the manifest records it
  (e.g. after the source moved); otherwise it keeps the link and warns
- merge sync re-points a link only if the manifest records it or it
  already points into the source; otherwise it reports the entry as
  kept local, as it already does for a real folder; --force replaces it
- init's import moves identical copies to the trash under
  replaced-by-init/<target>/ instead of deleting them

Tests: ownership_test.go adds regression tests that use createLink, so
they run on Windows without Developer Mode (junctions). The 4 keep
tests fail without this change. TestSyncTargetMerge_FixesBrokenLink now
records the link in the manifest first, since a same-name link that
skillshare did not make is no longer re-pointed. Existing tests in
internal/sync, internal/trash and cmd/skillshare show the same failures
on a Windows host with and without the change (symlink privilege). The
devcontainer suite has not been run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say what sync and init keep when skillshare did not create it

The previous commit makes sync and init leave alone entries skillshare
did not create. Update the pages that describe that behaviour:

- sync-modes: merge mode keeps a same-name link from another tool and
  reports it as local; orphan cleanup keeps folders that only look like
  skillshare's flat names, and broken links outside the source that the
  manifest does not record. sync --force still removes them.
- init: identical folders replaced with links during the first sync go
  to the trash first (replaced-by-init/<tool>/, cleaned after 7 days).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(sourcefs): drop the raw-write allowance replaceIdenticalCopies no longer needs

replaceIdenticalCopies now moves an identical copy to the trash instead
of calling os.RemoveAll, so TestRawWriteRatchet reports its allowance as
stale.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(sync): apply the ownership rule at every consumer

Review of the first commit found places that still did, or predicted,
the old behaviour. One rule now decides whether a link is skillshare's:
Manifest.OwnsLink (the manifest records a link there, or it points into
the source). It compares canonical paths, so a source reached through an
alias and a relative project link still count as skillshare's.

- copy mode kept re-pointing: it removed any same-name link and wrote a
  copy. It now keeps a link it does not own, like merge mode.
- the dashboard diff predicted a prune for a folder that is only named
  like skillshare's, and an update for another tool's link. It now
  reports them as local and kept. The orphan-link prediction uses the
  same rule as prune.
- `diff` reported a target as in sync while sync printed "kept local"
  for another tool's link. It lists the link as a local override.
- doctor reported a broken link skillshare did not create as an error
  and suggested `skillshare sync`, which now keeps it. It is a warning
  with its own row, and `broken_symlinks` is `warning` in --json.
- `trash restore` put a folder init had replaced into the source as a
  new nested skill. Restore refuses entries under replaced-by-init/ and
  names the trash folder to copy from.
- init reported a folder it could not move to the trash as one that
  differs from the source, and dropped the error. It is reported
  separately, with the error.
- the PruneOptions.ManagedOnly comment still said broken external links
  are skipped; manifest-recorded ones are removed.

Tests cover the states the review listed: a source behind an alias, a
relative project link, ManagedOnly, standard naming, dry run with
--force, and a recorded copy the user replaced with a link.
TestSync_Pruning_RemovesBrokenExternalSymlinks passed without testing
anything, because FileExists follows links; it is now two tests that
use Lstat, one per owner.

Agent merge is unchanged: agents have no link manifest.

* fix(diff): list another tool's link as kept in copy mode too

Copy mode now keeps a same-name link skillshare did not create, but both
diffs read the entry with os.Stat. A broken link showed as a skill to
add on every run, and a live one as a plain local copy, while sync kept
both and said "kept local".

`diff` and the dashboard diff check the link first and report it the way
merge mode does: a local override, kept until --force.

* test(sync): make the aliased-source link while its folder exists

TestSyncMergeRepointsUnrecordedLinkIntoAliasedSource failed on Windows:
it linked straight to a missing folder, and a junction cannot be made
to one. It now links first and removes the folder after, like the other
broken-link tests in this file.

* fix(sync): compare a broken link by where it would point

linksIntoSource resolved both paths with EvalSymlinks, which gives up on
a path that does not exist. A broken link is exactly that, so a link
into a source reached through an alias (a symlinked config folder, or a
short 8.3 path on Windows) compared an unresolved path with a resolved
one and was taken for another tool's link. Sync then kept it instead of
repairing or pruning it.

It now uses sourcewalk.Canonical, which resolves the nearest folder that
exists and keeps the missing tail. The test covers both spellings: the
alias in the link, and the alias in the configured source.

* fix(init): report what the first sync kept, and match prune in the diff

Two previews said less, or more, than sync does.

init ran its first sync quietly and printed only "Synced". Sync now keeps
a link another tool put on a skill's name, a folder that is only named
like skillshare's, and a broken link it did not create, so the skill was
reported as synced while the tool still loaded the other copy. firstSync
returns the warnings a plain sync prints, and init shows them. They
already name the folders that differ from the source, so the separate
list of those is gone.

The dashboard diff counted an orphan link as a removal whenever the
manifest recorded it. Prune keeps a recorded link that still resolves
outside the source (the source moved and the old checkout stayed), so
the Sync page showed a removal that never happened. The diff now uses
prune's own rule: a link into the source goes when broken or recorded;
any other link only when broken and recorded.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Willie <egg358358@gmail.com>
2026-11-17 04:15:04 +08:00

5.7 KiB

sidebar_position
sidebar_position
4

trash

Manage uninstalled skills and agents in the trash directory.

skillshare trash list                    # Interactive TUI (in TTY)
skillshare trash list --no-tui           # Plain text output
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 agents list             # List trashed agents
skillshare trash agents restore tutor    # Restore an agent from trash
skillshare trash --all list              # List trashed skills + agents

When to Use

  • Recover a skill or agent you recently uninstalled (within 7 days)
  • Permanently delete trashed items to free space
  • Check what's in the trash before it auto-expires

Interactive TUI

In a TTY, trash list opens an interactive list of trashed items, newest first. Select one or more to restore them or delete them permanently, or empty the whole trash; each asks first. Opening an item shows its files, so you can check it before restoring. The keys are listed at the bottom of the screen. When using --all or without a kind filter, skills and agents are listed together.

If some items fail, for example restoring a skill whose name already exists in source, the rest are still processed and the result lists what failed.

Use --no-tui to skip the TUI and print plain text instead:

skillshare trash list --no-tui           # Plain text output
skillshare trash list --no-tui | less    # Pipe to pager manually

Kind Filter

By default, trash operates on skills. Use the agents positional keyword to target agents, or --all to include both:

skillshare trash list                    # Skills only (default)
skillshare trash agents list             # Agents only
skillshare trash --all list              # Both skills and agents
skillshare trash agents restore tutor    # Restore a trashed agent
skillshare trash agents empty            # Empty agent trash only

Subcommands

list (alias: ls)

Show all items currently in the trash. Launches the interactive TUI in a terminal, or prints plain text with --no-tui or in non-TTY:

skillshare trash list
skillshare trash agents list
skillshare trash --all list --no-tui

Plain text output:

Trash
  my-skill      1.2 KB · 2d ago
  old-helper    800 B · 5d ago

2 items, 2.0 KB
  Each item is removed for good 7 days after it was trashed

restore

Restore the most recent trashed version back to the source directory:

skillshare trash restore my-skill
skillshare trash agents restore tutor
✓ Restore   my-skill → ~/.config/skillshare/skills · trashed 2d ago

Next
  skillshare sync  link it into your targets again

For agents, the restore hint will suggest skillshare sync agents instead.

Folders under replaced-by-init/<tool>/ are the exception: init put them there when it replaced a tool's folder with a link, and the source already holds the same skill, so restore refuses them. Copy one back from the trash folder by hand if you need it.

Restore also brings back what the install recorded: a skill, tracked repo or agent installed from GitHub or another remote keeps its source, so update and check still work. Items trashed by an older version come back as local.

A trashed source link is listed as link → <target> and restored as a link (or junction) again, never as a copy of its target. A skill trashed from behind a followed link (_dev-skills/foo) is restored into the real checkout when follow_source_links is on; the restore fails and keeps the trash entry when the setting is off or a nested link below the checkout leads elsewhere.

If an item with the same name already exists in source, restore will fail. Uninstall the existing item first or use a different name.

delete (alias: rm)

Permanently delete a single item from the trash:

skillshare trash delete my-skill
skillshare trash agents delete tutor
✓ Permanently deleted my-skill

empty

Permanently delete all items from the trash (with confirmation prompt):

skillshare trash empty
skillshare trash agents empty
! This will permanently delete 3 items from trash
? Continue? [y/N] y
✓ Emptied trash: 3 items permanently deleted · 0.1s

Backup vs Trash

These two safety mechanisms protect different things:

backup trash
Protects target directories (sync snapshots) source skills and agents (uninstall)
Location ~/.local/share/skillshare/backups/ ~/.local/share/skillshare/trash/ (skills), .../trash/agents/ (agents)
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
agents Positional keyword — operate on agents instead of skills
--all Include both skills and agents
--no-tui Disable interactive TUI, use plain text output
--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.

See Also

  • uninstall — Remove skills (moves to trash)
  • backup — Backup target directories
  • restore — Restore targets from backup