lshed 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.0 — 2026-09-03
+
+Hand-configured MCP servers travel with the profile. Secret values do not.
+
+- New category `mcp` for Claude Code: each user-scope server in `~/.claude.json` becomes `mcp/<name>.json` in the shed. `restore` writes only `mcpServers.<name>` and leaves the rest of the file (machine ID, session state, servers you added by hand) untouched. The file is replaced atomically.
+- `init` masks values under `env` and `headers` whose key looks like a secret with `${VAR}` (`EXA_API_KEY` → `${EXA_API_KEY}`, `Authorization: Bearer …` → `Bearer ${NOTION_AUTHORIZATION}`). Claude Code expands `${VAR}` from the environment in every scope, so `restore` places the placeholder verbatim and no secret passes through lshed. Verified against the real binary.
+- `restore` and `status` list the variables a profile needs that are not set in the current shell.
+- `diff` shows entry changes by key path; `save` keeps placeholders that still match and masks newly added secret-looking keys.
+- Profile switches remove only the servers lshed placed, backing each up as JSON.
+- Adapter interface: `entries()` returns categories that live as JSON entries instead of files, with `secretKeys` and `expandsEnv` policy. The default root honours `CLAUDE_CONFIG_DIR`.
+- Managed-set paths for entries are written as `mcp:<name>`; a colon cannot appear in a path segment, so they never collide with files.
+
+## 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.

package/README.md

@@ -64,12 +64,15 @@ components:
   instructions:
     - id: base                    # file:./instructions/base.md
     - id: research-style
+  mcp:
+    - id: exa                     # file:./mcp/exa.json — secrets replaced by ${VAR}
 
 profiles:
   research:
     skills: [paper-review]
     agents: [reviewer]
     instructions: [base, research-style]    # order matters
+    mcp: [exa]
   teaching:
     skills: [grading-helper]
     commands: [summarize]
@@ -77,10 +80,25 @@ profiles:
 ```
 
 - 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`.
+- Category names come from the adapter. For Claude Code: `skills`, `agents`, `commands`, `instructions`, `mcp`.
 - `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.
 
+## MCP servers and secrets
+
+User-scope MCP servers live in `~/.claude.json`, next to machine IDs and session state. lshed treats each server as a component of category `mcp`: the shed holds `mcp/<name>.json`, and `restore` edits only the `mcpServers.<name>` key of `~/.claude.json`, leaving everything else in that file alone.
+
+**No secret value enters the shed.** `init` replaces values under `env` and `headers` whose key looks like a secret (`key`, `token`, `secret`, `pass`, `auth`, `credential`, `cookie`, `session`) with a `${VAR}` placeholder:
+
+```json
+{ "type": "stdio", "command": "npx", "args": ["-y", "exa-mcp-server"],
+  "env": { "EXA_API_KEY": "${EXA_API_KEY}" } }
+{ "type": "http", "url": "https://mcp.notion.com/mcp",
+  "headers": { "Authorization": "Bearer ${NOTION_AUTHORIZATION}" } }
+```
+
+`restore` writes the placeholder as is. Claude Code expands `${VAR}` from the environment when it starts the server, so the value only ever lives in your shell (`export EXA_API_KEY=...` in `~/.zshrc`, or however you manage secrets). `restore` and `status` list the variables the profile needs that are not set. The heuristic is a suggestion: edit the JSON in the shed to add or remove placeholders, and `init` warns when something in `args` or `url` looks like a token. `save` keeps existing placeholders and masks new secret-looking keys, so a rotated key never leaks into the shed by accident.
+
 ## Three kinds of things
 
 A real `~/.claude` mixes three kinds of content, and they need different handling:
@@ -108,10 +126,22 @@ profiles:
 
 `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`.
+- `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`:
 
@@ -156,22 +186,24 @@ The shed is the source of truth for authored parts: `save` copies local edits ba
 <shed>/
   lshed.yaml
   skills/<id>/            agents/<id>.md        commands/<id>.md        instructions/<id>.md
+  mcp/<id>.json                                 ← secrets as ${VAR}
 
 ~/.claude/
   skills/ agents/ commands/ CLAUDE.md           ← placed by restore
+~/.claude.json  mcpServers.<id>                 ← one key per mcp component; the rest of the file is untouched
   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.
+`state.json` is per machine and is not part of the shed. If `CLAUDE_CONFIG_DIR` is set, lshed uses it as the root and expects `.claude.json` inside it, as Claude Code does.
 
 ## Not in scope (yet)
 
-- MCP servers and secrets. Planned: the manifest names the keys, values are injected locally, nothing secret enters the shed.
+- Secrets beyond "name the variable". Encrypted values, `op://` references and OS keychains are possible later; today lshed is deliberately no better than dotfiles here.
+- Project-scope MCP servers (`.mcp.json`, `~/.claude.json` `projects.*`). They belong to the project.
 - `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