claude-snapshot: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

The repo root is a Claude Code skill (claude-snapshot): portable, secret-free backup / restore / compare of a full Claude Code configuration across OSes. The two scripts are runtime-dependency-free Node ESM with no build step - users install via the plugin and run them directly; nothing is compiled or npm installed on their side. The package.json and node_modules are dev-only tooling (Biome, markdownlint, TypeScript for @ts-check); they never ship to users and the scripts never import them. There is no unit-test framework - verification is done by running the scripts against sandboxes (below).

On the author's machine ~/.claude/skills/claude-snapshot is a junction/symlink to this repo: edits here are live immediately in every Claude Code session. Treat script changes as production changes and verify before considering them done.

Hard invariants (violating these is a bug, not a style issue)

1. Shareability - no username, home path, hostname, or secret may appear anywhere in skill source. Everything machine-specific is discovered at runtime (os.homedir(), CLAUDE_CONFIG_DIR, process.execPath, process.platform/arch) and tokenized in bundles. Before committing: grep -ri "<username>\|C:\\\\Users\|/Users/" --include="*.md" --include="*.mjs" . must return nothing.
2. No secrets in bundles - three layers in collect.mjs: SECRET_KEY_RE (JSON key names), SECRET_VALUE_RE (JSON whole-value vendor formats; generic prefixes anchored, high-entropy vendor prefixes unanchored - a Bearer github_pat_... header once slipped past an anchored regex), and SECRET_TEXT_PATTERNS + redactText() (full-text pass over every collected text file - hooks/memory/markdown, not just JSON; length-qualified so documentation quoting a bare prefix never self-matches). No entropy heuristic by design (git SHAs false-positive). Every redaction is recorded (names/labels only) in EXCLUDED.md.
3. Restore never writes blind - dry-run by default, snapshot-before-write on --apply, conflicts always reported and never auto-resolved (existing values win). Idempotency is a contract: applying the same bundle twice must report all-skip, zero writes.
4. The bundle is untrusted input on restore/extract/compare (it may come from another party or a bare-machine bootstrap). Every manifest field (bundlePath, target, merge) and file body is attacker-controllable. Defenses that MUST hold when touching apply.mjs:
   • Path containment. safeJoin (extract) rejects ../absolute/drive escapes and re-checks isWithin(dest). targetPath resolves + confines every restore target to ALLOWED_TARGET_ROOTS (the CLAUDE_HOME subtree plus exact files ~/.claude.json, ~/CLAUDE.md); out-of-bounds -> rejected, never written. Anything comparing/keying paths uses the tokenized target, not the cosmetic bundlePath.
   • Symlink-safe writes. safeWriteFile refuses a symlink at the final component (wx on create closes the TOCTOU on the create path). Known residual: the existing-file overwrite branch still follows a symlink swapped in by a concurrent local process - out of the bundle threat model, documented, not chased.
   • Prototype-pollution filter. PROTO_KEYS drops __proto__/constructor/prototype at every level of deepMerge and detokenizeJson.
   • Corrupt bundles are rejected up front, not mid-write. Before any planning or write, a container whose manifest.files is missing/not-an-array, or that lists a file with no matching (or non-string-content) record in files, exits with a clean error. An attacker-crafted manifest must not crash readBundle with a raw TypeError after partial work.
   • Executable config is surfaced, not silently applied. Restoring hooks/skills/MCP is the tool's job (can't be blocked), so instead every exec-bearing change is flagged in report.securityWarnings: flagExecKeys for JSON hooks/statusLine/command key additions, an MCP-add warning, and one consolidated summary of new files dropped into exec dirs (hooks/skills/commands/agents/ output-styles). Consolidation is deliberate - per-file warnings on a normal restore (dozens of legit files) are noise that masks a genuinely unexpected drop.
5. Mode names are backup / restore / compare - never mix naming pairs (no "export").