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

generalize runtime ownership with doctor and local skill migration

Browse Source
This commit is contained in:
Jason Woltje
2026-02-17 12:10:06 -06:00
parent 967c9c462b
commit db2ec9524f
25 changed files with 3974 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
bin/mosaic-doctor Executable file
View File

@@ -0,0 +1,201 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
FAIL_ON_WARN=0
VERBOSE=0
usage() {
cat <<USAGE
Usage: $(basename "$0") [options]
Audit Mosaic runtime linkage and detect drift across agent runtimes.
Options:
--fail-on-warn Exit non-zero when warnings are found
--verbose Print pass checks too
-h, --help Show help
USAGE
}
while [[ $# -gt 0 ]]; do
case "$1" in
--fail-on-warn)
FAIL_ON_WARN=1
shift
;;
--verbose)
VERBOSE=1
shift
;;
-h|--help)
usage
exit 0
;;
*)
echo "Unknown argument: $1" >&2
usage >&2
exit 1
;;
esac
done
warn_count=0
warn() {
warn_count=$((warn_count + 1))
echo "[WARN] $*"
}
pass() {
if [[ $VERBOSE -eq 1 ]]; then
echo "[OK] $*"
fi
}
expect_dir() {
local d="$1"
if [[ ! -d "$d" ]]; then
warn "Missing directory: $d"
else
pass "Directory present: $d"
fi
}
expect_file() {
local f="$1"
if [[ ! -f "$f" ]]; then
warn "Missing file: $f"
else
pass "File present: $f"
fi
}
check_tree_links() {
local src_root="$1"
local dst_root="$2"
[[ -d "$src_root" ]] || return
while IFS= read -r -d '' src; do
local rel dst
rel="${src#$src_root/}"
dst="$dst_root/$rel"
if [[ ! -L "$dst" ]]; then
warn "Not symlinked: $dst (expected -> $src)"
continue
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 [[ -z "$dst_real" || -z "$src_real" || "$dst_real" != "$src_real" ]]; then
warn "Drifted link: $dst (expected -> $src)"
else
pass "Linked: $dst"
fi
done < <(find "$src_root" -type f -print0)
}
echo "[mosaic-doctor] Mosaic home: $MOSAIC_HOME"
# Canonical Mosaic checks
expect_file "$MOSAIC_HOME/STANDARDS.md"
expect_dir "$MOSAIC_HOME/guides"
expect_dir "$MOSAIC_HOME/rails"
expect_dir "$MOSAIC_HOME/profiles"
expect_dir "$MOSAIC_HOME/templates/agent"
expect_dir "$MOSAIC_HOME/skills"
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"
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
done
# Skills runtime checks
for runtime_skills in "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.config/opencode/skills"; do
[[ -d "$runtime_skills" ]] || continue
while IFS= read -r -d '' skill; do
name="$(basename "$skill")"
[[ "$name" == .* ]] && continue
target="$runtime_skills/$name"
if [[ ! -e "$target" ]]; then
warn "Missing skill link: $target"
continue
fi
if [[ ! -L "$target" ]]; then
# Runtime-specific local skills are allowed only for hidden/system entries.
warn "Non-symlink skill entry: $target"
continue
fi
target_real="$(readlink -f "$target" 2>/dev/null || true)"
skill_real="$(readlink -f "$skill" 2>/dev/null || true)"
if [[ -z "$target_real" || -z "$skill_real" || "$target_real" != "$skill_real" ]]; then
warn "Drifted skill link: $target (expected -> $skill)"
else
pass "Linked skill: $target"
fi
done < <(find "$MOSAIC_HOME/skills" "$MOSAIC_HOME/skills-local" -mindepth 1 -maxdepth 1 -type d -print0)
done
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")
done
broken_links=0
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"
fi
echo "[mosaic-doctor] warnings=$warn_count"
if [[ $FAIL_ON_WARN -eq 1 && $warn_count -gt 0 ]]; then
exit 1
fi

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

@@ -48,12 +48,23 @@ 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"
for runtime_file in \
CLAUDE.md \
settings.json \
hooks-config.json \
context7-integration.md; do
src="$MOSAIC_HOME/runtime/claude/$runtime_file"
[[ -f "$src" ]] || continue
link_file "$src" "$HOME/.claude/$runtime_file"
done
for qa_script in \
debug-hook.sh \
qa-hook-handler.sh \

87
bin/mosaic-migrate-local-skills Executable file
View File

@@ -0,0 +1,87 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
APPLY=0
usage() {
cat <<USAGE
Usage: $(basename "$0") [--apply]
Migrate runtime-local skill directories (e.g. ~/.claude/skills/jarvis) to Mosaic-managed
skills by replacing local directories with symlinks to ~/.mosaic/skills-local.
Default mode is dry-run.
USAGE
}
while [[ $# -gt 0 ]]; do
case "$1" in
--apply)
APPLY=1
shift
;;
-h|--help)
usage
exit 0
;;
*)
echo "Unknown argument: $1" >&2
usage >&2
exit 1
;;
esac
done
skill_roots=(
"$HOME/.claude/skills"
"$HOME/.codex/skills"
"$HOME/.config/opencode/skills"
)
if [[ ! -d "$MOSAIC_HOME/skills-local" ]]; then
echo "[mosaic-local-skills] Missing local skills dir: $MOSAIC_HOME/skills-local" >&2
exit 1
fi
count=0
while IFS= read -r -d '' local_skill; do
name="$(basename "$local_skill")"
src="$MOSAIC_HOME/skills-local/$name"
[[ -d "$src" ]] || continue
for root in "${skill_roots[@]}"; do
[[ -d "$root" ]] || continue
target="$root/$name"
# Already linked correctly.
if [[ -L "$target" ]]; then
target_real="$(readlink -f "$target" 2>/dev/null || true)"
src_real="$(readlink -f "$src" 2>/dev/null || true)"
if [[ -n "$target_real" && -n "$src_real" && "$target_real" == "$src_real" ]]; then
continue
fi
fi
# Only migrate local directories containing SKILL.md
if [[ -d "$target" && -f "$target/SKILL.md" && ! -L "$target" ]]; then
count=$((count + 1))
if [[ $APPLY -eq 1 ]]; then
stamp="$(date +%Y%m%d%H%M%S)"
mv "$target" "${target}.mosaic-bak-${stamp}"
ln -s "$src" "$target"
echo "[mosaic-local-skills] migrated: $target -> $src"
else
echo "[mosaic-local-skills] would migrate: $target -> $src"
fi
fi
done
done < <(find "$MOSAIC_HOME/skills-local" -mindepth 1 -maxdepth 1 -type d -print0)
if [[ $APPLY -eq 1 ]]; then
echo "[mosaic-local-skills] complete: migrated=$count"
else
echo "[mosaic-local-skills] dry-run: migratable=$count"
echo "[mosaic-local-skills] re-run with --apply to migrate"
fi

4
bin/mosaic-prune-legacy-runtime
View File

@@ -80,12 +80,12 @@ while IFS= read -r -d '' bak; do
count_deletable=$((count_deletable + 1))
if [[ $APPLY -eq 1 ]]; then
rm -f "$bak"
rm -rf "$bak"
echo "[mosaic-prune] deleted: $bak"
else
echo "[mosaic-prune] would delete: $bak"
fi
done < <(find "$TARGET_ROOT" -type f -name '*.mosaic-bak-*' -print0)
done < <(find "$TARGET_ROOT" \( -type f -o -type d \) -name '*.mosaic-bak-*' -print0)
if [[ $APPLY -eq 1 ]]; then
echo "[mosaic-prune] complete: deleted=$count_deletable candidates=$count_candidates runtime=$RUNTIME"

13
bin/mosaic-sync-skills
View File

@@ -5,6 +5,7 @@ MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
SKILLS_REPO_URL="${MOSAIC_SKILLS_REPO_URL:-https://git.mosaicstack.dev/mosaic/agent-skills.git}"
SKILLS_REPO_DIR="${MOSAIC_SKILLS_REPO_DIR:-$MOSAIC_HOME/sources/agent-skills}"
MOSAIC_SKILLS_DIR="$MOSAIC_HOME/skills"
MOSAIC_LOCAL_SKILLS_DIR="$MOSAIC_HOME/skills-local"
fetch=1
link_only=0
@@ -13,10 +14,10 @@ usage() {
cat <<USAGE
Usage: $(basename "$0") [options]
Sync canonical skills into ~/.mosaic/skills and link them into runtime skill directories.
Sync canonical skills into ~/.mosaic/skills and link all Mosaic skills into runtime skill directories.
Options:
--link-only Skip git clone/pull and only relink from ~/.mosaic/skills
--link-only Skip git clone/pull and only relink from ~/.mosaic/{skills,skills-local}
--no-link Sync canonical skills but do not update runtime links
-h, --help Show help
@@ -49,7 +50,7 @@ while [[ $# -gt 0 ]]; do
esac
done
mkdir -p "$MOSAIC_HOME" "$MOSAIC_SKILLS_DIR"
mkdir -p "$MOSAIC_HOME" "$MOSAIC_SKILLS_DIR" "$MOSAIC_LOCAL_SKILLS_DIR"
if [[ $fetch -eq 1 ]]; then
if [[ -d "$SKILLS_REPO_DIR/.git" ]]; then
@@ -134,6 +135,12 @@ for target in "${link_targets[@]}"; do
link_skill_into_target "$skill" "$target"
done < <(find "$MOSAIC_SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d -print0)
if [[ -d "$MOSAIC_LOCAL_SKILLS_DIR" ]]; then
while IFS= read -r -d '' skill; do
link_skill_into_target "$skill" "$target"
done < <(find "$MOSAIC_LOCAL_SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d -print0)
fi
echo "[mosaic-skills] Linked skills into: $target"
done