lshed 0.0.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 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.
+
+- `init` scans `~/.claude` (skills, agents, commands, CLAUDE.md) into a shed and writes `lshed.yaml`
+- `restore <profile>` with managed-set semantics, backups on by default, `--dry-run`
+- `status`, `diff`, `save`
+- Instructions are assembled as an `@`-import list, not merged
+- `file:` sources only; `github:` is parsed but rejected until 0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leesongheon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# lshed
+
+Keep your coding-agent harness — skills, subagents, commands, instructions — in a **shed**, and restore it on any machine with one command.
+
+```
+lshed init --shed ~/lshed          # scan ~/.claude into a shed + write lshed.yaml
+lshed restore research             # apply a profile anywhere
+```
+
+The shed is a plain directory. Put it in a git repo, Dropbox, whatever. lshed does not sync it for you.
+
+## Why
+
+Every new laptop, server, container or WSL box means setting up `~/.claude` again. dotfiles tools move **files**; they don't know what a skill, an agent or an instruction fragment is, they can't compose a subset per machine, and they can't tell which parts they placed and which were yours.
+
+lshed adds three first-class ideas on top of "a directory in git":
+
+| Idea | What it gives you |
+|---|---|
+| **Components** | every skill / agent / command / instruction fragment is one named part in the shed |
+| **Profiles** | named recipes — `research`, `work`, `minimal` — that pick a subset of parts |
+| **Managed set** | lshed remembers what it placed, so switching profiles removes only its own files and never touches yours |
+
+Currently supports **Claude Code** (`~/.claude`). Other agents plug in through an adapter.
+
+## Install
+
+```
+npm install -g lshed
+```
+
+Node 20 or newer.
+
+## Quick start
+
+```bash
+# 1. On the machine that already has your setup
+lshed init --shed ~/lshed
+cd ~/lshed && git init && git add -A && git commit -m "my harness" && git remote add origin <your private repo> && git push -u origin main
+
+# 2. Edit ~/lshed/lshed.yaml — add profiles, drop parts you don't need everywhere
+
+# 3. On any other machine
+git clone <your private repo> ~/lshed
+lshed restore research --shed ~/lshed      # --shed only needed the first time
+```
+
+## The manifest
+
+`lshed.yaml` lives at the root of the shed. `init` generates it; edit it by hand from then on.
+
+```yaml
+version: 1
+agent: claude-code
+
+components:
+  skills:
+    - id: paper-review            # source defaults to file:./skills/paper-review
+    - id: grading-helper
+  agents:
+    - id: reviewer                # file:./agents/reviewer.md
+  commands:
+    - id: summarize
+  instructions:
+    - id: base                    # file:./instructions/base.md
+    - id: research-style
+
+profiles:
+  research:
+    skills: [paper-review]
+    agents: [reviewer]
+    instructions: [base, research-style]    # order matters
+  teaching:
+    skills: [grading-helper]
+    commands: [summarize]
+    instructions: [base]
+```
+
+- 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.
+
+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`.
+- 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>] [--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.
+
+Anything it overwrites or removes is backed up first under `~/.claude/lshed/backups/<timestamp>/`, unless you pass `--no-backup`. Files lshed never placed are left alone. `--dry-run` prints the plan and writes nothing.
+
+### Ownership
+
+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
+
+```
+<shed>/
+  lshed.yaml
+  skills/<id>/            agents/<id>.md        commands/<id>.md        instructions/<id>.md
+
+~/.claude/
+  skills/ agents/ commands/ CLAUDE.md           ← placed by restore
+  lshed/state.json                              ← which profile, which paths are managed
+  lshed/instructions/<id>.md                    ← fragments imported by CLAUDE.md
+  lshed/backups/<timestamp>/                    ← whatever restore replaced
+```
+
+`state.json` is per machine and is not part of the shed.
+
+## Not in scope (yet)
+
+- MCP servers and secrets. Planned: the manifest names the keys, values are injected locally, nothing secret enters the shed.
+- `settings.json` merging (hooks, permissions).
+- `sync` (a git pull/push wrapper). Use git in the shed directly for now.
+- Plugins installed through Claude Code's marketplace. They are packages too; recording them is next.
+- Windows and macOS have not been tested. The code avoids platform-specific paths, but treat 0.1 as Linux/WSL.
+
+## Troubleshooting
+
+- **"창고 위치를 모릅니다"** — pass `--shed <dir>` or set `LSHED_HOME`. After one successful `restore`, lshed remembers it.
+- **restore replaced my `CLAUDE.md`** — it is in `~/.claude/lshed/backups/<timestamp>/CLAUDE.md`. Move its content into a fragment in the shed and add that fragment to your profile.
+- **I edited a skill locally and want to keep it** — `lshed diff` to see, `lshed save <id>` to push it into the shed, then commit the shed.
+
+## License
+
+MIT