Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions components/cloud-environment/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,8 @@ distrusted root is a distinct `WARN`/notice line, never conflated with

## Repo bootstrap handoff

After the parallel toolchain tracks finish, the script runs the resolved
After the parallel toolchain tracks finish and the
[fleet plugin install](#plugin-install) has run, the script runs the resolved
checkout's committed `.claude/cloud-bootstrap.sh`, best-effort, with
`CLAUDE_CODE_REMOTE=true`, `CLAUDE_PROJECT_DIR` set to the checkout root,
and the checkout root as the working directory.
Expand All @@ -58,7 +59,7 @@ its next cache rebuild (see [Update lifecycle](#update-lifecycle)).

## Plugin install

After the repo bootstrap, a generic, data-driven stage installs plugins from
Before the repo bootstrap, a generic, data-driven stage installs plugins from
one settings-shaped file: **the fleet list**,
[`fleet-plugins.json`](fleet-plugins.json) beside this script, the one place
the organization's cloud plugin set is declared. The script fetches it from
Expand All @@ -72,9 +73,15 @@ repo-agnostic.
A repo's own `.claude/settings.json` carries only the deltas it declares
beyond the fleet (an extra marketplace, a plugin beyond the fleet, or a
`false` opt-out, which project scope applies over the user-scope install).
Those are not installed here: each repo's session bootstrap applies them as
an overlay on top of this list, from the snapshot copy, at session start (see
the [cloud-bootstrap component](../cloud-bootstrap/README.md)).
Those are not installed by this stage: the
[repo bootstrap](#repo-bootstrap-handoff) that runs next applies them as an
overlay on top of this list, from the snapshot copy (see the
[cloud-bootstrap component](../cloud-bootstrap/README.md)). That is why this
stage runs first — the bootstrap's plugin step skips outright when the fleet
list is absent, so a bootstrap running before the fetch would bake no deltas
at all and leave them to arrive only when the session bootstrap re-runs and
the operator resumes. The same bootstrap still runs at session start, where
it repairs drift between the snapshot and the repo's current declarations.

`extraKnownMarketplaces` entries are registered (`claude plugin marketplace
add`, skipping ones already registered) and every `enabledPlugins` entry set
Expand Down
71 changes: 39 additions & 32 deletions components/cloud-environment/setup.sh
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
# interleaves; the main shell's LOG is untouched by design.
set -u

SCRIPT_VERSION='2026-09-07.2'
SCRIPT_VERSION='2026-09-08.1'
STAMP='/opt/melodic-env-setup.done'
STAMP_FALLBACK='/tmp/melodic-env-setup.done'
# Fleet plugin list: the one standards-hosted, settings-shaped file every
Expand Down Expand Up @@ -316,37 +316,18 @@ for track in "A gh + powershell|$track_a_log" \
rm -f "$track_file" 2>/dev/null
done

# Bake the checked-out repo's committed bootstrap (.claude/cloud-bootstrap.sh
# under the resolved repo root) into the cached snapshot. One name, no
# fallbacks: every fleet repo commits its generic repository setup —
# dependencies and plugin installs — there. Running it here is load-bearing
# for plugins: the session's plugin registry is built at process start and
# never re-read, so plugin installs must land at cache build, not
# mid-session.
if [[ -z "$REPO_ROOT" ]]; then
log 'repo bootstrap skipped: repo root unresolved (see WARN above); nothing baked'
elif [[ -f "$REPO_ROOT/.claude/cloud-bootstrap.sh" ]]; then
if (cd "$REPO_ROOT" &&
CLAUDE_CODE_REMOTE=true CLAUDE_PROJECT_DIR="$REPO_ROOT" \
bash .claude/cloud-bootstrap.sh) >>"$LOG" 2>&1; then
log 'repo bootstrap .claude/cloud-bootstrap.sh baked'
else
log 'WARN repo bootstrap .claude/cloud-bootstrap.sh failed (see log)'
fi
else
# Unambiguous no-op: the root WAS resolved, the repo just has no bootstrap.
# The unresolved-root case logs its own distinct line above.
log "repo root resolved to $REPO_ROOT, no bootstrap present (.claude/cloud-bootstrap.sh) — expected no-op"
fi

# Generic plugin install from one settings-shaped file (extraKnownMarketplaces
# + enabledPlugins): the fleet list at FLEET_PLUGINS_URL, which every snapshot
# installs whatever repo it was built for. No repo-specific logic — a repo's
# own enabledPlugins block declares deltas beyond the fleet and the session
# bootstrap applies them as an overlay, so the snapshot itself stays the same
# for every repo built against it. This must happen here, at cache build:
# own enabledPlugins block declares deltas beyond the fleet and the repo
# bootstrap below applies them as an overlay, so the snapshot itself stays the
# same for every repo built against it. This must happen here, at cache build:
# Claude Code reads its plugin registry at process start and never re-reads
# it, so only snapshot-baked installs are loaded at a session's first turn.
# It must also happen BEFORE the repo bootstrap: that bootstrap's plugin stage
# reads this fetched list and skips outright when it is absent, so a bootstrap
# that ran first would bake none of the repo's deltas and leave them to arrive
# on a later resume.
# Github-source marketplaces' install/update semantics already handle
# versions — no snapshot-refresh logic here (the commit-drift refresh in
# claude-code-plugins' own hook is specific to its directory-source
Expand All @@ -357,11 +338,11 @@ elif ! command -v jq >/dev/null 2>&1; then
log 'plugins: jq not available; skipping'
else
# The fetched copy lands in the snapshot (FLEET_PLUGINS, or its /tmp
# fallback with a WARN, mirroring the stamp) so the per-repo bootstrap's
# drift repair reads the same list offline. A fetch failure costs this
# build's plugin install, never the build: the next rebuild fetches again,
# and a session on a snapshot without the list installs nothing rather than
# guessing at a set.
# fallback with a WARN, mirroring the stamp) so the repo bootstrap below —
# and every later drift repair it runs on resume — reads the same list
# offline. A fetch failure costs this build's plugin install, never the
# build: the next rebuild fetches again, and a session on a snapshot without
# the list installs nothing rather than guessing at a set.
rm -f "$FLEET_PLUGINS" "$FLEET_PLUGINS_FALLBACK" 2>/dev/null
if curl -fsSL --proto '=https' --retry 2 --retry-delay 3 \
"$FLEET_PLUGINS_URL" -o "$FLEET_PLUGINS_FALLBACK" >>"$LOG" 2>&1 &&
Expand All @@ -381,6 +362,32 @@ else
fi
fi

# Bake the checked-out repo's committed bootstrap (.claude/cloud-bootstrap.sh
# under the resolved repo root) into the cached snapshot. One name, no
# fallbacks: every fleet repo commits its generic repository setup —
# dependencies and plugin installs — there. Running it here is load-bearing
# for plugins: the session's plugin registry is built at process start and
# never re-read, so plugin installs must land at cache build, not mid-session.
# It runs AFTER the fleet install above so its plugin stage finds the fetched
# fleet list and overlays the repo's own deltas onto it — that is what makes
# those deltas live at a session's first turn instead of only after the
# session bootstrap re-runs and the operator resumes.
if [[ -z "$REPO_ROOT" ]]; then
log 'repo bootstrap skipped: repo root unresolved (see WARN above); nothing baked'
elif [[ -f "$REPO_ROOT/.claude/cloud-bootstrap.sh" ]]; then
if (cd "$REPO_ROOT" &&
CLAUDE_CODE_REMOTE=true CLAUDE_PROJECT_DIR="$REPO_ROOT" \
bash .claude/cloud-bootstrap.sh) >>"$LOG" 2>&1; then
log 'repo bootstrap .claude/cloud-bootstrap.sh baked'
else
log 'WARN repo bootstrap .claude/cloud-bootstrap.sh failed (see log)'
fi
else
# Unambiguous no-op: the root WAS resolved, the repo just has no bootstrap.
# The unresolved-root case logs its own distinct line above.
log "repo root resolved to $REPO_ROOT, no bootstrap present (.claude/cloud-bootstrap.sh) — expected no-op"
fi

# Temp-file hygiene: without this the fetched installers — and this script
# itself, which the environment bootstrap curls to /tmp — persist into the
# snapshot and show up in every live session. Runs after the repo bootstrap,
Expand Down
25 changes: 20 additions & 5 deletions components/cloud-environment/setup.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -153,18 +153,33 @@ assert_contains 'README bootstrap URL matches the component path' \
"$(cat "$readme")" \
'raw.githubusercontent.com/melodic-software/standards/main/components/cloud-environment/setup.sh'

# The build installs from the fleet list alone. A repo's enabledPlugins block
# is a deltas overlay applied by the session bootstrap's drift repair, so no
# call here may install from the checkout's settings file: reintroducing one
# would make the snapshot repo-specific again and resurrect the block as a
# whole-set install source.
# This script installs from the fleet list alone. A repo's enabledPlugins block
# is a deltas overlay the repo's own bootstrap applies, so no call here may
# install from the checkout's settings file: reintroducing one would make the
# snapshot repo-specific again and resurrect the block as a whole-set install
# source.
# shellcheck disable=SC2016 # the $ is a literal in the needle
assert_not_contains 'setup.sh does not install from the checkout settings block' \
"$(cat "$script")" 'install_plugins_from "$settings"'
# shellcheck disable=SC2016 # the $ is a literal in the needle
assert_not_contains 'setup.sh does not resolve the checkout settings block for install' \
"$(cat "$script")" 'settings="$REPO_ROOT/.claude/settings.json"'

# Ordering contract: the fleet install must precede the repo bootstrap. The
# repo bootstrap applies the repo's deltas as an overlay on the fleet list and
# skips entirely when that list is absent, so a bootstrap that runs first bakes
# no deltas into the snapshot and the repo's own plugins go live only on the
# next resume.
# shellcheck disable=SC2016 # the $ is a literal in the grep needle
fleet_install_ln="$(grep -n -F 'install_plugins_from "$fleet_file" fleet' "$script" | head -n 1 | cut -d: -f1)"
repo_bootstrap_ln="$(grep -n -F 'bash .claude/cloud-bootstrap.sh' "$script" | head -n 1 | cut -d: -f1)"
if [[ -n "$fleet_install_ln" && -n "$repo_bootstrap_ln" && "$fleet_install_ln" -lt "$repo_bootstrap_ln" ]]; then
pass 'fleet plugin install runs before the repo bootstrap'
else
fail 'fleet plugin install runs before the repo bootstrap' \
"fleet install at line '${fleet_install_ln:-none}', repo bootstrap at line '${repo_bootstrap_ln:-none}'"
fi

# Spawn census for install_plugins_from: two sources must share one
# marketplace list and one plugin list, the memoization cloud-bootstrap.sh
# relies on when it reads the fleet list and then the repo overlay. Sourced
Expand Down