lshed 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.3.0 — 2026-09-02
+
+Claude Code plugins are packages now. On the machine this was built against, the five installed plugins were the only thing a fresh `restore` still left out, and two of them carry MCP servers.
+
+- `init` records each user-scope plugin as `claude-plugin:<name>@<marketplace>` and each GitHub-backed marketplace as `claude-marketplace:<owner/repo>`. Project-scope plugins belong to their project and are skipped.
+- `restore` adds missing marketplaces first, then installs missing plugins through `claude plugin install`. Both are the agent's own package manager, so they run without `--yes`; `--yes` is forwarded as `-y` to accept a marketplace-declared install command.
+- Plugins cannot be pinned. `lshed.lock` records the version that actually got installed and `status` shows when it differs from what another machine had. `update` runs `claude plugin update`.
+- Installers are an interface now. `github:`/`git:` live in core; an adapter contributes its own (`ClaudeCodeAdapter` provides the two above). Install order follows installer priority, then manifest order.
+- Lock entries use `rev` instead of `commit`. Old locks still read.
+
+## 0.2.1 — 2026-09-02
+
+- `lshed list [--unused]` shows everything in the shed and which profiles use it.
+- `lshed remove <key>` deletes a component or package from the shed. Refused while any profile still references it. Packages leave the manifest and lock only; the local clone stays.
+- `lshed prune [--yes]` removes everything no profile uses. Lists without `--yes`.
+- Manifest edits preserve your comments. Empty `packages:` is no longer written.
+
+## 0.2.0 — 2026-09-02
+
+A harness holds three kinds of things, and 0.1 treated them all the same. Running against a real `~/.claude` showed that 55 of 62 "skills" were files generated by one toolkit's installer, and the toolkit itself was a git clone.
+
+- **Packages.** A `packages:` list in `lshed.yaml` records things you *installed* by source and version instead of copying them: `source: github:owner/repo@ref` (or `git:<url>#ref`), `into: <path under the agent root>`, optional `install: <command>`. `restore` clones a missing package at the commit pinned in `lshed.lock`; a package already present is never touched.
+- **Generated files are skipped.** `init` recognises a directory as a package when it contains a `.git` with a remote, and recognises a stub as generated when one of its symlinks points inside a package. Both are left out of the shed and the managed set. Aliases that an installer creates without symlinks are not detected; use `init --exclude`.
+- **`lshed.lock`** pins each package to a commit. Written by `init` from the existing clone, by `restore` on first clone, and by `update`.
+- **`lshed update [ids...]`** fast-forwards packages and refreshes the lock.
+- **Install commands run only with `--yes`.** Without it, `restore` and `update` print the commands and stop. A shed can be cloned from anywhere; running its shell commands should be a deliberate act.
+- `git:` source scheme for non-GitHub remotes.
+
+Packages are additive: switching to a profile that does not list one leaves it on disk. Removing a clone with a backup would mean copying a repository, which is the wrong tool for that job.
+
+## 0.1.1 — 2026-09-02
+
+Both fixes came from running 0.1.0 against a real 62-skill `~/.claude`.
+
+- Skip regenerable directories when copying: `node_modules`, `.git`, `__pycache__`, `.venv`, cache dirs, `*.log`. A real harness went from 1.6 GB to 6.2 MB. Build output such as `dist/` is **not** ignored by default, because for some skills it is the deliverable.
+- Extend the list with `ignore:` in `lshed.yaml`; the same list applies to `diff`, `save` and backups, so ignored files never show up as drift.
+- Follow symlinks. A skill symlinked into `~/.claude/skills` used to be skipped silently; it is now captured and copied by content. Broken links are skipped.
+- `init --exclude <id...>` leaves out components that do not belong in a shed, such as a toolkit with its own installer.
+
 ## 0.1.0 — 2026-09-02
 
 First working release. Claude Code only.

package/README.md

@@ -76,24 +76,82 @@ profiles:
     instructions: [base]
 ```
 
-- `source` accepts `file:<path relative to the shed>`. `github:owner/repo@ref` is parsed and reserved for a future release; using it today is an error, not silent misbehaviour.
+- Component `source` accepts `file:<path relative to the shed>`. Package `source` accepts `github:owner/repo@ref` or `git:<url>#ref`.
 - Category names come from the adapter. For Claude Code: `skills`, `agents`, `commands`, `instructions`.
+- `ignore:` at the top level adds to the built-in list of things never copied: `node_modules`, `.git`, `__pycache__`, `.venv`, cache directories, `*.log`. Build output like `dist/` is not ignored by default, since some skills ship it. Add it yourself if your parts rebuild from source.
 - Instructions are not merged. `restore` writes a `CLAUDE.md` that `@`-imports each fragment in order, so a fragment edit shows up without re-running anything. Your original `CLAUDE.md` is backed up the first time.
 
+## Three kinds of things
+
+A real `~/.claude` mixes three kinds of content, and they need different handling:
+
+| Kind | Example | What lshed does |
+|---|---|---|
+| **Authored** | a skill you wrote, your `CLAUDE.md` | copies it into the shed |
+| **Installed** | a toolkit you `git clone`d, a plugin | records source + commit; `restore` clones it back |
+| **Generated** | stub skills an installer wrote for you | skips them; they return when the installer runs |
+
+`init` sorts this out for you. A directory with a `.git` and a remote becomes a **package**. A skill whose symlink points inside a package is treated as generated and skipped. Everything else is authored and copied.
+
+```yaml
+packages:
+  - id: gstack
+    source: github:garrytan/gstack@main   # git:<url>#ref for other hosts
+    into: skills/gstack                   # where it lives under ~/.claude
+    install: ./setup                      # optional; run after clone, only with --yes
+
+profiles:
+  default:
+    packages: [gstack]
+    skills: [add-drivers, domain-modeling]
+```
+
+`lshed.lock` pins each package to a commit, so a fresh machine gets the same version you had. `lshed update` moves it forward.
+
+Claude Code plugins are packages too, with their own scheme. `init` finds them in `~/.claude/plugins`:
+
+```yaml
+packages:
+  - id: claude-plugins-official
+    source: claude-marketplace:anthropics/claude-plugins-official
+  - id: exa
+    source: claude-plugin:exa@claude-plugins-official
+```
+
+`restore` adds the marketplace, then runs `claude plugin install exa@claude-plugins-official`. Plugins cannot be pinned to a version, so the lock records whatever got installed and `status` tells you when it differs from the machine you came from. Plugins that bundle MCP servers bring them along.
+
+Rules that keep this safe:
+
+- A package that is already present is never touched by `restore`. Your local checkout is yours.
+- `install:` is a shell command. `restore` and `update` **print it and stop** unless you pass `--yes`. Plugin installs go through Claude Code's own package manager and run without it; `--yes` is forwarded as `-y` for plugins that declare an install command.
+- Packages are not part of the managed set. Switching profiles never deletes a clone.
+- Installers sometimes create aliases without symlinks, which `init` cannot tell from authored skills. Leave those out with `--exclude`:
+
+```bash
+lshed init --shed ~/harness --exclude _gstack-command connect-chrome
+```
+
 ## Commands
 
 ```
-lshed init [--shed <dir>] [--profile <name>]   scan the current environment into a shed
-lshed restore [profile] [--dry-run] [--no-backup]
-lshed status                                    applied profile, managed paths, drift
+lshed init [--shed <dir>] [--profile <name>] [--exclude <id...>]
+lshed restore [profile] [--dry-run] [--no-backup] [--yes]
+lshed update [ids...] [--dry-run] [--yes]       pull packages forward, refresh lshed.lock
+lshed status                                    applied profile, managed paths, drift, packages
 lshed diff                                      files that differ between local and shed
 lshed save [ids...]                             copy local edits back into the shed
+lshed list [--unused]                           what is in the shed, and which profiles use it
+lshed remove <key>                              drop a component or package from the shed
+lshed prune [--yes]                             drop everything no profile uses
 ```
 
+`remove` and `prune` delete from the shed without a backup. The shed is meant to live in git; commit before you prune. Both refuse to touch anything a profile still lists, so the way to retire a part is to take it out of the profiles first.
+
 Global options: `--shed <dir>` (or `LSHED_HOME`; after the first restore lshed remembers it), `--root <dir>` (agent config root, default `~/.claude`).
 
 ### What `restore` does
 
+0. Clones any package in the profile that is missing, at the commit in `lshed.lock`.
 1. Removes paths that the **previous** profile placed and the new one doesn't need.
 2. Copies every part of the new profile into place.
 3. Regenerates the instructions file.
@@ -102,7 +160,7 @@ Anything it overwrites or removes is backed up first under `~/.claude/lshed/back
 
 ### Ownership
 
-The shed is the source of truth. `save` copies local edits back for `file:` parts only. Remote parts will be read-only and refreshed with `update` once remote sources land.
+The shed is the source of truth for authored parts: `save` copies local edits back for `file:` components. Packages are owned by their upstream: `update` pulls them, `save` ignores them.
 
 ## Where things live
 
@@ -124,7 +182,8 @@ The shed is the source of truth. `save` copies local edits back for `file:` part
 
 - MCP servers and secrets. Planned: the manifest names the keys, values are injected locally, nothing secret enters the shed.
 - `settings.json` merging (hooks, permissions).
-- Remote sources (`github:`), lock file, `update`, `list --unused`, `prune`.
+- `sync` (a git pull/push wrapper). Use git in the shed directly for now.
+- MCP servers configured by hand in `~/.claude.json`. Plugin-bundled ones are covered.
 - Windows and macOS have not been tested. The code avoids platform-specific paths, but treat 0.1 as Linux/WSL.
 
 ## Troubleshooting