mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

drop claude symlink trees for migrated assets

Browse Source
This commit is contained in:
Jason Woltje
2026-02-17 12:20:33 -06:00
parent 947d4e808d
commit a146aa0709
4 changed files with 114 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@@ -48,16 +48,13 @@ Manual commands:
~/.mosaic/bin/mosaic-sync-skills --link-only
```
## Runtime Compatibility Linking
## Runtime Compatibility Sync
Installer also links Claude-compatible paths back to Mosaic canonicals:
Installer syncs Claude runtime overlays as regular files (not symlinks):
- `~/.claude/agent-guides` -> `~/.mosaic/guides`
- `~/.claude/scripts/{git,codex,bootstrap,cicd,portainer}` -> `~/.mosaic/rails/...`
- `~/.claude/templates` -> `~/.mosaic/templates/agent`
- `~/.claude/presets/{domains,tech-stacks,workflows}` -> `~/.mosaic/profiles/...`
- `~/.claude/presets/*.json` runtime overlays -> `~/.mosaic/runtime/claude/settings-overlays/`
- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` -> `~/.mosaic/runtime/claude/...`
- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.mosaic/runtime/claude/...`
Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.
Run manually:

119
bin/mosaic-doctor
View File

@@ -9,7 +9,7 @@ usage() {
cat <<USAGE
Usage: $(basename "$0") [options]
Audit Mosaic runtime linkage and detect drift across agent runtimes.
Audit Mosaic runtime state and detect drift across agent runtimes.
Options:
--fail-on-warn Exit non-zero when warnings are found
@@ -41,16 +41,12 @@ while [[ $# -gt 0 ]]; do
done
warn_count=0
warn() {
warn_count=$((warn_count + 1))
echo "[WARN] $*"
}
warn() { warn_count=$((warn_count + 1)); echo "[WARN] $*"; }
pass() {
if [[ $VERBOSE -eq 1 ]]; then
echo "[OK] $*"
fi
return 0
}
expect_dir() {
@@ -71,32 +67,46 @@ expect_file() {
fi
}
check_tree_links() {
local src_root="$1"
local dst_root="$2"
check_runtime_file_copy() {
local src="$1"
local dst="$2"
[[ -d "$src_root" ]] || return
[[ -f "$src" ]] || return 0
while IFS= read -r -d '' src; do
local rel dst
rel="${src#$src_root/}"
dst="$dst_root/$rel"
if [[ ! -e "$dst" ]]; then
warn "Missing runtime file: $dst"
return
fi
if [[ ! -L "$dst" ]]; then
warn "Not symlinked: $dst (expected -> $src)"
continue
fi
if [[ -L "$dst" ]]; then
warn "Runtime file should not be symlinked: $dst"
return
fi
local dst_real src_real
dst_real="$(readlink -f "$dst" 2>/dev/null || true)"
src_real="$(readlink -f "$src" 2>/dev/null || true)"
if ! cmp -s "$src" "$dst"; then
warn "Runtime file drift: $dst (does not match $src)"
else
pass "Runtime file synced: $dst"
fi
}
if [[ -z "$dst_real" || -z "$src_real" || "$dst_real" != "$src_real" ]]; then
warn "Drifted link: $dst (expected -> $src)"
warn_if_symlink_tree_present() {
local p="$1"
[[ -e "$p" ]] || return 0
if [[ -L "$p" ]]; then
warn "Legacy symlink path still present: $p"
return
fi
if [[ -d "$p" ]]; then
symlink_count=$(find "$p" -type l 2>/dev/null | wc -l | tr -d ' ')
if [[ "$symlink_count" != "0" ]]; then
warn "Legacy symlink entries still present under $p: $symlink_count"
else
pass "Linked: $dst"
pass "No symlinks under legacy path: $p"
fi
done < <(find "$src_root" -type f -print0)
fi
}
echo "[mosaic-doctor] Mosaic home: $MOSAIC_HOME"
@@ -112,37 +122,29 @@ expect_dir "$MOSAIC_HOME/skills-local"
expect_file "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
expect_file "$MOSAIC_HOME/bin/mosaic-sync-skills"
# Claude runtime checks
check_tree_links "$MOSAIC_HOME/guides" "$HOME/.claude/agent-guides"
check_tree_links "$MOSAIC_HOME/rails/git" "$HOME/.claude/scripts/git"
check_tree_links "$MOSAIC_HOME/rails/codex" "$HOME/.claude/scripts/codex"
check_tree_links "$MOSAIC_HOME/rails/bootstrap" "$HOME/.claude/scripts/bootstrap"
check_tree_links "$MOSAIC_HOME/rails/cicd" "$HOME/.claude/scripts/cicd"
check_tree_links "$MOSAIC_HOME/rails/portainer" "$HOME/.claude/scripts/portainer"
check_tree_links "$MOSAIC_HOME/templates/agent" "$HOME/.claude/templates"
check_tree_links "$MOSAIC_HOME/profiles/domains" "$HOME/.claude/presets/domains"
check_tree_links "$MOSAIC_HOME/profiles/tech-stacks" "$HOME/.claude/presets/tech-stacks"
check_tree_links "$MOSAIC_HOME/profiles/workflows" "$HOME/.claude/presets/workflows"
check_tree_links "$MOSAIC_HOME/runtime/claude/settings-overlays" "$HOME/.claude/presets"
# Claude runtime file checks (copied, non-symlink).
for rf in CLAUDE.md settings.json hooks-config.json context7-integration.md; do
src="$MOSAIC_HOME/runtime/claude/$rf"
dst="$HOME/.claude/$rf"
[[ -f "$src" ]] || continue
if [[ ! -L "$dst" ]]; then
warn "Not symlinked: $dst (expected -> $src)"
continue
fi
dst_real="$(readlink -f "$dst" 2>/dev/null || true)"
src_real="$(readlink -f "$src" 2>/dev/null || true)"
if [[ -z "$dst_real" || -z "$src_real" || "$dst_real" != "$src_real" ]]; then
warn "Drifted link: $dst (expected -> $src)"
else
pass "Linked: $dst"
fi
check_runtime_file_copy "$MOSAIC_HOME/runtime/claude/$rf" "$HOME/.claude/$rf"
done
# Skills runtime checks
# Legacy migration surfaces should no longer contain symlink trees.
legacy_paths=(
"$HOME/.claude/agent-guides"
"$HOME/.claude/scripts/git"
"$HOME/.claude/scripts/codex"
"$HOME/.claude/scripts/bootstrap"
"$HOME/.claude/scripts/cicd"
"$HOME/.claude/scripts/portainer"
"$HOME/.claude/templates"
"$HOME/.claude/presets/domains"
"$HOME/.claude/presets/tech-stacks"
"$HOME/.claude/presets/workflows"
)
for p in "${legacy_paths[@]}"; do
warn_if_symlink_tree_present "$p"
done
# Skills runtime checks (still symlinked into runtime-specific skills dirs).
for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.config/opencode/skills"; do
[[ -d "$runtime_skills" ]] || continue
@@ -157,7 +159,6 @@ for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.confi
fi
if [[ ! -L "$target" ]]; then
# Runtime-specific local skills are allowed only for hidden/system entries.
warn "Non-symlink skill entry: $target"
continue
fi
@@ -172,16 +173,12 @@ for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.confi
done < <(find "$MOSAIC_HOME/skills" "$MOSAIC_HOME/skills-local" -mindepth 1 -maxdepth 1 -type d -print0)
done
# Broken links only in managed runtime skill dirs.
link_roots=(
"$HOME/.claude/agent-guides"
"$HOME/.claude/scripts"
"$HOME/.claude/templates"
"$HOME/.claude/presets"
"$HOME/.claude/skills"
"$HOME/.codex/skills"
"$HOME/.config/opencode/skills"
)
existing_link_roots=()
for d in "${link_roots[@]}"; do
[[ -e "$d" ]] && existing_link_roots+=("$d")
@@ -192,7 +189,7 @@ if [[ ${#existing_link_roots[@]} -gt 0 ]]; then
broken_links=$(find "${existing_link_roots[@]}" -xtype l 2>/dev/null | wc -l | tr -d ' ')
fi
if [[ "$broken_links" != "0" ]]; then
warn "Broken symlinks detected across runtimes: $broken_links"
warn "Broken skill symlinks detected: $broken_links"
fi
echo "[mosaic-doctor] warnings=$warn_count"

97
bin/mosaic-link-runtime-assets
View File

@@ -2,59 +2,74 @@
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
backup_stamp="$(date +%Y%m%d%H%M%S)"
link_file() {
copy_file_managed() {
local src="$1"
local dst="$2"
mkdir -p "$(dirname "$dst")"
if [[ -L "$dst" ]]; then
local cur
cur="$(readlink -f "$dst" 2>/dev/null || true)"
local want
want="$(readlink -f "$src" 2>/dev/null || true)"
if [[ -n "$cur" && -n "$want" && "$cur" == "$want" ]]; then
rm -f "$dst"
fi
if [[ -f "$dst" ]]; then
if cmp -s "$src" "$dst"; then
return
fi
rm -f "$dst"
elif [[ -e "$dst" ]]; then
mv "$dst" "${dst}.mosaic-bak-${backup_stamp}"
fi
ln -s "$src" "$dst"
cp "$src" "$dst"
}
link_tree_files() {
local src_root="$1"
local dst_root="$2"
remove_legacy_path() {
local p="$1"
[[ -d "$src_root" ]] || return
if [[ -L "$p" ]]; then
rm -f "$p"
return
fi
while IFS= read -r -d '' src; do
local rel
rel="${src#$src_root/}"
local dst="$dst_root/$rel"
link_file "$src" "$dst"
done < <(find "$src_root" -type f -print0)
if [[ -d "$p" ]]; then
find "$p" -depth -type l -delete 2>/dev/null || true
find "$p" -depth -type d -empty -delete 2>/dev/null || true
return
fi
# Remove stale symlinked files if present.
if [[ -e "$p" && -L "$p" ]]; then
rm -f "$p"
fi
}
# Claude compatibility layer: keep existing ~/.claude workflows functional,
# but source canonical rails from ~/.mosaic.
link_tree_files "$MOSAIC_HOME/guides" "$HOME/.claude/agent-guides"
link_tree_files "$MOSAIC_HOME/rails/git" "$HOME/.claude/scripts/git"
link_tree_files "$MOSAIC_HOME/rails/codex" "$HOME/.claude/scripts/codex"
link_tree_files "$MOSAIC_HOME/rails/bootstrap" "$HOME/.claude/scripts/bootstrap"
link_tree_files "$MOSAIC_HOME/rails/cicd" "$HOME/.claude/scripts/cicd"
link_tree_files "$MOSAIC_HOME/rails/portainer" "$HOME/.claude/scripts/portainer"
link_tree_files "$MOSAIC_HOME/templates/agent" "$HOME/.claude/templates"
link_tree_files "$MOSAIC_HOME/profiles/domains" "$HOME/.claude/presets/domains"
link_tree_files "$MOSAIC_HOME/profiles/tech-stacks" "$HOME/.claude/presets/tech-stacks"
link_tree_files "$MOSAIC_HOME/profiles/workflows" "$HOME/.claude/presets/workflows"
link_tree_files "$MOSAIC_HOME/runtime/claude/settings-overlays" "$HOME/.claude/presets"
# Remove compatibility symlink surfaces for migrated content.
legacy_paths=(
"$HOME/.claude/agent-guides"
"$HOME/.claude/scripts/git"
"$HOME/.claude/scripts/codex"
"$HOME/.claude/scripts/bootstrap"
"$HOME/.claude/scripts/cicd"
"$HOME/.claude/scripts/portainer"
"$HOME/.claude/scripts/debug-hook.sh"
"$HOME/.claude/scripts/qa-hook-handler.sh"
"$HOME/.claude/scripts/qa-hook-stdin.sh"
"$HOME/.claude/scripts/qa-hook-wrapper.sh"
"$HOME/.claude/scripts/qa-queue-monitor.sh"
"$HOME/.claude/scripts/remediation-hook-handler.sh"
"$HOME/.claude/templates"
"$HOME/.claude/presets/domains"
"$HOME/.claude/presets/tech-stacks"
"$HOME/.claude/presets/workflows"
"$HOME/.claude/presets/jarvis-ralph.json"
)
for p in "${legacy_paths[@]}"; do
remove_legacy_path "$p"
done
# Runtime files are synced as regular files (not symlinks) to reduce path confusion.
for runtime_file in \
CLAUDE.md \
settings.json \
@@ -62,20 +77,8 @@ for runtime_file in \
context7-integration.md; do
src="$MOSAIC_HOME/runtime/claude/$runtime_file"
[[ -f "$src" ]] || continue
link_file "$src" "$HOME/.claude/$runtime_file"
copy_file_managed "$src" "$HOME/.claude/$runtime_file"
done
for qa_script in \
debug-hook.sh \
qa-hook-handler.sh \
qa-hook-stdin.sh \
qa-hook-wrapper.sh \
qa-queue-monitor.sh \
remediation-hook-handler.sh; do
src="$MOSAIC_HOME/rails/qa/$qa_script"
[[ -f "$src" ]] || continue
link_file "$src" "$HOME/.claude/scripts/$qa_script"
done
echo "[mosaic-link] Runtime compatibility assets linked"
echo "[mosaic-link] Runtime assets synced (non-symlink mode)"
echo "[mosaic-link] Canonical source: $MOSAIC_HOME"

2
profiles/README.md
View File

@@ -19,4 +19,4 @@ Current runtime overlay example:
## Claude Compatibility
`mosaic-link-runtime-assets` links these into `~/.claude/presets/*` so existing Claude flows keep working while `~/.mosaic` remains canonical.
`mosaic-link-runtime-assets` prunes legacy preset symlink trees from `~/.claude` so Mosaic remains canonical and Claude uses runtime overlays that reference Mosaic paths directly.