Merge origin/main into the Oct 8 triage wave

# Conflicts:
#	CHANGELOG.md
#	VERSION
#	agents-digest/gstack-AGENTS.md
#	package.json
This commit is contained in:
garrytan committed 2026-10-08 16:25:08 +00:00
commit 10d845ab4d
30 files changed
+1079 -131

No files matched your search

+2
View File
@@ -39,6 +39,8 @@ lib/cso/images/gstack-cso-preparation
.hermes/
.gbrain/
.gbrain-source
# Hosts installed from this checkout (bin/gstack-host-renders.sh, #1694)
.gstack-installed-hosts
.context/
extension/.auth.json
# xterm assets are vendored from npm at build time; not source-of-truth.
+41 -1
View File
@@ -1,6 +1,6 @@
# Changelog
## [1.91.63.0] - 2026-10-08
## [1.91.66.0] - 2026-10-08
**/autoplan no longer asks permission to read its own files after a background reviewer finishes.**
**34 contributor PRs from the outside-PR backlog land in this release, rewritten on current code with credit.**
@@ -73,6 +73,46 @@ Both are tracked in TODOS.md.
- The paid `autoplan-guard-pty` case asserts zero permission cards across a background reviewer's notice turn.
- TODOS.md gains "Parked contributor ideas (Oct 8 triage)", which keeps 35 parked PRs grouped by theme with their authors.
## [1.91.65.0] - 2026-10-08
**A gstack install carries skills only for the agents you installed: a global Claude install drops from 632 SKILL.md files (34.7 MB) to 63 (2.5 MB).**
**Codex and the other non-Claude agents get every file their skills read, instead of failing those reads silently.**
`./setup` rendered every agent's copy of the skills inside the install (#1694). A global Claude install at `~/.claude/skills/gstack` held Codex, Factory, Kiro, OpenCode, Cursor, Copilot, Slate, OpenClaw, Hermes and GBrain renders next to its own skills. Claude Code and Cursor-agent scan that tree, and Cursor-agent freezes above about 11 MB of skill files. Separately, the runtime directories setup builds for Codex, Factory, Kiro, OpenCode, Cursor and Copilot were missing files the skills read on demand: the jargon list, the question registry, the AskUserQuestion guides, the review checklists, the DX Hall of Fame and more (#1077's remaining part).
### The numbers that matter
Measured on Linux with a sandboxed HOME, installing from a fresh clone of the commit before this release (4637fae) and of this branch. The setup builds were real; Chromium and fonts were skipped.
| Install | Before | After |
|---|---|---|
| Global Claude install (`./setup`) | 632 `SKILL.md`, 34,738,066 bytes | 63 `SKILL.md`, 2,520,330 bytes |
| Existing install upgraded, then `./setup` | 632 `SKILL.md`, 34,738,066 bytes | 63 `SKILL.md`, 2,520,330 bytes; 569 generated `SKILL.md` (36.3 MB with their other files) moved to the backup |
| Development checkout with `./setup --host codex` | 632 `SKILL.md`, 34,738,066 bytes | 119 `SKILL.md`, 5,772,984 bytes (Claude plus Codex) |
| Same checkout, `GSTACK_RENDER_HOSTS=all bun run build` | 632 | 632; the next `./setup` prunes back to 119 |
| `$GSTACK_ROOT` paths missing from the Codex runtime root | 10 of 80 | 1 of 80 (`scripts/ship-measure.ts`, deferred) |
### What this means for you
Run `/gstack-upgrade` (or `git pull && ./setup`). The first setup prints one `pruned <dir>` line per agent you don't use from this checkout and a `host-render backup:` line naming where the generated files went; the next `./setup` prints none. `./setup --status` lists your agents, and `./setup --host <name>` adds one back. Nothing gstack can't prove it generated is removed.
### Itemized changes
#### Fixed
- An install renders skills only for the agents installed from it. setup records them in `.gstack-installed-hosts` in the checkout and never drops one, so `./setup --host codex` keeps a Factory render. The first run seeds the record from what the checkout already serves: install registry rows, install directories that resolve to it, agent skills that link into its renders, and legacy copy installs. `scripts/build.sh` renders Claude plus the recorded agents and prints which and why. A checkout with no record (a development checkout) still renders every agent, and `GSTACK_RENDER_HOSTS=all` forces that inside an install. (#1694)
- Every `./setup`, and a migration for upgrades, prunes the renders of agents missing from the record, using `gstack-relink`'s proof rules. Links into the checkout are removed. Files proven generated (gstack's generated-file banner, the generator's exact `openai.yaml`, or byte identity) are moved to `~/.gstack/backups/host-renders/<time>-<id>/`. Every other file stays where it is, and only emptied directories are removed. setup prints each kept file and a summary per agent, and `prune.log` in the backup lists every path. Two installs that share one state root are each cleaned. (#1694)
- The Codex `.agents/` render is made only when Codex is installed or recorded; a Claude-only setup used to make it every time. (#1694)
- Codex, Factory, Kiro, OpenCode, Cursor and Copilot runtime roots carry every file their skills read as `$GSTACK_ROOT/<path>`: `VERSION`, `scripts/jargon-list.json`, `scripts/question-registry.ts`, the AskUserQuestion split and CJK guides, `docs/test-value-bar.md`, all four review checklists and the review specialists, `plan-devex-review/dx-hall-of-fame.md`, design-html's vendored `pretext.js`, and host-rendered `office-hours` and `plan-design-review` `SKILL.md` copies. Cursor had two of the four checklists and only OpenCode had the specialists. (#1077)
#### Added
- README and `docs/troubleshooting.md` explain the record, the prune and its backup, and how to get an agent back. `docs/ADDING_A_HOST.md` documents the render contract and the new host checklist step. setup's Hermes, OpenClaw and GBrain hints say to add the agent to the record before rendering it by hand.
#### For contributors
- `bin/gstack-host-renders.sh` owns the record, the build's host selection and the prune; `scripts/build.sh`, setup, `bin/dev-setup` and `gstack-upgrade/migrations/v1.91.65.0.sh` source it. `bin/dev-setup` records Codex because it serves the repo's `.agents/`. `hosts/define-host.ts`' `sharedRuntimeRoot()` mirrors setup's new `_link_runtime_dists` list and `_copy_runtime_skill_refs`.
- New tests: `test/runtime-root-assets.test.ts` builds each runtime root with setup's own functions and checks every `$GSTACK_ROOT` literal in that agent's render on disk (it fails on the previous setup for all five roots); `test/host-renders.test.ts` (record, build selection, sequential installs, the upgrade refresh path); `test/host-renders-prune.test.ts` (a real all-agent render with a customized file, a user file, a look-alike skill and links; two installs on one state root; link-based seeding; the migration).
- Not verified: Cursor-agent and Claude Code were not re-run against the trimmed tree; the numbers are on-disk counts. The Windows copy-install paths are covered by stubbed tests only.
- Thanks to @vschoener for reporting #1694 and for the first fix attempt in #1695, @skyzer for the relocation approach in #1819 (both closed in favor of this one), @Saisreenivas for the Cursor-agent freeze report, and @el-analista for #1077.
## [1.91.62.0] - 2026-10-08
**A Rails repair can now finish verifying on arm64.**
+7
View File
@@ -516,6 +516,13 @@ The active skill lives at `~/.claude/skills/gstack/`. After making changes:
2. Fetch and reset in the skill directory: `cd ~/.claude/skills/gstack && git fetch origin && git reset --hard origin/main`
3. Rebuild: `cd ~/.claude/skills/gstack && bun run build`
`bun run build` renders every host in a checkout setup never ran in. In an
install (any checkout with `.gstack-installed-hosts`, including one set up with
`bin/dev-setup`, which records Claude and Codex) it renders only the recorded
hosts and prints them (#1694); `GSTACK_RENDER_HOSTS=all bun run build` renders
every host there, and the next `./setup` prunes the extra renders to
`$GSTACK_STATE_ROOT/backups/host-renders/` again.
**If you use gbrain:** the `git reset --hard` in step 2 reverts the brain-aware
(`GBRAIN_CONTEXT_LOAD` / `GBRAIN_SAVE_RESULTS`) blocks that `gstack-config
gbrain-refresh` renders into the install (those generated blocks differ from
+1 -1
View File
@@ -829,7 +829,7 @@ When Conductor creates a new workspace, `bin/dev-setup` runs automatically. It d
- **`.claude/skills/` is gitignored.** The symlinks never get committed.
- **Never write raw `ln -snf` in `setup`.** Every link site in `setup` MUST route through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. The helper preserves `ln -snf` on Unix and switches to `cp -R` / `cp -f` on Windows without Developer Mode, where plain `ln -snf` produces frozen file copies that don't refresh on `git pull`. `test/setup-windows-fallback.test.ts` enforces this with a static invariant — a single raw `ln` call outside the helper body fails CI.
- **Synchronous subagent dispatches must state the flag.** Claude Code runs Agent-tool subagents in the background by default (since v2.1.198), so any template step that dispatches a subagent and consumes its output must carry `run_in_background: false`. Use the `{{FOREGROUND_DISPATCH_NOTE}}` placeholder (`scripts/resolvers/constants.ts`) instead of hand-writing the guidance, and add the generated carrier file to `GENERATED_WITH_GUIDANCE` in `test/run-in-background-guidance.test.ts` in the same commit — its structural scanner fails CI on any generated dispatch imperative that lacks the flag.
- **Never delete or link over a skill entry `setup` cannot prove is gstack's.** Every destructive site in `setup` (the linker, the alias installer, both prefix-flip cleanups) and in `bin/gstack-relink` goes through the ownership helpers (`_claude_entry_is_ours` / `_claude_entry_owned_strongly` in `setup`, `_entry_is_ours` / `_entry_owned_strongly` in relink). The retired-skill prune (`_prune_stale_generated`) applies the same strong/weak split through its own gate: a real host directory is a candidate only when its SKILL.md carries the generated banner (`_owned_for_windows_refresh`), a host symlink is removed only when it resolves into gstack (`_gstack_target_is_ours`), a bannered real directory is cleaned through `_cleanup_weak_dir`, and a symlink inside the render tree is never followed. A symlink into gstack or the `.gstack-owned` marker proves the whole directory; a byte-identical or generated-banner SKILL.md proves only that file, and a differing one is moved to `~/.gstack/backups/skills/<ts>/` first. `test/setup-link-ownership.test.ts`, `test/setup-cleanup-orphans.test.ts`, `test/setup-prune-stale-generated.test.ts`, and `test/relink.test.ts` pin it. The rule is duplicated in the two scripts until the shared helper filed in TODOS.md lands: change both.
- **Never delete or link over a skill entry `setup` cannot prove is gstack's.** Every destructive site in `setup` (the linker, the alias installer, both prefix-flip cleanups) and in `bin/gstack-relink` goes through the ownership helpers (`_claude_entry_is_ours` / `_claude_entry_owned_strongly` in `setup`, `_entry_is_ours` / `_entry_owned_strongly` in relink). The retired-skill prune (`_prune_stale_generated`) applies the same strong/weak split through its own gate: a real host directory is a candidate only when its SKILL.md carries the generated banner (`_owned_for_windows_refresh`), a host symlink is removed only when it resolves into gstack (`_gstack_target_is_ours`), a bannered real directory is cleaned through `_cleanup_weak_dir`, and a symlink inside the render tree is never followed. A symlink into gstack or the `.gstack-owned` marker proves the whole directory; a byte-identical or generated-banner SKILL.md proves only that file, and a differing one is moved to `~/.gstack/backups/skills/<ts>/` first. `test/setup-link-ownership.test.ts`, `test/setup-cleanup-orphans.test.ts`, `test/setup-prune-stale-generated.test.ts`, and `test/relink.test.ts` pin it. The rule is duplicated in the two scripts until the shared helper filed in TODOS.md lands: change both. The host-render prune (`gstack_prune_host_renders` in `bin/gstack-host-renders.sh`, #1694) applies the same split to the render dirs of hosts a checkout does not serve: a link into the checkout goes, a file proven generated moves to `~/.gstack/backups/host-renders/<ts>-<id>/`, anything else stays, and only emptied directories are removed (`test/host-renders-prune.test.ts`).
- **`./setup` never fails on Chromium.** The Playwright bootstrap (section `# 2` of `setup`) is best-effort and bounded: every failure becomes a reason code (`skipped`, `chromium-install`, `chromium-install-timeout`, `chromium-install-locked`, `windows-no-node`, `windows-node-modules`, `post-install-launch`) printed in the final summary alongside the browser-dependent skills, and skill registration always runs. `GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT=<seconds>` (default 600) bounds the download; `GSTACK_SKIP_PLAYWRIGHT=1` skips it, the right knob for a no-browser box or a setup-only test loop. `GSTACK_SKIP_ASIDE=1` makes the browser summary (like the skills' probe and the renderer) treat Aside as absent, so the summary never promises a fallback the bootstrap did not deliver (`test/setup-browser-hint.test.ts`). Anything you add after the bootstrap must stay independent of the browser. `test/setup-playwright-best-effort.test.ts` pins the block.
## Testing your changes in a real project
+12
View File
@@ -119,6 +119,16 @@ An explicit `--host X` installs for X only and never changes another agent's
install. `/gstack-upgrade` refreshes every install it registered, one row per
host, and says which ones failed.
A checkout carries skills only for the agents installed from it. Setup records
them in `.gstack-installed-hosts` and never drops one, so adding an agent later
is just `./setup --host <name>`. Copies rendered for other agents are pruned:
generated files move to `~/.gstack/backups/host-renders/`, and files gstack
can't prove it generated stay where they are. A global Claude install went
from 632 `SKILL.md` files (34.7 MB) to its own 63 (2.5 MB), which keeps Cursor-agent
from freezing on the skills tree (#1694). In a development checkout,
`bun run build` still renders every agent; inside an install it renders the
recorded ones, and `GSTACK_RENDER_HOSTS=all bun run build` renders them all.
Tiers: **full** is certified by a real workflow run (see
[Certify your host](docs/ADDING_A_HOST.md#certify-your-host)); **experimental**
installs and passes the conformance tests but has no certification run yet;
@@ -687,6 +697,8 @@ it. The usual fix is to re-run setup from that row's source for that host, e.g.
A project install lives in the project's `.claude/skills/gstack` or
`.agents/skills/gstack`; run its `setup` from inside the project.
**Cursor freezes on load, or an agent's gstack skills went missing after an upgrade?** Each checkout now renders skills only for the agents installed from it (#1694). `./setup --status` lists them; `./setup --host <name>` adds one back. Pruned copies are in `~/.gstack/backups/host-renders/<time>-<id>/`, with every path in its `prune.log` ([troubleshooting](docs/troubleshooting.md#host-renders-pruned)).
**`/browse` (or `/qa`, `/design-review`) says `NEEDS_ASIDE` or `ASIDE_NOT_RUNNING`?** That's the probe telling you it's about to use the fallback browser. Want Aside? Open the app and sign in — `aside --version` should print a version and `aside repl 'console.log("ok")'` should print `ok` — then re-run. gstack never installs it for you. Want the fallback on purpose while Aside is open? `GSTACK_SKIP_ASIDE=1` makes every skill, the renderer, and `./setup` treat Aside as absent. When Aside is absent the probe prints `NEEDS_ASIDE: <OS>` and skills trust that line for the macOS-only download pitch; `GSTACK_PLATFORM` overrides the OS it names, for tests and unusual hosts (set it in your shell — gstack never reads it from a project `.env`).
**`/browse` fails on the fallback browser?** `cd ~/.claude/skills/gstack && bun install && bun run build`
+37
View File
@@ -311,6 +311,43 @@ From the approved 2026-10 test/eval/CI audit plan; the audit PR files these.
application-control messages as blocked from reporters' captures; nobody has
run it on an enforcing machine. **Effort:** S. **Priority:** P3.
### P2/P3: install footprint follow-ups from the October fix wave (PR C2, v1.91.65.0)
- **`scripts/ship-measure.ts` on env-var hosts** — /ship's measure loop runs
`$GSTACK_ROOT/scripts/ship-measure.ts`, which imports gstack's test helpers
and eval harness, so a Codex/Factory/... runtime root would need most of the
development tree. It is the one `$GSTACK_ROOT` path
`test/runtime-root-assets.test.ts` defers. Either make ship-measure
self-contained or have the skill call it from the source checkout
(`.source-path`). **Effort:** M. **Priority:** P3.
- **Rendered `SKILL.md` copies inside runtime roots are discoverable** —
`office-hours/SKILL.md` (#2449) and now `plan-design-review/SKILL.md` sit in
`~/.codex/skills/gstack/<skill>/` because skills read them as
`$GSTACK_ROOT/<skill>/SKILL.md`. A host that scans its skills dir
recursively may list them beside `gstack-<skill>`. Pointing those reads at
the sibling registry path, as /autoplan does, removes the copies; that is a
prompt change and needs its evals. **Effort:** M. **Priority:** P3.
- **Removing one host from a checkout** — the installed-hosts record only
grows, and `gstack-uninstall` removes every install. A per-host uninstall
should drop the host from `.gstack-installed-hosts` so its render is pruned;
today that is a hand edit. **Effort:** S. **Priority:** P3.
- **Recording an instruction-only host from setup** — Hermes, OpenClaw and
GBrain renders made by hand inside an install survive only when the user adds
the host to `.gstack-installed-hosts` first (setup's hint says so). A
`./setup --host hermes --render`-style path would record and render in one
step; it needs a product call because those tiers install nothing today.
**Effort:** S. **Priority:** P3.
- **Host-render backups never expire** — each install's first pruning setup
moves about 36 MB of generated files to
`$GSTACK_STATE_ROOT/backups/host-renders/`. Add a retention rule (for example
keep 30 days) once nobody has asked for a restore. **Effort:** S.
**Priority:** P3.
- **Verify the Cursor-agent freeze and Claude Code's listing on a real
install** — #1694's symptoms (Cursor-agent freezing above about 11 MB, Claude
Code dropping skill descriptions) were measured as on-disk bytes only: 632
`SKILL.md` / 34.7 MB before, 63 / 2.5 MB after. Nobody re-ran Cursor or
Claude Code against the trimmed tree. **Effort:** S. **Priority:** P3.
### P2/P3: severe fix wave follow-ups (filed 2026-10-03, v1.91.19.0)
Deferred from the approved severe fix wave (docs/designs/SEVERE_FIX_WAVE_2026_10.md), each with its reason.
+1 -1
View File
@@ -1 +1 @@
1.91.63.0
1.91.66.0
+1 -1
View File
@@ -1,4 +1,4 @@
# gstack digest v1.91.63.0 — regenerate/re-copy after upgrading gstack
# gstack digest v1.91.66.0 — regenerate/re-copy after upgrading gstack
Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
for agent hosts without a full skill install. The full skills add workflows,
+5
View File
@@ -56,6 +56,11 @@ if [ ! -e "$AGENTS_LINK" ]; then
ln -s "$REPO_ROOT" "$AGENTS_LINK"
fi
# 5b. Record Codex as a host this checkout serves (bin/gstack-host-renders.sh),
# so setup and `bun run build` keep rendering .agents/ for it (#1694).
. "$REPO_ROOT/bin/gstack-host-renders.sh"
gstack_render_hosts_add "$REPO_ROOT" codex
# 6. Run setup via the symlink so it detects .claude/skills/ as its parent.
#
# Workspace/dev setup MUST be non-interactive: Conductor runs this under a
+239
View File
@@ -0,0 +1,239 @@
# shellcheck shell=bash
# gstack-host-renders.sh — the one owner of a checkout's installed-hosts record
# and of the prune of skill renders for hosts it does not serve (#1694).
#
# Sourced, never executed: scripts/build.sh, setup and the gstack-upgrade
# migration source it. Bash 3.2 clean.
#
# A checkout renders one skills tree per host (.agents/ for Codex, .factory/,
# .kiro/, ...). Rendering all of them inside an install put ~576 extra SKILL.md
# files (32 MB) under ~/.claude/skills/gstack, a tree Claude Code and
# Cursor-agent scan (#1694). Instead:
# - setup adds each host it installs to $ROOT/.gstack-installed-hosts. The
# record is additive: ./setup --host codex never drops a recorded factory.
# - scripts/build.sh renders claude plus the recorded hosts. A checkout with
# no record (a development checkout) or GSTACK_RENDER_HOSTS=all renders
# every host.
# - every ./setup prunes renders of unrecorded hosts with the
# bin/gstack-relink proof rules: a symlink into this checkout (STRONG) is
# removed; a file proven generated (WEAK: gen-skill-docs' banner, the
# generator's exact openai.yaml shape, or byte identity with this checkout)
# is moved to $GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/; anything
# else stays where it is. Only directories left empty are removed.
# host:render-dir for every host whose render lives in its own checkout dir.
# Claude renders into the tracked tree. test/host-renders.test.ts keeps this
# equal to hostSubdir in hosts/*.ts.
GSTACK_HOST_RENDER_DIRS="codex:.agents kiro:.kiro factory:.factory opencode:.opencode cursor:.cursor copilot:.copilot slate:.slate openclaw:.openclaw hermes:.hermes gbrain:.gbrain"
gstack_render_hosts_file() { printf '%s/.gstack-installed-hosts\n' "$1"; }
_gstack_render_host_known() {
local pair
[ "$1" = claude ] && return 0
for pair in $GSTACK_HOST_RENDER_DIRS; do [ "${pair%%:*}" = "$1" ] && return 0; done
return 1
}
# gstack_render_hosts_read ROOT — the recorded hosts, one per line, sorted.
gstack_render_hosts_read() {
local file h
file="$(gstack_render_hosts_file "$1")"
[ -f "$file" ] || return 0
while IFS= read -r h; do
h="${h%%#*}"; h="$(printf '%s' "$h" | tr -d '[:space:]')"
[ -n "$h" ] && _gstack_render_host_known "$h" && printf '%s\n' "$h"
done < "$file" | sort -u
}
# gstack_render_hosts_has ROOT HOST
gstack_render_hosts_has() { gstack_render_hosts_read "$1" | grep -qx "$2"; }
# gstack_render_hosts_add ROOT HOST... — add hosts to the record (never removes
# one). Writes only when the set changed, by atomic rename.
gstack_render_hosts_add() {
local root="$1" file tmp old new h
shift
file="$(gstack_render_hosts_file "$root")"
old="$(gstack_render_hosts_read "$root")"
new="$( { [ -n "$old" ] && printf '%s\n' "$old"; for h in "$@"; do _gstack_render_host_known "$h" && printf '%s\n' "$h"; done; } | sort -u)"
[ -f "$file" ] && [ "$new" = "$old" ] && return 0
tmp="$file.tmp.$$"
if {
echo "# Hosts installed from this gstack checkout, one per line. Written by ./setup;"
echo "# scripts/build.sh renders skills only for these (#1694) and setup prunes the"
echo "# renders of every other host. Add a host by running ./setup --host <name>."
if [ -n "$new" ]; then printf '%s\n' "$new"; fi
} > "$tmp" && mv -f "$tmp" "$file"; then
return 0
fi
rm -f "$tmp"
return 1
}
# gstack_render_hosts_select ROOT — sets GSTACK_RENDER_HOST_LIST ("all", or
# claude followed by the recorded hosts) and GSTACK_RENDER_HOST_REASON.
gstack_render_hosts_select() {
local root="$1" file h
file="$(gstack_render_hosts_file "$root")"
GSTACK_RENDER_HOST_LIST=all
case "${GSTACK_RENDER_HOSTS:-}" in
all) GSTACK_RENDER_HOST_REASON="GSTACK_RENDER_HOSTS=all"; return 0 ;;
'') ;;
*) echo "warning: GSTACK_RENDER_HOSTS accepts only 'all' (got '${GSTACK_RENDER_HOSTS}'); ignoring it" >&2 ;;
esac
if [ ! -f "$file" ]; then
GSTACK_RENDER_HOST_REASON="no installed-hosts record, so this is a development checkout"
return 0
fi
GSTACK_RENDER_HOST_LIST=claude
for h in $(gstack_render_hosts_read "$root"); do
[ "$h" = claude ] || GSTACK_RENDER_HOST_LIST="$GSTACK_RENDER_HOST_LIST $h"
done
GSTACK_RENDER_HOST_REASON="recorded in $file; GSTACK_RENDER_HOSTS=all renders every host"
}
# _gstack_hr_link_abs LINK — absolute target of LINK, its directory part
# canonicalized (same rule as bin/gstack-relink's _link_target_abs).
_gstack_hr_link_abs() {
local dest d b d_real
dest="$(readlink "$1" 2>/dev/null || true)"
[ -n "$dest" ] || return 1
case "$dest" in /*) ;; *) dest="${1%/*}/$dest" ;; esac
d="${dest%/*}"; b="${dest##*/}"
if d_real="$(cd "$d" 2>/dev/null && pwd -P)"; then printf '%s/%s\n' "$d_real" "$b"; else printf '%s\n' "$dest"; fi
}
# gstack_render_hosts_seed ROOT — record the hosts this checkout already
# serves, for installs made before the record existed: registry rows whose
# source is ROOT, known install roots that resolve to ROOT (a bin/ link or the
# .source-path a Windows copy root carries), host skills entries that link
# into ROOT's render of that host, and gstack skill copies in a host skills dir
# that has no runtime root at all. Needs bin/gstack-install-registry.sh.
gstack_render_hosts_seed() {
local root="$1" real host dest iroot src pair dir e target found=""
real="$(cd "$root" 2>/dev/null && pwd -P)" || return 0
command -v gstack_install_registry_rows >/dev/null 2>&1 || return 0
while IFS=' ' read -r host _ _ _ _ src _; do
[ -n "$host" ] && [ "$src" = "$real" ] && found="$found $host"
done <<EOF
$(gstack_install_registry_rows 2>/dev/null)
EOF
while IFS=' ' read -r host _ dest iroot; do
[ -n "$host" ] || continue
if { [ -e "$iroot" ] || [ -L "$iroot" ]; }; then
src="$(_gstack_install_source "$iroot")"
[ -z "$src" ] && [ -f "$iroot/.source-path" ] && src="$(head -1 "$iroot/.source-path" 2>/dev/null)"
if [ -n "$src" ] && { [ "$src" = "$real" ] || [ "$(cd "$src" 2>/dev/null && pwd -P)" = "$real" ]; }; then
found="$found $host"; continue
fi
fi
dir=""
for pair in $GSTACK_HOST_RENDER_DIRS; do [ "${pair%%:*}" = "$host" ] && dir="${pair#*:}"; done
[ -n "$dir" ] && [ -d "$dest" ] || continue
for e in "$dest"/gstack*; do
if [ -L "$e" ]; then
target="$(_gstack_hr_link_abs "$e")" || continue
case "$target" in "$real/$dir"/*|"$root/$dir"/*) found="$found $host"; break ;; esac
elif [ ! -e "$iroot" ] && [ -d "$e" ] && { [ -f "$e/.gstack-owned" ] || grep -q '<!-- AUTO-GENERATED from' "$e/SKILL.md" 2>/dev/null; }; then
# Copied skills with no runtime root naming any checkout: a legacy
# copy install. Keep serving it rather than guess it is someone else's.
found="$found $host"; break
fi
done
done <<EOF
$(gstack_install_known_roots 2>/dev/null)
EOF
[ -n "$found" ] || return 0
# shellcheck disable=SC2086 # word-split the host list on purpose
gstack_render_hosts_add "$root" $found
}
# _gstack_hr_generated FILE TREE REAL — WEAK proof that FILE is a gstack
# render or copy: gen-skill-docs' two-line banner (setup's
# _gstack_generated_header rule), the generator's exact openai.yaml shape for
# its own skill directory, byte identity with this checkout (a Windows sidecar
# copy), or setup's runtime pointers naming this checkout.
_gstack_hr_generated() {
local f="$1" tree="$2" real="$3" skill rel first
case "$(head -c 8192 "$f" 2>/dev/null)" in
*'<!-- AUTO-GENERATED from '*'<!-- Regenerate: bun run gen:skill-docs -->'*) return 0 ;;
esac
case "$f" in
*/agents/openai.yaml)
skill="${f%/agents/openai.yaml}"; skill="${skill##*/}"
[ "$(head -1 "$f" 2>/dev/null)" = "interface:" ] \
&& grep -qxF " display_name: \"$skill\"" "$f" \
&& grep -qxF " default_prompt: \"Use $skill for this task.\"" "$f" \
&& [ "$(wc -l < "$f" | tr -d ' ')" -le 6 ] && return 0 ;;
*/.gstack-owned|*/.source-path)
first="$(head -1 "$f" 2>/dev/null)"
[ -n "$first" ] && [ "$(cd "$first" 2>/dev/null && pwd -P)" = "$real" ] && return 0 ;;
esac
case "$f" in
"$tree"/skills/gstack/*)
rel="${f#"$tree"/skills/gstack/}"
[ -f "$real/$rel" ] && cmp -s "$f" "$real/$rel" && return 0 ;;
esac
return 1
}
# gstack_prune_host_renders ROOT — prune the render dir of every host the
# record does not name. For each tree it changes, prints the kept paths and a
# summary; every path is listed in the backup's prune.log. A tree with nothing
# left to remove (only kept files) is silent. Returns 1 when a proven file
# could not be backed up (it is then left in place). Needs GSTACK_STATE_ROOT.
gstack_prune_host_renders() {
local root="$1" real recorded pair host dir tree backup e rel target rc=0
local n_backed n_links n_kept n_dirs kept_lines lines nl='
'
real="$(cd "$root" 2>/dev/null && pwd -P)" || return 0
[ -f "$(gstack_render_hosts_file "$root")" ] || return 0
recorded=" $(gstack_render_hosts_read "$root" | tr '\n' ' ') "
backup="${GSTACK_STATE_ROOT:?gstack-host-renders: GSTACK_STATE_ROOT is not set}/backups/host-renders/$(date -u +%Y%m%dT%H%M%SZ)-$(printf '%s' "$real" | cksum | awk '{print $1}')"
for pair in $GSTACK_HOST_RENDER_DIRS; do
host="${pair%%:*}"; dir="${pair#*:}"; tree="$real/$dir"
case "$recorded" in *" $host "*) continue ;; esac
if [ -L "$tree" ] || [ ! -d "$tree" ]; then continue; fi
n_backed=0; n_links=0; n_kept=0; n_dirs=0; kept_lines=""; lines=""
while IFS= read -r e; do
[ -n "$e" ] || continue
rel="${e#"$real"/}"
if [ -L "$e" ]; then
target="$(_gstack_hr_link_abs "$e")" || target=""
case "$target" in
"$real"|"$root") n_kept=$((n_kept + 1)); kept_lines="$kept_lines kept $rel: links to the checkout itself (bin/dev-setup)$nl"; lines="${lines}kept $rel links to the checkout itself$nl" ;;
"$real"/*|"$root"/*) rm -f "$e" && { n_links=$((n_links + 1)); lines="${lines}removed link $rel -> $target$nl"; } ;;
*) n_kept=$((n_kept + 1)); kept_lines="$kept_lines kept $rel: links outside this checkout$nl"; lines="${lines}kept $rel links outside this checkout$nl" ;;
esac
elif _gstack_hr_generated "$e" "$tree" "$real"; then
if mkdir -p "$backup/${rel%/*}" && mv -f "$e" "$backup/$rel"; then
n_backed=$((n_backed + 1)); lines="${lines}backed up $rel generated$nl"
else
rc=1; n_kept=$((n_kept + 1)); echo " kept $rel: could not back it up to $backup" >&2
fi
else
n_kept=$((n_kept + 1)); kept_lines="$kept_lines kept $rel: not proven generated (no gstack banner or byte match)$nl"
lines="${lines}kept $rel not proven generated$nl"
fi
done <<EOF
$(find "$tree" \( -type f -o -type l \) -print 2>/dev/null)
EOF
# -depth with -exec removes children first, so a directory emptied by its
# children's removal goes in the same pass.
while IFS= read -r e; do
[ -n "$e" ] || continue
n_dirs=$((n_dirs + 1)); lines="${lines}removed dir ${e#"$real"/} empty$nl"
done <<EOF
$(find "$tree" -depth -type d -empty -exec rmdir {} \; -print 2>/dev/null)
EOF
[ $((n_backed + n_links + n_dirs)) -gt 0 ] || continue
mkdir -p "$backup" && printf '%s' "$lines" >> "$backup/prune.log"
printf '%s' "$kept_lines"
echo " pruned $dir ($host is not installed from this checkout): $n_backed generated files backed up, $n_links links removed, $n_dirs empty dirs removed, $n_kept kept"
done
if [ -f "$backup/prune.log" ]; then
echo " host-render backup: $backup (every path: $backup/prune.log; restore a file with mv)"
fi
return "$rc"
}
+40 -6
View File
@@ -75,7 +75,9 @@ Inventory of every setup side effect, by phase (line numbers are approximate):
| Phase | Writes | Scope |
|---|---|---|
| Build | `browse/dist`, `design/dist`, `make-pdf/dist`, `bin/gstack-cso-*` in the source checkout | source |
| Generation | `.agents/`, `.kiro/`, `.factory/`, `.opencode/`, `.cursor/` renders in the source checkout; `gstack-patch-names` rewrites Claude `name:` fields in place | source |
| Hosts record | `.gstack-installed-hosts` in the source checkout: every host setup installed from it, additive (#1694) | source |
| Generation | renders for the recorded hosts only (`.agents/`, `.kiro/`, `.factory/`, `.opencode/`, `.cursor/`, `.copilot/`) in the source checkout; `gstack-patch-names` rewrites Claude `name:` fields in place | source |
| Render prune | renders of hosts the record does not name: links into the checkout removed, generated files moved to `$GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/`, other files kept | source / state root |
| Chromium | Playwright cache (`~/.cache/ms-playwright`), lock under the state root | machine |
| Config | `skill_prefix`, `timeline_stop_hook`, team-mode keys in `$GSTACK_STATE_ROOT/config.yaml` | state root |
| Claude arm | `~/.claude/skills/gstack` link, one dir per skill with a `SKILL.md` link, alias copies | selected host |
@@ -114,6 +116,29 @@ shell metacharacters) is named through a `<host>-<id>.root` alias symlink:
worktree-isolated Claude Code refuses a command path containing a space in any
quoting.
### Host renders in an install (#1694)
A checkout renders skills only for the hosts installed from it.
`bin/gstack-host-renders.sh` owns the record, `.gstack-installed-hosts` in the
checkout: setup adds each host it installs and never removes one, so
`./setup --host codex` keeps a `--host factory` render. The first run after an
upgrade seeds it from the hosts the checkout already serves (registry rows,
install roots that resolve to it, host skills that link into its renders, and
legacy copies with no runtime root). `scripts/build.sh` renders claude plus
the recorded hosts and prints which hosts and why; a checkout with no record (a
development checkout) or `GSTACK_RENDER_HOSTS=all` renders every host.
Every setup run then prunes the renders of unrecorded hosts with
`bin/gstack-relink`'s proof rules: a symlink into the checkout (strong proof)
is removed; a file proven generated (weak proof: the gen-skill-docs banner, the
generator's exact `openai.yaml` shape, byte identity with the checkout) is
moved to `$GSTACK_STATE_ROOT/backups/host-renders/<ts>-<id>/`; every other file
stays where it is, and only directories left empty are removed. The backup's
`prune.log` lists every path. A gstack-upgrade migration runs
the same prune for an install upgraded without a setup run. Instruction-only
hosts (Hermes, OpenClaw, GBrain) are never installed by setup, so a user who
renders one by hand inside an install adds its name to the record first.
## Host tiers and capabilities
Every host declares `tier` and `capabilities` (`scripts/host-config.ts`).
@@ -257,8 +282,14 @@ That expands to the full `HostConfig` with these defaults:
(`~/.claude/skills/gstack` → `~/{globalRoot}`, `.claude/skills/gstack` →
`{localSkillRoot}`, `.claude/skills` → `{hostSubdir}/skills`)
- `suppressedResolvers`: the GBrain pair (`GBRAIN_CONTEXT_LOAD`, `GBRAIN_SAVE_RESULTS`)
- `runtimeRoot`: the shared asset list (`bin`, `browse/dist`, `browse/bin`,
`gstack-upgrade`, `ETHOS.md` + review checklist files)
- `runtimeRoot`: `sharedRuntimeRoot()`, every file the skills run or read as
`$GSTACK_ROOT/<path>` (`bin`, `lib`, the compiled tools, `freeze/bin`, the
review checklists and specialists, the jargon list and question registry,
the AskUserQuestion docs, the DX Hall of Fame, `VERSION`, and the
office-hours and plan-design-review `SKILL.md` copies). It mirrors setup's
`_link_runtime_dists` and `_copy_runtime_skill_refs`;
`test/runtime-root-assets.test.ts` checks each staged root on disk. A host
with extra assets passes them: `sharedRuntimeRoot(['qa/templates'])`.
- `install`: `{ linkingStrategy: 'symlink-generated' }`
- `learningsMode: 'basic'`
@@ -280,7 +311,7 @@ Review Army), `GBRAIN_RESOLVERS` (the default
suppression pair), and `EXEC_STYLE_TOOL_REWRITES` (the OpenClaw-style
lowercase-tool rewrites shared by openclaw and gbrain).
Good examples: `hosts/opencode.ts` (path + runtimeRoot overrides),
Good examples: `hosts/opencode.ts` (path + extra runtime assets),
`hosts/factory.ts` (tool rewrites and conditional fields), `hosts/hermes.ts`
(AGENTS.md host with custom tool rewrites and resolver composition).
@@ -300,9 +331,12 @@ export const ALL_HOST_CONFIGS: HostConfig[] = [
export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, myhost };
```
### 3. Add to .gitignore
### 3. Add to .gitignore and the render table
Add `.myhost/` to `.gitignore` (generated skill docs are gitignored).
Add `.myhost/` to `.gitignore` (generated skill docs are gitignored), and add
`myhost:.myhost` to `GSTACK_HOST_RENDER_DIRS` in `bin/gstack-host-renders.sh`
so an install renders it only when it is installed and prunes it otherwise
(#1694; `test/host-renders.test.ts` checks the table against `hosts/*.ts`).
### 4. Generate and verify
+30
View File
@@ -763,6 +763,36 @@ whose hooks parse. This is a gstack bug: report the printed `<file>:<line>`.
cannot be checked before the pull; setup then refuses the broken hook (see the
entry above).
<a id="host-renders-pruned"></a>
### `pruned <dir> (<host> is not installed from this checkout): ...` / `kept <path>: not proven generated (...)` / `host-render backup: <dir> (...)`
**Meaning.** A gstack checkout keeps skills only for the agents installed from
it, listed in `.gstack-installed-hosts` in the checkout (#1694). Older installs
rendered every agent's copy, so a global Claude install carried 632 `SKILL.md`
files (34.7 MB) that Claude Code and Cursor-agent scan. setup removed the copy
for an agent that is not installed from this checkout. Generated files were
moved to the backup directory it printed; links into the checkout were removed;
files it could not prove gstack generated (`kept ...`) were left in place.
`prune.log` in the backup lists every path. The same prune runs once from the
upgrade migration. Agents in the record are never pruned.
**Fix.** Nothing, if you don't use that agent. To get an agent back, install
it from this checkout, which records it and renders its skills:
```bash
./setup --host <name>
```
For an instruction-only agent you render by hand (Hermes, OpenClaw, GBrain),
add its name to `.gstack-installed-hosts` first, then run
`bun run gen:skill-docs --host <name>`. To restore one file, `mv` it back from
the backup. A `kept` file is yours: move or delete it when you no longer need it.
The backup sits in gstack's state root, which no agent scans; delete it once
you are sure you don't need it (about 36 MB for a pre-1.91.65 Claude install).
**Expected result.** The next `./setup` prints no `pruned` line, and
`./setup --status` lists the agents you use.
<a id="cso-windows-msvc-compile"></a>
### `CSO unavailable: its native helper was not built (windows-msvc-compile)`
+31
View File
@@ -0,0 +1,31 @@
#!/usr/bin/env bash
# Migration: v1.91.65.0 — install footprint (#1694). The release queue may
# rename this file at /ship; it must match VERSION.
#
# Installs used to render every host's skills inside the checkout, so a global
# Claude install carried ~576 extra SKILL.md files (32 MB) that Claude Code and
# Cursor-agent scan. Record the hosts this install already serves (registry
# rows, install roots that resolve here, host skills that link into its
# renders), then prune the renders of every other host with
# bin/gstack-host-renders.sh: generated files are backed up under
# $GSTACK_STATE_ROOT/backups/host-renders/, anything not proven generated stays.
# ./setup runs the same prune on every run; this covers an install upgraded
# without one. Idempotent and non-fatal.
set -u
_gstack_migration_dir="${BASH_SOURCE[0]//\\//}"; _gstack_migration_dir="${_gstack_migration_dir%/*}"
_gstack_bin="${_gstack_migration_dir}/../../bin"
. "$_gstack_bin/gstack-state-root.sh" 2>/dev/null || { echo "$0: cannot resolve the gstack state root: $_gstack_bin/gstack-state-root.sh is missing. fix: reinstall with ./setup or /gstack-upgrade (docs/state-root.md)" >&2; exit 1; }
gstack_state_root_select; GSTACK_STATE_ROOT="$_gstack_sr_root"
. "$_gstack_bin/gstack-install-registry.sh" 2>/dev/null || exit 0
. "$_gstack_bin/gstack-host-renders.sh" 2>/dev/null || exit 0
INSTALL="${GSTACK_INSTALL_DIR:-${HOME:-}/.claude/skills/gstack}"
[ -f "$INSTALL/VERSION" ] && [ -f "$INSTALL/setup" ] || exit 0
gstack_render_hosts_seed "$INSTALL"
if [ ! -f "$(gstack_render_hosts_file "$INSTALL")" ]; then
echo "host renders: no install from $INSTALL was found, so its renders were left alone; ./setup --host <name> records and prunes"
exit 0
fi
gstack_prune_host_renders "$INSTALL" || echo "host renders: some generated files could not be backed up and were left in place; the next ./setup retries" >&2
exit 0
-9
View File
@@ -39,15 +39,6 @@ const codex = defineHost({
{ from: 'CLAUDE.md', to: 'AGENTS.md' },
],
// Mirrors create_codex_runtime_root in setup. design/dist and make-pdf/dist
// back $GSTACK_DESIGN and $GSTACK_MAKE_PDF (#2891).
runtimeRoot: {
globalSymlinks: ['bin', 'lib', 'browse/dist', 'browse/bin', 'design/dist', 'make-pdf/dist', 'freeze/bin', 'careful/bin', 'gstack-upgrade', 'ETHOS.md'],
globalFiles: {
'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'],
},
},
// Outside-review resolvers route to Claude Code; Review Army has its own restriction.
suppressedResolvers: ['REVIEW_ARMY', ...GBRAIN_RESOLVERS],
+23 -6
View File
@@ -76,6 +76,28 @@ export function preambleToolGlossary(glossary: string): Record<string, string> {
return { [PREAMBLE_GLOSSARY_ANCHOR]: `${glossary}\n\n${PREAMBLE_GLOSSARY_ANCHOR}` };
}
/**
* The runtime-root assets setup installs for every env-var host: the tools
* the skills run plus every file they read as "$GSTACK_ROOT/<path>". Mirrors
* setup's _link_runtime_dists and _copy_runtime_skill_refs (each root also
* links bin, lib, browse and ETHOS.md); test/runtime-root-assets.test.ts
* checks the staged roots on disk. `extraSymlinks` appends host-only assets.
*/
export function sharedRuntimeRoot(extraSymlinks: string[] = []): HostConfig['runtimeRoot'] {
return {
globalSymlinks: ['bin', 'lib', 'browse/dist', 'browse/bin', 'design/dist', 'make-pdf/dist', 'freeze/bin', 'careful/bin',
'review/specialists', 'design-html/vendor', 'gstack-upgrade', 'ETHOS.md', 'VERSION', ...extraSymlinks],
globalFiles: {
'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'],
'scripts': ['jargon-list.json', 'question-registry.ts'],
'docs': ['askuserquestion-split.md', 'askuserquestion-cjk.md', 'test-value-bar.md'],
'plan-devex-review': ['dx-hall-of-fame.md'],
'office-hours': ['SKILL.md'],
'plan-design-review': ['SKILL.md'],
},
};
}
/**
* Host definition input: name + displayName are required, everything else is
* an override on the common external-host defaults documented above.
@@ -128,12 +150,7 @@ export function defineHost<const N extends string>(overrides: HostOverrides<N>):
extraPathRewrites,
toolRewrites,
suppressedResolvers = [...GBRAIN_RESOLVERS],
runtimeRoot = {
globalSymlinks: ['bin', 'lib', 'browse/dist', 'browse/bin', 'design/dist', 'make-pdf/dist', 'freeze/bin', 'careful/bin', 'gstack-upgrade', 'ETHOS.md'],
globalFiles: {
'review': ['checklist.md', 'TODOS-format.md'],
},
},
runtimeRoot = sharedRuntimeRoot(),
install = {
linkingStrategy: 'symlink-generated',
},
+2 -7
View File
@@ -1,4 +1,4 @@
import { defineHost, preambleToolGlossary } from './define-host';
import { defineHost, preambleToolGlossary, sharedRuntimeRoot } from './define-host';
const opencode = defineHost({
name: 'opencode',
@@ -13,12 +13,7 @@ const opencode = defineHost({
// OpenCode links a wider runtime asset set than the shared default
// (design binary, review specialists, qa templates/references, DX hall of fame).
runtimeRoot: {
globalSymlinks: ['bin', 'lib', 'browse/dist', 'browse/bin', 'design/dist', 'make-pdf/dist', 'freeze/bin', 'careful/bin', 'gstack-upgrade', 'ETHOS.md', 'review/specialists', 'qa/templates', 'qa/references', 'plan-devex-review/dx-hall-of-fame.md'],
globalFiles: {
'review': ['checklist.md', 'design-checklist.md', 'greptile-triage.md', 'TODOS-format.md'],
},
},
runtimeRoot: sharedRuntimeRoot(['qa/templates', 'qa/references']),
});
export default opencode;
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "gstack",
"version": "1.91.63",
"version": "1.91.66",
"description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
"license": "MIT",
"type": "module",
+14 -1
View File
@@ -36,7 +36,20 @@ esac
# inside untrusted repos, and dotenv could set security switches such as
# GSTACK_CHROMIUM_NO_SANDBOX while a bunfig preload runs arbitrary code (D0).
"$BUN_CMD" run vendor:xterm
"$BUN_CMD" run gen:skill-docs --host all
# Inside an install, render only the hosts setup installed from this checkout
# (#1694): every host's render under ~/.claude/skills/gstack is scanned by
# Claude Code and Cursor. bin/gstack-host-renders.sh owns the record.
. "$ROOT/bin/gstack-host-renders.sh"
gstack_render_hosts_select "$ROOT"
if [ "$GSTACK_RENDER_HOST_LIST" = all ]; then
echo "Rendering skills for every host: $GSTACK_RENDER_HOST_REASON"
"$BUN_CMD" run gen:skill-docs --host all
else
echo "Rendering skills for: $GSTACK_RENDER_HOST_LIST ($GSTACK_RENDER_HOST_REASON)"
for render_host in $GSTACK_RENDER_HOST_LIST; do
"$BUN_CMD" run gen:skill-docs --host "$render_host"
done
fi
"$BUN_CMD" build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig browse/src/cli.ts --outfile browse/dist/browse
"$BUN_CMD" build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig browse/src/find-browse.ts --outfile browse/dist/find-browse
"$BUN_CMD" build --compile --no-compile-autoload-dotenv --no-compile-autoload-bunfig design/src/cli.ts --outfile design/dist/design
+75 -80
View File
@@ -255,6 +255,7 @@ case "$HOST" in
echo "To integrate gstack with OpenClaw:"
echo " 1. Tell your OpenClaw agent: 'install gstack for openclaw'"
echo " 2. Or generate artifacts: bun run gen:skill-docs --host openclaw"
echo " (in an install, add 'openclaw' to .gstack-installed-hosts first, or ./setup prunes them)"
echo " 3. See docs/OPENCLAW.md for the full architecture"
print_instruction_tier
exit 0 ;;
@@ -268,6 +269,8 @@ case "$HOST" in
echo " 2. Render Hermes-flavoured skills yourself (not certified; #2826):"
echo " bun run gen:skill-docs --host hermes"
echo " then point a Hermes profile's skills.external_dirs at .hermes/skills."
echo " Add 'hermes' to .gstack-installed-hosts in this checkout first: ./setup"
echo " prunes renders of hosts that file does not name (#1694)."
print_instruction_tier
exit 0 ;;
gbrain)
@@ -278,6 +281,7 @@ case "$HOST" in
echo ""
echo "To generate brain-aware skills:"
echo " bun run gen:skill-docs --host gbrain"
echo " (in an install, add 'gbrain' to .gstack-installed-hosts first, or ./setup prunes them)"
echo ""
echo "GBrain setup and brain skills ship from the GBrain repo."
echo ""
@@ -316,6 +320,7 @@ SOURCE_GSTACK_DIR="$(cd "$(dirname "$0")" && pwd -P)"
gstack_state_root_select; GSTACK_STATE_ROOT="$_gstack_sr_root"
. "$SOURCE_GSTACK_DIR/bin/gstack-install-registry.sh" || { echo "$0: $SOURCE_GSTACK_DIR/bin/gstack-install-registry.sh is missing. fix: reinstall from a fresh clone (docs/ADDING_A_HOST.md)" >&2; exit 1; }
. "$SOURCE_GSTACK_DIR/bin/gstack-render-claude.sh" || { echo "$0: $SOURCE_GSTACK_DIR/bin/gstack-render-claude.sh is missing. fix: reinstall from a fresh clone" >&2; exit 1; }
. "$SOURCE_GSTACK_DIR/bin/gstack-host-renders.sh" || { echo "$0: $SOURCE_GSTACK_DIR/bin/gstack-host-renders.sh is missing. fix: reinstall from a fresh clone" >&2; exit 1; }
SETUP_VERSION="$(cat "$SOURCE_GSTACK_DIR/VERSION" 2>/dev/null || echo unknown)"
# --claude-model is validated before anything is written, and persisted once
@@ -630,8 +635,15 @@ _link_or_copy() {
# "$GSTACK_ROOT/freeze/bin/...". Subdirectories only, never the whole skill
# directory: make-pdf/, freeze/ and careful/ ship a Claude SKILL.md a host
# scanning its skills root would discover as a duplicate skill.
# Also the files the skills read on demand as "$GSTACK_ROOT/<path>" (#1077
# residue): the preamble's jargon list, question registry and AskUserQuestion
# docs, the review checklists and specialists, /plan-devex-review's Hall of
# Fame, the test-value bar, design-html's vendored pretext.js and VERSION.
# Pinned by test/runtime-root-assets.test.ts. A destination that already exists
# as a real entry is left alone: in the repo-local sidecar review/ is a link to
# the source, so its files already resolve and must never be linked over.
_link_runtime_dists() {
local d
local d f
# Record the source checkout (#3026): on Windows the root's browse/dist is a
# copy with no node_modules beside it, and the browse CLI runs the checkout's
# Node server bundle from here instead. /gstack-upgrade reads it too.
@@ -640,13 +652,37 @@ _link_runtime_dists() {
else
printf '%s\n' "$1" > "$2/.source-path"
fi
for d in design/dist make-pdf/dist freeze/bin careful/bin; do
for d in design/dist make-pdf/dist freeze/bin careful/bin review/specialists design-html/vendor; do
[ -d "$1/$d" ] || continue
if [ "$IS_WINDOWS" -eq 1 ] || [ -L "$2/$d" ] || [ ! -e "$2/$d" ]; then
mkdir -p "$2/${d%/*}"
_link_or_copy "$1/$d" "$2/$d"
fi
done
for f in VERSION scripts/jargon-list.json scripts/question-registry.ts \
docs/askuserquestion-split.md docs/askuserquestion-cjk.md docs/test-value-bar.md \
review/checklist.md review/design-checklist.md review/greptile-triage.md review/TODOS-format.md \
plan-devex-review/dx-hall-of-fame.md; do
[ -f "$1/$f" ] || continue
if [ "$IS_WINDOWS" -eq 1 ] || [ -L "$2/$f" ] || [ ! -e "$2/$f" ]; then
case "$f" in */*) mkdir -p "$2/${f%/*}" ;; esac
_link_or_copy "$1/$f" "$2/$f"
fi
done
}
# _copy_runtime_skill_refs RENDER_SKILLS ROOT — skills that read another
# skill's instructions as "$GSTACK_ROOT/<skill>/SKILL.md" get that host's
# rendered copy there: plan-eng-review's inline office-hours step (#2449) and
# the plan-design-review sections. Real-file copies, like every SKILL.md in a
# runtime root, and only the SKILL.md, never the skill's source directory.
_copy_runtime_skill_refs() {
local s
for s in office-hours plan-design-review; do
[ -f "$1/gstack-$s/SKILL.md" ] || continue
mkdir -p "$2/$s"
_copy_skill_md "$1/gstack-$s/SKILL.md" "$2/$s/SKILL.md"
done
}
# ─── Real-file SKILL.md copies in host runtime roots (C3, #333) ──────────────
@@ -1681,6 +1717,23 @@ fi
# (bin/gstack-render-claude.sh).
gstack_claude_overlay "$SOURCE_GSTACK_DIR" "$SOURCE_GSTACK_DIR/bin/gstack-config"
# Installed-hosts record (#1694): the build renders skills only for these
# hosts, and step 7b prunes every other host's render from this checkout. The
# record only grows; installs made before it existed are discovered first.
gstack_render_hosts_seed "$SOURCE_GSTACK_DIR"
_RENDER_HOSTS_SELECTED=""
[ "$INSTALL_CLAUDE" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED claude"
[ "$INSTALL_CODEX" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED codex"
[ "$INSTALL_KIRO" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED kiro"
[ "$INSTALL_FACTORY" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED factory"
[ "$INSTALL_OPENCODE" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED opencode"
[ "$INSTALL_CURSOR" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED cursor"
[ "$INSTALL_COPILOT" -eq 1 ] && _RENDER_HOSTS_SELECTED="$_RENDER_HOSTS_SELECTED copilot"
# shellcheck disable=SC2086 # the host list splits on purpose
if ! gstack_render_hosts_add "$SOURCE_GSTACK_DIR" $_RENDER_HOSTS_SELECTED; then
echo " warning: could not write $(gstack_render_hosts_file "$SOURCE_GSTACK_DIR"); this build renders every host and nothing is pruned" >&2
fi
# Migrate existing wrappers BEFORE build can regenerate/prune shared host trees.
# This also repairs existing Codex/Kiro installs during a Claude-only setup.
# A failed/foreign replacement retains its old render even when build runs
@@ -1880,14 +1933,16 @@ if [ ! -x "$BROWSE_BIN" ]; then
exit 1
fi
# 1b. Generate .agents/ Codex skill docs — always regenerate to prevent stale descriptions.
# 1b. Generate .agents/ Codex skill docs whenever this checkout serves Codex.
# .agents/ is no longer committed — generated at setup time from .tmpl templates.
# bun run build generates the host-default artifact. Always render Codex again
# with the resolved user profile so a build cannot overwrite a Sol-specific render.
# Always regenerate: generation is fast (<2s) and mtime-based staleness checks are fragile
# (miss stale files when timestamps match after clone/checkout/upgrade).
# (miss stale files when timestamps match after clone/checkout/upgrade). A
# checkout with no Codex install renders none (#1694).
AGENTS_DIR="$SOURCE_GSTACK_DIR/.agents/skills"
NEEDS_AGENTS_GEN=1
NEEDS_AGENTS_GEN=0
if [ "$INSTALL_CODEX" -eq 1 ] || gstack_render_hosts_has "$SOURCE_GSTACK_DIR" codex; then NEEDS_AGENTS_GEN=1; fi
if [ "$NEEDS_AGENTS_GEN" -eq 1 ]; then
log "Generating .agents/ skill docs..."
@@ -2716,19 +2771,7 @@ create_codex_runtime_root() {
if [ -f "$agents_dir/gstack-upgrade/SKILL.md" ]; then
_copy_skill_md "$agents_dir/gstack-upgrade/SKILL.md" "$codex_gstack/gstack-upgrade/SKILL.md"
fi
# plan-eng-review's inline office-hours step reads
# $GSTACK_ROOT/office-hours/SKILL.md (#2449) — install the codex-rendered
# variant there so the documented path exists.
if [ -f "${agents_dir}/gstack-office-hours/SKILL.md" ]; then
mkdir -p "${codex_gstack}/office-hours"
_copy_skill_md "${agents_dir}/gstack-office-hours/SKILL.md" "${codex_gstack}/office-hours/SKILL.md"
fi
# Review runtime assets (individual files, NOT the whole review/ dir which has SKILL.md)
for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
if [ -f "$gstack_dir/review/$f" ]; then
_link_or_copy "$gstack_dir/review/$f" "$codex_gstack/review/$f"
fi
done
_copy_runtime_skill_refs "$agents_dir" "$codex_gstack"
# ETHOS.md — referenced by "Search Before Building" in all skill preambles
if [ -f "$gstack_dir/ETHOS.md" ]; then
_link_or_copy "$gstack_dir/ETHOS.md" "$codex_gstack/ETHOS.md"
@@ -2772,18 +2815,7 @@ create_factory_runtime_root() {
if [ -f "$factory_dir/gstack-upgrade/SKILL.md" ]; then
_copy_skill_md "$factory_dir/gstack-upgrade/SKILL.md" "$factory_gstack/gstack-upgrade/SKILL.md"
fi
# plan-eng-review's inline office-hours step reads
# $GSTACK_ROOT/office-hours/SKILL.md (#2449) — install the factory-rendered
# variant there so the documented path exists.
if [ -f "${factory_dir}/gstack-office-hours/SKILL.md" ]; then
mkdir -p "${factory_gstack}/office-hours"
_copy_skill_md "${factory_dir}/gstack-office-hours/SKILL.md" "${factory_gstack}/office-hours/SKILL.md"
fi
for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
if [ -f "$gstack_dir/review/$f" ]; then
_link_or_copy "$gstack_dir/review/$f" "$factory_gstack/review/$f"
fi
done
_copy_runtime_skill_refs "$factory_dir" "$factory_gstack"
if [ -f "$gstack_dir/ETHOS.md" ]; then
_link_or_copy "$gstack_dir/ETHOS.md" "$factory_gstack/ETHOS.md"
fi
@@ -2805,7 +2837,7 @@ create_opencode_runtime_root() {
rm -rf "$opencode_gstack"
fi
mkdir -p "$opencode_gstack" "$opencode_gstack/browse" "$opencode_gstack/gstack-upgrade" "$opencode_gstack/review" "$opencode_gstack/qa" "$opencode_gstack/plan-devex-review"
mkdir -p "$opencode_gstack" "$opencode_gstack/browse" "$opencode_gstack/gstack-upgrade" "$opencode_gstack/review" "$opencode_gstack/qa"
if [ -f "$opencode_dir/gstack/SKILL.md" ]; then
_copy_skill_md "$opencode_dir/gstack/SKILL.md" "$opencode_gstack/SKILL.md"
@@ -2826,30 +2858,13 @@ create_opencode_runtime_root() {
if [ -f "$opencode_dir/gstack-upgrade/SKILL.md" ]; then
_copy_skill_md "$opencode_dir/gstack-upgrade/SKILL.md" "$opencode_gstack/gstack-upgrade/SKILL.md"
fi
# plan-eng-review's inline office-hours step reads
# $GSTACK_ROOT/office-hours/SKILL.md (#2449) — install the opencode-rendered
# variant there so the documented path exists.
if [ -f "${opencode_dir}/gstack-office-hours/SKILL.md" ]; then
mkdir -p "${opencode_gstack}/office-hours"
_copy_skill_md "${opencode_dir}/gstack-office-hours/SKILL.md" "${opencode_gstack}/office-hours/SKILL.md"
fi
for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
if [ -f "$gstack_dir/review/$f" ]; then
_link_or_copy "$gstack_dir/review/$f" "$opencode_gstack/review/$f"
fi
done
if [ -d "$gstack_dir/review/specialists" ]; then
_link_or_copy "$gstack_dir/review/specialists" "$opencode_gstack/review/specialists"
fi
_copy_runtime_skill_refs "$opencode_dir" "$opencode_gstack"
if [ -d "$gstack_dir/qa/templates" ]; then
_link_or_copy "$gstack_dir/qa/templates" "$opencode_gstack/qa/templates"
fi
if [ -d "$gstack_dir/qa/references" ]; then
_link_or_copy "$gstack_dir/qa/references" "$opencode_gstack/qa/references"
fi
if [ -f "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" ]; then
_link_or_copy "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" "$opencode_gstack/plan-devex-review/dx-hall-of-fame.md"
fi
if [ -f "$gstack_dir/ETHOS.md" ]; then
_link_or_copy "$gstack_dir/ETHOS.md" "$opencode_gstack/ETHOS.md"
fi
@@ -2989,12 +3004,7 @@ create_cursor_runtime_root() {
if [ -f "$cursor_dir/gstack-upgrade/SKILL.md" ]; then
_copy_skill_md "$cursor_dir/gstack-upgrade/SKILL.md" "$cursor_gstack/gstack-upgrade/SKILL.md"
fi
# Review runtime assets — the cursor host config ships the lean pair.
for f in checklist.md TODOS-format.md; do
if [ -f "$gstack_dir/review/$f" ]; then
_link_or_copy "$gstack_dir/review/$f" "$cursor_gstack/review/$f"
fi
done
_copy_runtime_skill_refs "$cursor_dir" "$cursor_gstack"
if [ -f "$gstack_dir/ETHOS.md" ]; then
_link_or_copy "$gstack_dir/ETHOS.md" "$cursor_gstack/ETHOS.md"
fi
@@ -3049,13 +3059,6 @@ create_cursor_sidecar() {
_link_or_copy "$cursor_dir/gstack-upgrade/SKILL.md" "$cursor_gstack/gstack-upgrade/SKILL.md"
fi
fi
for f in checklist.md TODOS-format.md; do
if [ -f "$repo_root/review/$f" ]; then
if [ "$IS_WINDOWS" -eq 1 ] || [ -L "$cursor_gstack/review/$f" ] || [ ! -e "$cursor_gstack/review/$f" ]; then
_link_or_copy "$repo_root/review/$f" "$cursor_gstack/review/$f"
fi
fi
done
if [ -f "$repo_root/ETHOS.md" ]; then
if [ "$IS_WINDOWS" -eq 1 ] || [ -L "$cursor_gstack/ETHOS.md" ] || [ ! -e "$cursor_gstack/ETHOS.md" ]; then
_link_or_copy "$repo_root/ETHOS.md" "$cursor_gstack/ETHOS.md"
@@ -3161,15 +3164,7 @@ create_copilot_runtime_root() {
if [ -f "$copilot_dir/gstack-upgrade/SKILL.md" ]; then
_copy_skill_md "$copilot_dir/gstack-upgrade/SKILL.md" "$copilot_gstack/gstack-upgrade/SKILL.md"
fi
if [ -f "$copilot_dir/gstack-office-hours/SKILL.md" ]; then
mkdir -p "$copilot_gstack/office-hours"
_copy_skill_md "$copilot_dir/gstack-office-hours/SKILL.md" "$copilot_gstack/office-hours/SKILL.md"
fi
for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
if [ -f "$gstack_dir/review/$f" ]; then
_link_or_copy "$gstack_dir/review/$f" "$copilot_gstack/review/$f"
fi
done
_copy_runtime_skill_refs "$copilot_dir" "$copilot_gstack"
if [ -f "$gstack_dir/ETHOS.md" ]; then
_link_or_copy "$gstack_dir/ETHOS.md" "$copilot_gstack/ETHOS.md"
fi
@@ -3460,15 +3455,7 @@ if [ "$INSTALL_KIRO" -eq 1 ]; then
if [ -f "$KIRO_DIR/gstack/SKILL.md" ]; then
_copy_skill_md "$KIRO_DIR/gstack/SKILL.md" "$KIRO_GSTACK/SKILL.md"
fi
if [ -f "$KIRO_DIR/gstack-office-hours/SKILL.md" ]; then
mkdir -p "$KIRO_GSTACK/office-hours"
_copy_skill_md "$KIRO_DIR/gstack-office-hours/SKILL.md" "$KIRO_GSTACK/office-hours/SKILL.md"
fi
for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
if [ -f "$SOURCE_GSTACK_DIR/review/$f" ]; then
_link_or_copy "$SOURCE_GSTACK_DIR/review/$f" "$KIRO_GSTACK/review/$f"
fi
done
_copy_runtime_skill_refs "$KIRO_DIR" "$KIRO_GSTACK"
for skill_dir in "$KIRO_DIR"/gstack*/; do
[ -f "$skill_dir/SKILL.md" ] || continue
skill_name="$(basename "$skill_dir")"
@@ -3630,6 +3617,14 @@ if [ "$INSTALL_CODEX" -eq 1 ]; then
_setup_arm_publish codex "$_CX_SCOPE" "$_CX_PROJECT" "$CODEX_SKILLS" "$CODEX_GSTACK" - "${_CODEX_RENDER_ROOT:-committed}"
fi
# 7b. Prune the skill renders of hosts this checkout does not serve (#1694),
# on every run, so each install converges on its own recorded hosts even when
# several installs share one state root. Generated files go to the state
# root's backups; anything not proven generated stays in place.
if ! gstack_prune_host_renders "$SOURCE_GSTACK_DIR"; then
echo " warning: some generated host renders could not be backed up, so they were left in place; the next ./setup retries" >&2
fi
# 8. Run pending version migrations
# Migrations handle state fixes that ./setup alone can't cover (stale config,
# orphaned files, directory structure changes). Each migration is idempotent.
+1 -1
View File
@@ -93,7 +93,7 @@ describe.skipIf(process.platform === 'win32')('Codex global install: the freeze
const rootDir = path.join(codexHome, 'skills', 'gstack');
const project = path.join(sandbox, 'project', 'src');
fs.mkdirSync(project, { recursive: true });
const functions = ['_link_or_copy', '_link_runtime_dists', '_copy_skill_md', '_gstack_generated_header', 'create_codex_runtime_root']
const functions = ['_link_or_copy', '_link_runtime_dists', '_copy_runtime_skill_refs', '_copy_skill_md', '_gstack_generated_header', 'create_codex_runtime_root']
.filter(name => SETUP_SRC.includes(`\n${name}() {`)).map(extractFunction).join('\n');
const built = spawnSync('bash', ['-c', `IS_WINDOWS=0\n_CODEX_RENDER_ROOT="${renderDir}"\n${functions}\ncreate_codex_runtime_root "${ROOT}" "${rootDir}"`],
{ encoding: 'utf8', timeout: 30_000, env: { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: home } });
+14 -11
View File
@@ -3665,13 +3665,13 @@ describe('setup script validation', () => {
expect(fnBody).toContain('browse/dist');
expect(fnBody).toContain('browse/bin');
expect(fnBody).toContain('gstack-upgrade/SKILL.md');
expect(fnBody).toContain('checklist.md');
expect(fnBody).toContain('TODOS-format.md');
// Review checklists and the other read-on-demand files come from the shared
// helpers, the same set every env-var root gets (#1077 residue): the Cursor
// render reads design-checklist.md and review/specialists too.
expect(fnBody).toContain('_link_runtime_dists "$gstack_dir" "$cursor_gstack"');
expect(fnBody).toContain('_copy_runtime_skill_refs "$cursor_dir" "$cursor_gstack"');
// bin scripts import ../lib — the two must travel together.
expect(fnBody).toContain('$cursor_gstack/lib');
expect(fnBody).not.toContain('design-checklist.md');
expect(fnBody).not.toContain('greptile-triage.md');
expect(fnBody).not.toContain('review/specialists');
expect(fnBody).not.toContain('qa/templates');
expect(fnBody).not.toContain('_link_or_copy "$gstack_dir" "$cursor_gstack"');
});
@@ -3745,19 +3745,22 @@ describe('setup script validation', () => {
test('create_codex_runtime_root exposes only runtime assets', () => {
const fnStart = setupContent.indexOf('create_codex_runtime_root()');
const fnEnd = setupContent.indexOf('}', setupContent.indexOf('done', setupContent.indexOf('review/', fnStart)));
const fnEnd = setupContent.indexOf('\n}\n', fnStart);
const fnBody = setupContent.slice(fnStart, fnEnd);
expect(fnBody).toContain('gstack/SKILL.md');
expect(fnBody).toContain('$codex_gstack/lib');
expect(fnBody).toContain('browse/dist');
expect(fnBody).toContain('browse/bin');
expect(fnBody).toContain('gstack-upgrade/SKILL.md');
// Review runtime assets (individual files, not the whole dir)
expect(fnBody).toContain('checklist.md');
expect(fnBody).toContain('design-checklist.md');
expect(fnBody).toContain('greptile-triage.md');
expect(fnBody).toContain('TODOS-format.md');
expect(fnBody).toContain('_link_runtime_dists "$gstack_dir" "$codex_gstack"');
expect(fnBody).not.toContain('_link_or_copy "$gstack_dir" "$codex_gstack"');
// Review runtime assets: individual files from the shared helper, never
// the whole review/ dir, which has a SKILL.md.
const shared = setupContent.slice(setupContent.indexOf('_link_runtime_dists() {'), setupContent.indexOf('_copy_runtime_skill_refs() {'));
for (const f of ['review/checklist.md', 'review/design-checklist.md', 'review/greptile-triage.md', 'review/TODOS-format.md']) {
expect(shared).toContain(f);
}
expect(shared).not.toMatch(/for d in [^;]*\breview(?:\s|;)/);
});
test('create_factory_runtime_root links shared lib modules beside bin', () => {
+168
View File
@@ -0,0 +1,168 @@
/**
* #1694: renders of hosts an install does not serve are pruned safely.
*
* Every ./setup (and the gstack-upgrade migration) removes the render dirs of
* hosts missing from the installed-hosts record with bin/gstack-relink's proof
* rules: a symlink into the checkout (STRONG) goes; a file proven generated
* (WEAK: gen-skill-docs' banner, the generator's openai.yaml shape, byte
* identity) is moved to $GSTACK_STATE_ROOT/backups/host-renders/; anything
* else stays; only emptied directories are removed. The legacy layout here is
* a real `--host all` render.
*/
import { afterAll, afterEach, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { runGeneration } from '../scripts/gen-skill-docs';
import { cleanupFixtures, cleanupSeed, makeFixture, makeSource, put, runSetup, type Fixture } from './helpers/install-fixture';
const ROOT = path.resolve(import.meta.dir, '..');
const OTHER_DIRS = ['.agents', '.factory', '.kiro', '.opencode', '.cursor', '.copilot', '.slate', '.openclaw', '.hermes', '.gbrain'];
afterEach(cleanupFixtures);
afterAll(cleanupSeed);
const skillFiles = (dir: string): string[] => !fs.existsSync(dir) ? []
: (fs.readdirSync(dir, { recursive: true }) as string[]).filter(rel => path.basename(rel) === 'SKILL.md' && fs.statSync(path.join(dir, rel)).isFile());
async function legacyRender(src: string): Promise<void> {
const result = await runGeneration({ host: 'all', outputRoot: src });
if (result.exitCode !== 0) throw new Error('legacy render failed');
}
function backups(f: Fixture): string[] {
const dir = path.join(f.home, '.gstack/backups/host-renders');
return fs.existsSync(dir) ? fs.readdirSync(dir).map(d => path.join(dir, d)) : [];
}
function setupOk(f: Fixture, src: string, args: string[] = []) {
const r = runSetup(f, path.join(src, 'setup'), args);
expect(r.status, r.stdout + r.stderr).toBe(0);
return r;
}
describe.skipIf(process.platform === 'win32')('setup prunes unrecorded host renders without losing a file (#1694)', () => {
test('a legacy all-host render inside a Claude install: generated files backed up, user files kept, links handled', async () => {
const f = makeFixture();
const src = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
await legacyRender(src);
const before = skillFiles(src).length;
expect(before).toBeGreaterThan(600);
const customized = path.join(src, '.factory/skills/gstack-qa/SKILL.md');
fs.appendFileSync(customized, '\nMy own QA note.\n');
put(path.join(src, '.factory/notes.md'), 'my notes, no banner\n');
put(path.join(src, '.kiro/skills/my-skill/SKILL.md'), '---\nname: my-skill\n---\nHand-written.\n');
fs.mkdirSync(path.join(src, '.cursor/skills/gstack'), { recursive: true });
fs.symlinkSync(path.join(src, 'bin'), path.join(src, '.cursor/skills/gstack/bin'));
fs.mkdirSync(path.join(f.dir, 'outside'));
fs.symlinkSync(path.join(f.dir, 'outside'), path.join(src, '.cursor/skills/gstack/elsewhere'));
const r = setupOk(f, src);
expect(fs.readFileSync(path.join(src, '.gstack-installed-hosts'), 'utf8')).toEndWith('\nclaude\n');
// Only the Claude skills and the hand-written look-alike remain.
const left = skillFiles(src).filter(rel => rel.startsWith('.'));
expect(left).toEqual(['.kiro/skills/my-skill/SKILL.md']);
expect(before - skillFiles(src).length).toBeGreaterThan(550);
expect(fs.readdirSync(path.join(src, '.factory'), { recursive: true })).toEqual(['notes.md']);
expect(fs.lstatSync(path.join(src, '.cursor/skills/gstack/elsewhere')).isSymbolicLink()).toBe(true);
expect(fs.existsSync(path.join(f.dir, 'outside'))).toBe(true);
expect(fs.existsSync(path.join(src, '.cursor/skills/gstack/bin'))).toBe(false);
expect(fs.existsSync(path.join(src, 'bin/gstack-config'))).toBe(true);
for (const dir of ['.agents', '.opencode', '.copilot', '.slate', '.openclaw', '.hermes', '.gbrain']) expect(fs.existsSync(path.join(src, dir)), dir).toBe(false);
expect(r.stdout).toContain('kept .factory/notes.md: not proven generated (no gstack banner or byte match)');
expect(r.stdout).toContain('kept .kiro/skills/my-skill/SKILL.md: not proven generated');
expect(r.stdout).toContain('kept .cursor/skills/gstack/elsewhere: links outside this checkout');
expect(r.stdout).toMatch(/pruned \.factory \(factory is not installed from this checkout\): \d+ generated files backed up, 0 links removed, \d+ empty dirs removed, 1 kept/);
const [backup] = backups(f);
expect(backups(f)).toHaveLength(1);
expect(r.stdout).toContain(`host-render backup: ${backup} (every path: ${backup}/prune.log; restore a file with mv)`);
expect(fs.readFileSync(path.join(backup!, '.factory/skills/gstack-qa/SKILL.md'), 'utf8')).toEndWith('\nMy own QA note.\n');
const log = fs.readFileSync(path.join(backup!, 'prune.log'), 'utf8');
expect(log).toContain('backed up\t.agents/skills/gstack-qa/agents/openai.yaml\tgenerated');
expect(log).toContain('backed up\t.hermes/skills/gstack-qa/SKILL.md\tgenerated');
expect(log).toContain(`removed link\t.cursor/skills/gstack/bin\t-> ${src}/bin`);
expect(log).toContain('kept\t.factory/notes.md\tnot proven generated');
expect(log).toContain('removed dir\t.agents\tempty');
const again = setupOk(f, src);
expect(again.stdout).not.toContain('pruned ');
expect(again.stdout).not.toContain('host-render backup');
expect(backups(f)).toHaveLength(1);
}, 240_000);
test('two installs sharing one state root each end with only their own hosts', async () => {
const f = makeFixture();
const a = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
const b = makeSource(f, path.join(f.home, 'src-b/gstack'));
await legacyRender(a);
await legacyRender(b);
setupOk(f, a);
setupOk(f, b, ['--host', 'codex']);
for (const dir of OTHER_DIRS) expect(fs.existsSync(path.join(a, dir)), `a ${dir}`).toBe(false);
expect(skillFiles(path.join(b, '.agents')).length).toBeGreaterThan(40);
for (const dir of OTHER_DIRS.filter(d => d !== '.agents')) expect(fs.existsSync(path.join(b, dir)), `b ${dir}`).toBe(false);
expect(backups(f)).toHaveLength(2);
}, 240_000);
test('a host whose skills link into the render is kept even with no registry row', async () => {
const f = makeFixture();
const src = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
await legacyRender(src);
fs.mkdirSync(path.join(f.home, '.factory/skills'), { recursive: true });
fs.symlinkSync(path.join(src, '.factory/skills/gstack-qa'), path.join(f.home, '.factory/skills/gstack-qa'));
setupOk(f, src);
expect(fs.readFileSync(path.join(src, '.gstack-installed-hosts'), 'utf8')).toEndWith('\nclaude\nfactory\n');
expect(skillFiles(path.join(src, '.factory')).length).toBeGreaterThan(40);
expect(fs.existsSync(path.join(f.home, '.factory/skills/gstack-qa/SKILL.md'))).toBe(true);
}, 240_000);
});
describe.skipIf(process.platform === 'win32')('gstack-upgrade migration prunes existing installs (#1694)', () => {
const migrations = fs.readdirSync(path.join(ROOT, 'gstack-upgrade/migrations'))
.filter(n => fs.readFileSync(path.join(ROOT, 'gstack-upgrade/migrations', n), 'utf8').includes('gstack-host-renders.sh'));
test('exactly one migration owns the prune, and setup runs it (not newer than VERSION)', () => {
expect(migrations).toEqual([expect.stringMatching(/^v\d+\.\d+\.\d+\.\d+\.sh$/)]);
const parts = (v: string) => v.split('.').map(Number);
const mine = parts(migrations[0]!.slice(1, -3));
const version = parts(fs.readFileSync(path.join(ROOT, 'VERSION'), 'utf8').trim());
const cmp = mine.map((n, i) => n - version[i]!).find(d => d !== 0) ?? 0;
expect(cmp).toBeLessThanOrEqual(0);
});
function migrate(f: Fixture, install: string) {
return spawnSync('bash', [path.join(install, 'gstack-upgrade/migrations', migrations[0]!)], {
cwd: f.home, encoding: 'utf8', timeout: 60_000, env: { ...f.env, GSTACK_INSTALL_DIR: install },
});
}
test('a pre-record Claude install: renders of other hosts are backed up and removed, a look-alike survives, rerun is a no-op', async () => {
const f = makeFixture();
const src = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
await legacyRender(src);
put(path.join(src, '.opencode/skills/mine/SKILL.md'), 'no banner\n');
const r = migrate(f, src);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(fs.readFileSync(path.join(src, '.gstack-installed-hosts'), 'utf8')).toEndWith('\nclaude\n');
expect(skillFiles(src).filter(rel => rel.startsWith('.'))).toEqual(['.opencode/skills/mine/SKILL.md']);
expect(r.stdout).toContain('kept .opencode/skills/mine/SKILL.md: not proven generated');
expect(backups(f)).toHaveLength(1);
const again = migrate(f, src);
expect(again.status).toBe(0);
expect(again.stdout).not.toContain('pruned ');
expect(backups(f)).toHaveLength(1);
}, 240_000);
test('a checkout no install points at is left alone', async () => {
const f = makeFixture();
const src = makeSource(f, path.join(f.home, 'elsewhere/gstack'));
await legacyRender(src);
const before = skillFiles(src).length;
const r = migrate(f, src);
expect(r.status).toBe(0);
expect(r.stdout).toContain(`host renders: no install from ${src} was found, so its renders were left alone`);
expect(skillFiles(src).length).toBe(before);
expect(fs.existsSync(path.join(src, '.gstack-installed-hosts'))).toBe(false);
}, 240_000);
});
+172
View File
@@ -0,0 +1,172 @@
/**
* #1694: an install renders skills only for the hosts installed from it.
*
* `./setup` used to run `gen:skill-docs --host all` inside the install, so a
* global Claude install at ~/.claude/skills/gstack carried 632 SKILL.md files
* (34.7 MB): every other host's render, all scanned by Claude Code and
* Cursor-agent. setup now keeps an additive record of the hosts it installed
* ($ROOT/.gstack-installed-hosts, owned by bin/gstack-host-renders.sh) and
* scripts/build.sh renders claude plus those hosts. A checkout with no record
* (development) or GSTACK_RENDER_HOSTS=all still renders every host.
*/
import { afterAll, afterEach, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { ALL_HOST_CONFIGS } from '../hosts';
import { cleanupFixtures, cleanupSeed, makeFixture, makeSource, owned, registryRows, runSetup } from './helpers/install-fixture';
const ROOT = path.resolve(import.meta.dir, '..');
const HELPER = path.join(ROOT, 'bin/gstack-host-renders.sh');
const BUILD = fs.readFileSync(path.join(ROOT, 'scripts/build.sh'), 'utf8');
const RENDER_BLOCK = BUILD.slice(BUILD.indexOf('. "$ROOT/bin/gstack-host-renders.sh"'), BUILD.indexOf('\n"$BUN_CMD" build --compile'));
const RENDER_DIRS = ALL_HOST_CONFIGS.filter(h => h.name !== 'claude').map(h => h.hostSubdir);
afterEach(cleanupFixtures);
afterAll(cleanupSeed);
function tmpRoot(): string {
const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-host-renders-')));
owned.push(dir);
return dir;
}
function sh(script: string, env: Record<string, string> = {}, cwd?: string) {
return spawnSync('bash', ['-c', `set -e\n. "${HELPER}"\n${script}`], {
cwd, encoding: 'utf8', timeout: 60_000, env: { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: os.tmpdir(), ...env },
});
}
const skillCount = (dir: string): number => !fs.existsSync(dir) ? 0
: fs.readdirSync(dir, { withFileTypes: true, recursive: true }).filter(e => e.isFile() && e.name === 'SKILL.md').length;
describe.skipIf(process.platform === 'win32')('installed-hosts record (bin/gstack-host-renders.sh)', () => {
test('its host -> render dir table matches hostSubdir in hosts/*.ts', () => {
const table = sh('printf "%s\\n" $GSTACK_HOST_RENDER_DIRS').stdout.trim().split('\n').sort();
expect(table).toEqual(ALL_HOST_CONFIGS.filter(h => h.name !== 'claude').map(h => `${h.name}:${h.hostSubdir}`).sort());
});
test('adding is additive, sorted and ignores unknown names; an unchanged set is not rewritten', () => {
const root = tmpRoot();
const file = path.join(root, '.gstack-installed-hosts');
expect(sh(`gstack_render_hosts_add "${root}" codex claude`).status).toBe(0);
expect(sh(`gstack_render_hosts_add "${root}" factory nonsense`).status).toBe(0);
expect(sh(`gstack_render_hosts_read "${root}"`).stdout).toBe('claude\ncodex\nfactory\n');
expect(fs.readFileSync(file, 'utf8')).toContain('# Hosts installed from this gstack checkout');
const stamp = new Date('2001-01-01');
fs.utimesSync(file, stamp, stamp);
expect(sh(`gstack_render_hosts_add "${root}" codex`).status).toBe(0);
expect(fs.statSync(file).mtime.getTime()).toBe(stamp.getTime());
fs.appendFileSync(file, 'hermes # rendered by hand\n\nbogus\n');
expect(sh(`gstack_render_hosts_read "${root}"`).stdout).toBe('claude\ncodex\nfactory\nhermes\n');
});
test('selection: no record renders every host; a record renders claude plus its hosts; GSTACK_RENDER_HOSTS=all overrides', () => {
const root = tmpRoot();
const select = (env: Record<string, string> = {}) => sh(`gstack_render_hosts_select "${root}"; echo "$GSTACK_RENDER_HOST_LIST|$GSTACK_RENDER_HOST_REASON"`, env);
expect(select().stdout).toBe('all|no installed-hosts record, so this is a development checkout\n');
sh(`gstack_render_hosts_add "${root}" codex`);
expect(select().stdout).toStartWith('claude codex|recorded in ');
expect(select({ GSTACK_RENDER_HOSTS: 'all' }).stdout).toBe('all|GSTACK_RENDER_HOSTS=all\n');
const odd = select({ GSTACK_RENDER_HOSTS: 'codex' });
expect(odd.stdout).toStartWith('claude codex|');
expect(odd.stderr).toContain("GSTACK_RENDER_HOSTS accepts only 'all' (got 'codex'); ignoring it");
});
});
describe.skipIf(process.platform === 'win32')('scripts/build.sh renders the recorded hosts (#1694)', () => {
// build.sh's render step with a bun that only records its arguments.
function renderCalls(root: string, env: Record<string, string> = {}) {
fs.mkdirSync(path.join(root, 'bin'), { recursive: true });
fs.copyFileSync(HELPER, path.join(root, 'bin/gstack-host-renders.sh'));
const bun = path.join(root, 'fake-bun');
fs.writeFileSync(bun, `#!/bin/sh\necho "$*" >> "${root}/bun.log"\n`, { mode: 0o755 });
const r = spawnSync('bash', ['-c', `set -e\nROOT="${root}"\nBUN_CMD="${bun}"\n${RENDER_BLOCK}`], {
cwd: root, encoding: 'utf8', timeout: 30_000, env: { PATH: process.env.PATH ?? '/usr/bin:/bin', ...env },
});
const log = fs.existsSync(path.join(root, 'bun.log')) ? fs.readFileSync(path.join(root, 'bun.log'), 'utf8') : '';
return { ...r, calls: log.trim().split('\n') };
}
test('a development checkout (no record) renders every host and says why', () => {
const r = renderCalls(tmpRoot());
expect(r.status, r.stderr).toBe(0);
expect(r.calls).toEqual(['run gen:skill-docs --host all']);
expect(r.stdout).toContain('Rendering skills for every host: no installed-hosts record, so this is a development checkout');
});
test('an install renders claude, then each recorded host, and prints them', () => {
const root = tmpRoot();
fs.writeFileSync(path.join(root, '.gstack-installed-hosts'), 'codex\nfactory\n');
const r = renderCalls(root);
expect(r.status, r.stderr).toBe(0);
expect(r.calls).toEqual(['run gen:skill-docs --host claude', 'run gen:skill-docs --host codex', 'run gen:skill-docs --host factory']);
expect(r.stdout).toContain(`Rendering skills for: claude codex factory (recorded in ${root}/.gstack-installed-hosts; GSTACK_RENDER_HOSTS=all renders every host)`);
});
test('GSTACK_RENDER_HOSTS=all renders every host inside an install', () => {
const root = tmpRoot();
fs.writeFileSync(path.join(root, '.gstack-installed-hosts'), 'claude\n');
const r = renderCalls(root, { GSTACK_RENDER_HOSTS: 'all' });
expect(r.calls).toEqual(['run gen:skill-docs --host all']);
expect(r.stdout).toContain('Rendering skills for every host: GSTACK_RENDER_HOSTS=all');
});
test('a real render inside a Claude install leaves no other host SKILL.md; a development checkout still renders all', () => {
const f = makeFixture();
const install = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
const dev = makeSource(f, path.join(f.home, 'dev/gstack'));
fs.writeFileSync(path.join(install, '.gstack-installed-hosts'), 'claude\n');
for (const root of [install, dev]) {
const r = spawnSync('bash', ['-c', `set -e\nROOT="${root}"\nBUN_CMD=bun\n${RENDER_BLOCK}`], {
cwd: root, encoding: 'utf8', timeout: 120_000, env: f.env,
});
expect(r.status, r.stdout + r.stderr).toBe(0);
}
for (const dir of RENDER_DIRS) {
expect(skillCount(path.join(install, dir)), dir).toBe(0);
expect(skillCount(path.join(dev, dir)), dir).toBeGreaterThan(40);
}
expect(skillCount(install)).toBeLessThan(100);
expect(skillCount(dev)).toBeGreaterThan(500);
}, 180_000);
});
describe.skipIf(process.platform === 'win32')('setup records each host it installs and never forgets one', () => {
test('claude, then codex, then factory: the record grows and each recorded host keeps its render', () => {
const f = makeFixture();
const src = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
const setup = (args: string[]) => {
const r = runSetup(f, path.join(src, 'setup'), args);
expect(r.status, r.stdout + r.stderr).toBe(0);
return fs.readFileSync(path.join(src, '.gstack-installed-hosts'), 'utf8').split('\n').filter(l => l && !l.startsWith('#'));
};
expect(setup([])).toEqual(['claude']);
expect(fs.existsSync(path.join(src, '.agents'))).toBe(false);
expect(setup(['--host', 'codex'])).toEqual(['claude', 'codex']);
expect(skillCount(path.join(src, '.agents'))).toBeGreaterThan(40);
expect(setup(['--host', 'factory'])).toEqual(['claude', 'codex', 'factory']);
expect(skillCount(path.join(src, '.agents'))).toBeGreaterThan(40);
expect(skillCount(path.join(src, '.factory'))).toBeGreaterThan(40);
// The updater path (/gstack-upgrade and gstack-session-update) refreshes
// every registered install; the record and both renders survive it.
const r = runSetup(f, path.join(src, 'setup'), ['--refresh-registered']);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(registryRows(f).map(row => row[0]).sort()).toEqual(['claude', 'codex', 'factory']);
expect(setup([])).toEqual(['claude', 'codex', 'factory']);
expect(skillCount(path.join(src, '.agents'))).toBeGreaterThan(40);
expect(skillCount(path.join(src, '.factory'))).toBeGreaterThan(40);
for (const dir of RENDER_DIRS.filter(d => d !== '.agents' && d !== '.factory')) expect(fs.existsSync(path.join(src, dir)), dir).toBe(false);
}, 240_000);
test('an install made before the record keeps the hosts the registry says it serves', () => {
const f = makeFixture();
const src = makeSource(f, path.join(f.home, '.claude/skills/gstack'));
expect(runSetup(f, path.join(src, 'setup'), ['--host', 'factory']).status).toBe(0);
fs.rmSync(path.join(src, '.gstack-installed-hosts'));
const r = runSetup(f, path.join(src, 'setup'), []);
expect(r.status, r.stdout + r.stderr).toBe(0);
expect(fs.readFileSync(path.join(src, '.gstack-installed-hosts'), 'utf8')).toContain('\nclaude\nfactory\n');
}, 120_000);
});
+1 -1
View File
@@ -529,7 +529,7 @@ describe('installed QA pointers', () => {
'_gstack_generated_header', '_claude_entry_owned_strongly', '_claude_entry_is_ours', '_write_owned_marker',
'_backup_skill_md', '_cleanup_weak_dir', '_gstack_dir_only_links', '_cleanup_linked_dir',
'_owned_for_windows_refresh', '_sidecar_root_user_owned', '_prune_stale_generated', '_skill_source_exists',
'_link_runtime_dists', '_copy_skill_md', '_skill_copy_hash', '_skill_copy_unmodified', '_preserve_skill_copy_edits', '_record_skill_copies',
'_link_runtime_dists', '_copy_runtime_skill_refs', '_copy_skill_md', '_skill_copy_hash', '_skill_copy_unmodified', '_preserve_skill_copy_edits', '_record_skill_copies',
].map(setupFunction).join('\n')
// Install-registry rows (setup's _setup_arm_* / _setup_row) are not under test here.
+ '\n_setup_arm_begin() { :; }\n_setup_arm_publish() { :; }\n_setup_row() { :; }';
+156
View File
@@ -0,0 +1,156 @@
/**
* Every file a generated skill reads through $GSTACK_ROOT exists in the
* runtime root setup builds for that host (#1077 residue, fix wave C2).
*
* Env-var hosts reach gstack only through their runtime root
* (~/.codex/skills/gstack, ~/.factory/skills/gstack, ...). The roots carried
* bin/, lib/ and the compiled tools, but not the files the shared preamble and
* several skills read on demand: the jargon list and question registry, the
* AskUserQuestion split and CJK docs, the DX Hall of Fame, the test-value bar,
* VERSION, design-html's vendored pretext.js and plan-design-review/SKILL.md.
* Those reads failed silently on every non-Claude host.
*
* This test renders every host, builds each runtime root with setup's own
* shell functions, then checks every $GSTACK_ROOT/<path> literal in that
* host's render (prose and fences) against the staged root on disk.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { spawnSync } from 'child_process';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { HOST_CONFIG_MAP } from '../hosts';
import { runGeneration } from '../scripts/gen-skill-docs';
const ROOT = path.resolve(import.meta.dir, '..');
const SETUP_SRC = fs.readFileSync(path.join(ROOT, 'setup'), 'utf-8');
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-root-assets-'));
const renderDir = path.join(tmp, 'render');
const src = path.join(tmp, 'gstack');
// Host -> the setup function that builds its global runtime root. Kiro builds
// its root inline in the Kiro arm and is covered by a source assertion below.
const ROOT_BUILDERS: Record<string, string> = {
codex: 'create_codex_runtime_root',
factory: 'create_factory_runtime_root',
opencode: 'create_opencode_runtime_root',
cursor: 'create_cursor_runtime_root',
copilot: 'create_copilot_runtime_root',
};
// Deferred, with the reason recorded in TODOS.md: /ship's measure loop runs
// scripts/ship-measure.ts, which imports gstack's test helpers and eval
// harness; a runtime root would need the whole development tree.
const DEFERRED = new Set(['scripts/ship-measure.ts']);
// Compiled outputs: the stub source carries placeholder binaries, so a fresh
// checkout without a build still exercises the links to them.
const BUILT = ['browse/dist/browse', 'browse/dist/find-browse', 'design/dist/design', 'make-pdf/dist/pdf'];
// Compiled into bin/, which every root links whole: checked through that link.
const BUILT_IN_BIN = new Set(['bin/gstack-global-discover']);
function extractFunction(name: string): string {
const start = SETUP_SRC.indexOf(`\n${name}() {`);
const end = SETUP_SRC.indexOf('\n}\n', start);
if (start < 0 || end < 0) throw new Error(`Could not locate ${name}() in setup`);
return SETUP_SRC.slice(start + 1, end + 2);
}
function walk(dir: string): string[] {
return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e =>
e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
}
/** Every $GSTACK_ROOT/<path> literal in a host's rendered skills. */
function referencedPaths(host: string): Set<string> {
const out = new Set<string>();
for (const file of walk(path.join(renderDir, HOST_CONFIG_MAP[host]!.hostSubdir, 'skills'))) {
for (const m of fs.readFileSync(file, 'utf8').matchAll(/\$\{?GSTACK_ROOT\}?\/([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)/g)) {
out.add(m[1]!.replace(/\.+$/, ''));
}
}
return out;
}
// A source tree that links every tracked top-level entry of this checkout,
// with stub compiled binaries and each host's render in its usual place.
function makeSource(): void {
fs.mkdirSync(src, { recursive: true });
const built = new Set(BUILT.map(rel => rel.split('/')[0]!));
for (const name of fs.readdirSync(ROOT)) {
if (name.startsWith('.') || name === 'node_modules') continue;
if (!built.has(name)) { fs.symlinkSync(path.join(ROOT, name), path.join(src, name)); continue; }
fs.mkdirSync(path.join(src, name));
for (const child of fs.readdirSync(path.join(ROOT, name))) {
if (child !== 'dist') fs.symlinkSync(path.join(ROOT, name, child), path.join(src, name, child));
}
}
for (const rel of BUILT) {
fs.mkdirSync(path.dirname(path.join(src, rel)), { recursive: true });
fs.writeFileSync(path.join(src, rel), '#!/bin/sh\nexit 0\n', { mode: 0o755 });
}
for (const host of Object.keys(ROOT_BUILDERS)) {
const sub = HOST_CONFIG_MAP[host]!.hostSubdir;
fs.symlinkSync(path.join(renderDir, sub), path.join(src, sub));
}
}
function buildRoot(host: string): { root: string; stderr: string; status: number | null } {
const root = path.join(tmp, 'home', host, 'skills', 'gstack');
fs.mkdirSync(path.dirname(root), { recursive: true });
const functions = ['_link_or_copy', '_link_runtime_dists', '_copy_runtime_skill_refs', '_copy_skill_md',
'_sidecar_root_user_owned', '_gstack_generated_header', ROOT_BUILDERS[host]!]
.filter(name => SETUP_SRC.includes(`\n${name}() {`)).map(extractFunction).join('\n');
const r = spawnSync('bash', ['-c', `set -e\nIS_WINDOWS=0\n${functions}\n${ROOT_BUILDERS[host]} "${src}" "${root}"`],
{ encoding: 'utf8', timeout: 30_000, env: { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: path.join(tmp, 'home') } });
return { root, stderr: r.stderr, status: r.status };
}
beforeAll(async () => {
const result = await runGeneration({ host: 'all', outputRoot: renderDir });
if (result.exitCode !== 0) throw new Error(result.diagnostics.filter(d => d.kind === 'error').map(d => d.message).join('\n'));
makeSource();
});
afterAll(() => fs.rmSync(tmp, { recursive: true, force: true }));
describe.skipIf(process.platform === 'win32')('runtime roots carry every $GSTACK_ROOT file their skills read', () => {
test('the extractor finds the known read-on-demand files in the Codex render', () => {
const paths = referencedPaths('codex');
for (const rel of ['scripts/jargon-list.json', 'scripts/question-registry.ts', 'docs/askuserquestion-split.md', 'plan-devex-review/dx-hall-of-fame.md']) {
expect(paths.has(rel), rel).toBe(true);
}
});
for (const host of Object.keys(ROOT_BUILDERS)) {
test(`${host}: every referenced path exists in the staged runtime root`, () => {
const { root, stderr, status } = buildRoot(host);
expect(stderr).toBe('');
expect(status).toBe(0);
const missing = [...referencedPaths(host)]
.filter(rel => !DEFERRED.has(rel) && !BUILT_IN_BIN.has(rel) && !fs.existsSync(path.join(root, rel))).sort();
expect(missing).toEqual([]);
// Each one is the same kind of entry as in the source: a file stays a file.
const wrongKind = [...referencedPaths(host)].filter(rel => fs.existsSync(path.join(root, rel)) && fs.existsSync(path.join(ROOT, rel))
&& fs.statSync(path.join(root, rel)).isFile() !== fs.statSync(path.join(ROOT, rel)).isFile());
expect(wrongKind).toEqual([]);
expect(fs.realpathSync(path.join(root, 'bin'))).toBe(fs.realpathSync(path.join(ROOT, 'bin')));
});
}
test('a runtime root never gains a whole skill directory beside the rendered copies', () => {
const { root } = buildRoot('codex');
for (const dir of ['plan-design-review', 'office-hours']) {
expect(fs.readdirSync(path.join(root, dir))).toEqual(['SKILL.md']);
expect(fs.lstatSync(path.join(root, dir, 'SKILL.md')).isSymbolicLink()).toBe(false);
expect(fs.readFileSync(path.join(root, dir, 'SKILL.md'), 'utf8')).toContain('$GSTACK_ROOT');
}
expect(fs.existsSync(path.join(root, 'design-html', 'SKILL.md'))).toBe(false);
expect(fs.existsSync(path.join(root, 'plan-devex-review', 'SKILL.md'))).toBe(false);
});
test('the Kiro arm uses the same shared asset helpers as every other root', () => {
const arm = SETUP_SRC.slice(SETUP_SRC.indexOf('# 6. Install for Kiro CLI'), SETUP_SRC.indexOf('# 6b. Install for Factory Droid'));
expect(arm.includes('_link_runtime_dists "$SOURCE_GSTACK_DIR" "$KIRO_GSTACK"')).toBe(true);
expect(arm.includes('_copy_runtime_skill_refs "$KIRO_DIR" "$KIRO_GSTACK"')).toBe(true);
});
});
+1 -1
View File
@@ -30,7 +30,7 @@ function fixture(copy: boolean) {
put(path.join(root, 'VERSION'), '2.0.0.0\n');
put(path.join(root, 'ETHOS.md'), 'Fixture ethos\n');
put(path.join(root, 'package.json'), JSON.stringify({ type: 'module', scripts: { 'gen:skill-docs': 'bun run scripts/gen-skill-docs.ts' } }));
for (const bin of ['gstack-config', 'gstack-patch-names', 'gstack-relink', 'gstack-migrate-claude-code', 'gstack-claude-code', 'gstack-models', 'gstack-state-root.sh', 'gstack-bun-version.sh', 'gstack-install-registry.sh', 'gstack-render-claude.sh']) {
for (const bin of ['gstack-config', 'gstack-patch-names', 'gstack-relink', 'gstack-migrate-claude-code', 'gstack-claude-code', 'gstack-models', 'gstack-state-root.sh', 'gstack-bun-version.sh', 'gstack-install-registry.sh', 'gstack-render-claude.sh', 'gstack-host-renders.sh']) {
const target = path.join(root, 'bin', bin);
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.copyFileSync(path.join(ROOT, 'bin', bin), target);
+1 -1
View File
@@ -97,7 +97,7 @@ const BUILDERS: Record<string, (sandbox: string, src: string) => Built> = {
},
};
const FUNCTIONS = ['_link_or_copy', '_link_runtime_dists', '_copy_skill_md', '_sidecar_root_user_owned', '_gstack_generated_header', 'create_agents_sidecar', 'create_codex_runtime_root']
const FUNCTIONS = ['_link_or_copy', '_link_runtime_dists', '_copy_runtime_skill_refs', '_copy_skill_md', '_sidecar_root_user_owned', '_gstack_generated_header', 'create_agents_sidecar', 'create_codex_runtime_root']
.filter(name => SETUP_SRC.includes(`\n${name}() {`))
.map(extractFunction)
.join('\n');
+1 -1
View File
@@ -17,7 +17,7 @@ const fn = (name: string) => {
const blockStart = setup.indexOf('# 6. Install for Kiro CLI');
const block = setup.slice(blockStart, setup.indexOf('# 6b.', blockStart));
const helpers = [
'_link_or_copy', '_link_runtime_dists', '_sidecar_root_user_owned', '_claude_entry_is_ours',
'_link_or_copy', '_link_runtime_dists', '_copy_runtime_skill_refs', '_sidecar_root_user_owned', '_claude_entry_is_ours',
'_claude_entry_owned_strongly', '_gstack_link_target_abs', '_gstack_target_is_ours',
'_gstack_generated_header', '_backup_skill_md', '_prune_stale_generated',
'_skill_source_exists', '_owned_for_windows_refresh', '_cleanup_weak_dir',
+1
View File
@@ -160,6 +160,7 @@ function runInstaller(
extraVars,
extractFn('_link_or_copy'),
extractFn('_link_runtime_dists'),
extractFn('_copy_runtime_skill_refs'),
// Ownership gates (#2142) — dependencies of every installer under test.
extractFn('_owned_for_windows_refresh'),
extractFn('_sidecar_root_user_owned'),
+1 -1
View File
@@ -455,7 +455,7 @@ describe('setup --team / --no-team / -q', () => {
try {
for (const rel of [
'setup', 'VERSION', 'SKILL.md', 'qa/SKILL.md', 'bin/gstack-config', 'bin/gstack-patch-names',
'bin/gstack-state-root.sh', 'bin/gstack-bun-version.sh', 'bin/gstack-install-registry.sh', 'bin/gstack-render-claude.sh',
'bin/gstack-state-root.sh', 'bin/gstack-bun-version.sh', 'bin/gstack-install-registry.sh', 'bin/gstack-render-claude.sh', 'bin/gstack-host-renders.sh',
'scripts/resolve-codex-generation-model.ts', 'scripts/models.ts', 'scripts/preflight-codex-overlap.ts',
'scripts/discover-skills.ts', 'scripts/external-skill-names.ts', 'scripts/host-config.ts',
'lib/claude-code-migration.ts', 'lib/model-policy.ts', 'lib/model-catalog.ts',