Update path conventions in documentation and scripts for home-persist feature

Author: chapterjason

docs/migration-guide.md

@@ -180,13 +180,14 @@ declare, list it on `home-persist`:
 
 ```jsonc
 "ghcr.io/sourecode/devcontainer-features/home-persist:1": {
-  "paths": ".gitconfig,.bash_history,.config/my-tool"
+  "paths": ".gitconfig,.bash_history,.config/my-tool/"
 }
 ```
 
-Paths are relative to `$HOME`. On first create, any existing content at
-those paths in the image gets moved into the volume; subsequent creates
-volume-win.
+Paths are relative to `$HOME`. Add a trailing `/` for directories (e.g.
+`.config/my-tool/`), omit it for files (e.g. `.gitconfig`). On first create,
+any existing content at those paths in the image gets moved into the volume;
+subsequent creates volume-win.
 
 ## Where env vars come from
 

docs/persistence.md

@@ -37,16 +37,22 @@ cross-tool leakage between workspaces.
    ```json
    {
      "source": "claude-code",
-     "paths": [".claude", ".claude.json"]
+     "paths": [".claude/", ".claude.json"]
    }
    ```
 
+   **Trailing-slash convention**: a path ending in `/` is a directory; the
+   resolver pre-creates the target so the symlink is never dangling. Use a
+   slash for `.claude/` but not for `.claude.json` (a file). Without this,
+   the first create on an empty volume leaves `~/.claude` as a dangling
+   symlink, and any consumer doing `mkdir -p ~/.claude` fails with EEXIST.
+
    Users can also declare project-local paths via the `paths` option on the
    `home-persist` feature:
 
    ```jsonc
    "ghcr.io/sourecode/devcontainer-features/home-persist:1": {
-     "paths": ".claude,.claude.json,.gitconfig"
+     "paths": ".claude/,.claude.json,.gitconfig"
    }
    ```
 
@@ -105,7 +111,7 @@ Properties that fall out:
 
 | Source         | Paths                         | Why                                          |
 | -------------- | ----------------------------- | -------------------------------------------- |
-| `claude-code`  | `.claude`, `.claude.json`     | Login credentials, sessions, plugins         |
+| `claude-code`  | `.claude/`, `.claude.json`    | Login credentials, sessions, plugins         |
 | `user` (opt-in)| whatever you list             | Project-local additions                      |
 
 Anything not in the declared set is image-owned and resets on rebuild — git
@@ -132,11 +138,13 @@ mkdir -p /etc/devcontainer-persist.d
 cat > /etc/devcontainer-persist.d/my-feature.json <<'EOF'
 {
   "source": "my-feature",
-  "paths": [".my-feature", ".config/my-feature"]
+  "paths": [".my-feature/", ".config/my-feature/", ".my-feature.conf"]
 }
 EOF
 ```
 
+Trailing `/` for directories, no slash for files.
+
 No ordering required — `home-persist`'s `onCreateCommand` runs after all
 features install, so the manifest is always visible by resolve time. Listing
 the same path in two manifests is harmless: the second is logged and

src/claude-code/devcontainer-feature.json

@@ -1,6 +1,6 @@
 {
   "id": "claude-code",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "name": "claude-code",
   "description": "Installs the latest Claude Code CLI via the official native installer, placing the binary in /usr/local/bin. Declares ~/.claude and ~/.claude.json as persistence targets via the home-persist manifest, so credentials, sessions, and plugins survive rebuilds when home-persist is installed.",
   "documentationURL": "https://github.com/SoureCode/devcontainer-features/tree/master/src/claude-code",

src/claude-code/install.sh

@@ -31,6 +31,6 @@ mkdir -p /etc/devcontainer-persist.d
 cat > /etc/devcontainer-persist.d/claude-code.json <<'EOF'
 {
   "source": "claude-code",
-  "paths": [".claude", ".claude.json"]
+  "paths": [".claude/", ".claude.json"]
 }
 EOF

src/home-persist/devcontainer-feature.json

@@ -1,14 +1,14 @@
 {
   "id": "home-persist",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "name": "home-persist",
   "description": "Symlinks selected paths under $HOME into a per-owner persistence volume mounted at /mnt/home-persist. Features and users declare paths via JSON manifests in /etc/devcontainer-persist.d/, and an onCreateCommand materializes the symlinks on every create. Requires the consumer to bind-mount a persistent source to /mnt/home-persist in devcontainer.json.",
   "documentationURL": "https://github.com/SoureCode/devcontainer-features/tree/master/src/home-persist",
   "options": {
     "paths": {
       "type": "string",
       "default": "",
-      "description": "Comma-separated list of paths under $HOME to persist (e.g. '.claude,.claude.json,.gitconfig'). Written to /etc/devcontainer-persist.d/user.json at build time. Leave empty if you only want features to contribute paths."
+      "description": "Comma-separated list of paths under $HOME to persist (e.g. '.claude/,.claude.json,.gitconfig'). A trailing slash marks a directory so the target is pre-created (prevents dangling-symlink errors in consumer scripts like `mkdir -p ~/.claude`). Written to /etc/devcontainer-persist.d/user.json at build time. Leave empty if you only want features to contribute paths."
     }
   },
   "onCreateCommand": "/usr/local/bin/home-persist-resolve"

src/home-persist/resolve.sh

@@ -8,6 +8,13 @@
 #
 # Manifest shape:
 #   { "source": "<label>", "paths": ["<rel-to-$HOME>", ...] }
+#
+# Path convention:
+#   - Trailing slash ("/") means the path is a directory. The target is
+#     pre-created so the symlink is never dangling — avoids `mkdir -p` on
+#     a dangling symlink failing with EEXIST in consumer scripts.
+#   - No trailing slash means the path is a file (or left dangling until
+#     a writer creates it).
 set -euo pipefail
 
 STATE="${HOME_PERSIST_STATE:-/mnt/home-persist}"
@@ -48,8 +55,12 @@ for mf in "${manifests[@]}"; do
     [ -z "$raw" ] && continue
     rel="${raw#\~/}"
     rel="${rel#/}"
+    is_dir=0
+    case "$rel" in
+      */) is_dir=1; rel="${rel%/}" ;;
+    esac
     case "$rel" in
-      *..*) log "rejecting path with .. in $mf: $raw"; continue ;;
+      *..*|"") log "rejecting invalid path in $mf: $raw"; continue ;;
     esac
 
     if [ -n "${owner[$rel]+x}" ]; then
@@ -65,6 +76,13 @@ for mf in "${manifests[@]}"; do
     if [ -e "$link" ] && [ ! -L "$link" ] && [ ! -e "$target" ]; then
       mv "$link" "$target"
     fi
+
+    # Pre-create directory targets so the symlink isn't dangling — consumer
+    # scripts running `mkdir -p ~/<path>` would otherwise hit EEXIST.
+    if [ "$is_dir" = 1 ] && [ ! -e "$target" ]; then
+      mkdir -p "$target"
+    fi
+
     ln -sfn "$target" "$link"
   done < <(jq -r '.paths[]?' "$mf")
 done