Files
gstack/test/user-render-out-dir-install.test.ts
T
Garry Tanandcapy-ai[bot] b1c32824fd Keep skill_prefix after updates, retire the ClawHub install route, and stop misreading cross-repo issue refs (GST-2967) (#4454)
Three small fixes: `skill_prefix=true` now survives updates when gbrain
is installed, the OpenClaw docs stop sending people to stale ClawHub
skills, and `gstack-issue-links` no longer reads other repositories'
issue numbers as gstack issues.

Why: each one misleads users or /ship today (wrong skill names after
every update, April 2026 skill builds, wrong `Refs #N` lines in PR
bodies).

Nothing to do as a reader. Thanks @fliaron (#4413) and @exGeni (#4421)
for the detailed reports.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-17 17:13:42 +00:00

354 lines
17 KiB
TypeScript

/**
* :user render never dirties the global-git install (#2569).
*
* Pre-v1.67, gbrain-enabled setups ran `gen:skill-docs:user --host claude`
* IN PLACE inside the install checkout, rewriting ~16 tracked SKILL.md files.
* The checkout stayed permanently dirty and every upgrade stashed a redundant
* snapshot of generated content. The fix renders to an untracked out-dir
* (~/.gstack/render/claude) and makes the Claude installers — setup's
* link_claude_skill_dirs AND bin/gstack-relink — prefer rendered files when
* present. A one-time migration (v1.67.0.0.sh) restores the legacy dirt.
*
* (The render mechanism itself — worktree byte-unchanged, section repointing —
* is pinned by test/gen-skill-docs-out-dir.test.ts.)
*/
import { describe, test, expect } from 'bun:test';
import { spawnSync } from 'child_process';
import { runBashScript } from './helpers/bash-script';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
const ROOT = path.resolve(import.meta.dir, '..');
const SETUP_SRC = fs.readFileSync(path.join(ROOT, 'setup'), 'utf-8');
const CONFIG_SRC = fs.readFileSync(path.join(ROOT, 'bin', 'gstack-config'), 'utf-8');
const RELINK_SRC = fs.readFileSync(path.join(ROOT, 'bin', 'gstack-relink'), 'utf-8');
const MIGRATION = path.join(ROOT, 'gstack-upgrade', 'migrations', 'v1.67.0.0.sh');
function extractFn(src: string, name: string): string {
const start = src.indexOf(`${name}() {`);
const end = src.indexOf('\n}\n', start);
if (start < 0 || end < 0) throw new Error(`Could not locate ${name}()`);
return src.slice(start, end + 2);
}
describe(':user render targets the out-dir, never the checkout (#2569)', () => {
test('setup renders gen:skill-docs:user with --out-dir only', () => {
const sites = SETUP_SRC.split('gen:skill-docs:user').length - 1;
const outDirSites = SETUP_SRC.split('gen:skill-docs:user --host claude --out-dir').length - 1;
// Every executable :user invocation carries --out-dir. (Prose/log
// mentions don't pair with `bun_cmd run`.)
const executableSites = SETUP_SRC.split('run gen:skill-docs:user').length - 1;
expect(executableSites).toBeGreaterThan(0);
expect(outDirSites).toBe(executableSites);
expect(sites).toBeGreaterThanOrEqual(outDirSites);
});
test('setup renders into a TMP dir, swaps on success, repoints after (never wipes first)', () => {
const block = SETUP_SRC.slice(
SETUP_SRC.indexOf('# ─── GBrain detection + conditional SKILL.md render'),
SETUP_SRC.indexOf('# 11. Plan-tune cathedral hook install'),
);
// The live render dir is symlinked into by installed skills — it may only
// be replaced AFTER a successful render (a pre-render wipe left every
// brain-aware SKILL.md link dangling on a transient render failure).
expect(block).toContain('--out-dir "$_GSTACK_RENDER_TMP"');
expect(block).not.toContain('--out-dir "$_GSTACK_RENDER_DIR"');
expect(block).toContain('_swap_in_render "$_GSTACK_RENDER_DIR" "$_GSTACK_RENDER_TMP"');
expect(block).toContain('link_claude_skill_dirs "$SOURCE_GSTACK_DIR" "$INSTALL_SKILLS_DIR"');
// Stale-render cleanup on the gbrain-gone path (a deliberate wipe).
expect(block).toContain('gbrain not detected');
expect(block).toContain('rm -rf "$_GSTACK_RENDER_DIR"');
});
test('gstack-config gbrain-refresh renders to a TMP out-dir, swaps on success', () => {
expect(CONFIG_SRC).toContain('gen:skill-docs:user --host claude --out-dir');
expect(CONFIG_SRC).not.toContain("this dirties the install's git tree");
expect(CONFIG_SRC).toContain('gstack-relink');
expect(CONFIG_SRC).toContain('--out-dir "$RENDER_TMP"');
expect(CONFIG_SRC).not.toContain('--out-dir "$RENDER_DIR"');
expect(CONFIG_SRC).toContain('_swap_in_render "$RENDER_DIR" "$RENDER_TMP"');
});
test('_swap_in_render behavior: success replaces, and the shape means failure never touches the live dir', () => {
// Both files carry the same-contract helper — drive each for real.
for (const src of [SETUP_SRC, CONFIG_SRC]) {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-render-swap-'));
try {
const live = path.join(tmp, 'claude');
const fresh = path.join(tmp, 'claude.tmp.123');
fs.mkdirSync(path.join(live, 'ship'), { recursive: true });
fs.writeFileSync(path.join(live, 'ship', 'SKILL.md'), 'old-render\n');
fs.mkdirSync(path.join(fresh, 'ship'), { recursive: true });
fs.writeFileSync(path.join(fresh, 'ship', 'SKILL.md'), 'new-render\n');
const script = [
'set -e',
extractFn(src, '_swap_in_render'),
`_swap_in_render "${live}" "${fresh}"`,
].join('\n');
const r = runBashScript(script, { timeout: 15_000 });
expect(r.status).toBe(0);
// Live dir now serves the fresh render at the SAME path (links into
// it stay valid), tmp and .old are gone.
expect(fs.readFileSync(path.join(live, 'ship', 'SKILL.md'), 'utf-8')).toBe('new-render\n');
expect(fs.existsSync(fresh)).toBe(false);
expect(fs.readdirSync(tmp)).toEqual(['claude']);
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
}
});
test('a FAILED render leaves the previous render dir fully intact (gstack-config path, end-to-end shape)', () => {
// Reconstruct the exact failure branch: render into tmp fails → tmp is
// removed, the live dir (and the symlinks into it) are untouched, and
// _swap_in_render is never called.
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-render-fail-'));
try {
const live = path.join(tmp, 'claude');
fs.mkdirSync(path.join(live, 'ship'), { recursive: true });
fs.writeFileSync(path.join(live, 'ship', 'SKILL.md'), 'previous-render\n');
// An installed skill symlinks into the live render dir.
const installed = path.join(tmp, 'installed-ship-SKILL.md');
fs.symlinkSync(path.join(live, 'ship', 'SKILL.md'), installed);
const script = [
'set -u',
extractFn(CONFIG_SRC, '_swap_in_render'),
`RENDER_DIR="${live}"`,
'RENDER_TMP="$RENDER_DIR.tmp.$$"',
'rm -rf "$RENDER_TMP"',
// The render fails (broken template, bun error, disk full).
'if ( mkdir -p "$RENDER_TMP" && false ); then',
' _swap_in_render "$RENDER_DIR" "$RENDER_TMP"',
'else',
' rm -rf "$RENDER_TMP"',
' echo "render failed — previous render left in place" >&2',
'fi',
].join('\n');
const r = runBashScript(script, { timeout: 15_000 });
expect(r.status).toBe(0);
expect(fs.readFileSync(path.join(live, 'ship', 'SKILL.md'), 'utf-8')).toBe('previous-render\n');
// The installed symlink still resolves — the skill set did not vanish.
expect(fs.readFileSync(installed, 'utf-8')).toBe('previous-render\n');
expect(fs.readdirSync(tmp).sort()).toEqual(['claude', 'installed-ship-SKILL.md']);
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
});
test('gstack-relink prefers the render dir when a rendered SKILL.md exists', () => {
expect(RELINK_SRC).toContain('render/claude');
expect(RELINK_SRC).toContain('[ -f "$RENDER_DIR/$skill/SKILL.md" ] && skill_md_src="$RENDER_DIR/$skill/SKILL.md"');
});
});
// Value: protects=with skill_prefix=true every rendered Claude skill keeps its gstack-<name> after a re-render, because each path that swaps a fresh
// render into a live render dir runs gstack-patch-names on it first; fails_when=a render path (setup's gbrain branch, gstack-config gbrain-refresh,
// gstack_claude_render_plain) swaps in the generator's unprefixed name: fields, the #4413 symptom; why_new=#2738 patched the render only from
// gstack-relink, which setup runs before these renders; seam=none; no_claim=the scan pins the call order, not each path's end-to-end behavior
describe('skill_prefix survives every Claude re-render (#4413)', () => {
const RENDER_HELPER = path.join(ROOT, 'bin', 'gstack-render-claude.sh');
test('every render swap is preceded by gstack-patch-names on the same temp dir', () => {
const sources: Array<[string, string]> = [
['setup', SETUP_SRC],
['bin/gstack-config', CONFIG_SRC],
['bin/gstack-render-claude.sh', fs.readFileSync(RENDER_HELPER, 'utf-8')],
];
let swaps = 0;
for (const [rel, src] of sources) {
const lines = src.split('\n');
lines.forEach((line, i) => {
const m = /^\s*_swap_in_render "([^"]+)" "([^"]+)"/.exec(line);
if (!m) return;
swaps++;
const before = lines.slice(Math.max(0, i - 30), i).join('\n');
expect(before, `${rel}:${i + 1} swaps ${m[2]} in without gstack-patch-names`).toContain(`gstack-patch-names" "${m[2]}"`);
});
}
expect(swaps).toBe(4);
});
function renderPlain(prefix: string) {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-render-prefix-'));
try {
const state = path.join(tmp, 'state');
fs.mkdirSync(state, { recursive: true });
fs.writeFileSync(path.join(state, 'config.yaml'), `skill_prefix: ${prefix}\n`);
const render = path.join(tmp, 'render', 'claude');
const script = [
'set -euo pipefail',
`. ${JSON.stringify(RENDER_HELPER)}`,
extractFn(SETUP_SRC, '_swap_in_render'),
'bun_cmd() {',
' local out="" prev=""',
' for a in "$@"; do [ "$prev" = --out-dir ] && out="$a"; prev="$a"; done',
' mkdir -p "$out/retro" "$out/gstack-upgrade"',
` printf -- '---\\nname: gstack\\n---\\n' > "$out/SKILL.md"`,
` printf -- '---\\nname: retro\\n---\\n' > "$out/retro/SKILL.md"`,
` printf -- '---\\nname: gstack-upgrade\\n---\\n' > "$out/gstack-upgrade/SKILL.md"`,
'}',
'_GSTACK_OVERLAY=claude',
`gstack_claude_render_plain ${JSON.stringify(tmp)} ${JSON.stringify(render)}`,
].join('\n');
const r = runBashScript(script, { timeout: 30_000, env: { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: tmp, GSTACK_STATE_ROOT: state } });
expect(r.status, r.stderr).toBe(0);
const name = (rel: string) => /^name: (.*)$/m.exec(fs.readFileSync(path.join(render, rel), 'utf-8'))?.[1];
return { root: name('SKILL.md'), retro: name('retro/SKILL.md'), upgrade: name('gstack-upgrade/SKILL.md') };
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
}
test('gstack_claude_render_plain serves prefixed names with skill_prefix true and the generator names with it false', () => {
expect(renderPlain('true')).toEqual({ root: 'gstack', retro: 'gstack-retro', upgrade: 'gstack-upgrade' });
expect(renderPlain('false')).toEqual({ root: 'gstack', retro: 'retro', upgrade: 'gstack-upgrade' });
});
});
describe('link_claude_skill_dirs prefers rendered SKILL.md (behavior)', () => {
test('a rendered variant is served; skills without one fall back to source', () => {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-render-pref-'));
try {
const src = path.join(tmp, 'src');
const skills = path.join(tmp, 'skills');
const home = path.join(tmp, 'gstack-home');
// Source tree: two skills.
for (const s of ['alpha', 'beta']) {
fs.mkdirSync(path.join(src, s), { recursive: true });
fs.writeFileSync(
path.join(src, s, 'SKILL.md'),
`---\nname: ${s}\ndescription: t\n---\ncanonical-${s}\n`,
);
}
// Render exists for alpha only.
fs.mkdirSync(path.join(home, 'render', 'claude', 'alpha'), { recursive: true });
fs.writeFileSync(
path.join(home, 'render', 'claude', 'alpha', 'SKILL.md'),
'---\nname: alpha\ndescription: t\n---\nrendered-alpha with Brain Context Load\n',
);
fs.mkdirSync(skills, { recursive: true });
const script = [
'set -e',
'IS_WINDOWS=0',
'SKILL_PREFIX=0',
'_WINDOWS_COPY_NOTE_PRINTED=1',
`GSTACK_HOME="${home}"`,
`GSTACK_STATE_ROOT="${home}"`,
extractFn(SETUP_SRC, '_link_or_copy'),
extractFn(SETUP_SRC, '_print_windows_copy_note_once'),
extractFn(SETUP_SRC, '_link_skill_runtime_assets'),
extractFn(SETUP_SRC, '_gstack_link_target_abs'),
extractFn(SETUP_SRC, '_gstack_target_is_ours'),
extractFn(SETUP_SRC, '_gstack_generated_header'),
extractFn(SETUP_SRC, '_claude_entry_owned_strongly'),
extractFn(SETUP_SRC, '_claude_entry_is_ours'),
extractFn(SETUP_SRC, '_write_owned_marker'),
extractFn(SETUP_SRC, '_backup_skill_md'),
extractFn(SETUP_SRC, '_cleanup_weak_dir'),
extractFn(SETUP_SRC, '_gstack_dir_only_links'),
extractFn(SETUP_SRC, '_cleanup_linked_dir'),
'_FOREIGN_SKIPPED_ENTRIES=()',
'_BACKED_UP_SKILL_MDS=()',
`_SKILL_BACKUP_ROOT="${os.tmpdir()}/gstack-harness-backups-${process.pid}"`,
`. "${path.join(ROOT, 'bin/gstack-skill-name.sh')}"`,
extractFn(SETUP_SRC, 'link_claude_skill_dirs'),
`link_claude_skill_dirs "${src}" "${skills}"`,
].join('\n');
const r = runBashScript(script, { timeout: 15_000 });
expect(r.status).toBe(0);
expect(fs.readFileSync(path.join(skills, 'alpha', 'SKILL.md'), 'utf-8')).toContain('rendered-alpha');
expect(fs.readFileSync(path.join(skills, 'beta', 'SKILL.md'), 'utf-8')).toContain('canonical-beta');
// The SOURCE stayed canonical — the render is served via the link only.
expect(fs.readFileSync(path.join(src, 'alpha', 'SKILL.md'), 'utf-8')).toContain('canonical-alpha');
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
});
});
describe('migration v1.67.0.0 — legacy in-place render cleanup (F12)', () => {
function git(cwd: string, ...args: string[]): void {
const r = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: 30_000 });
if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr}`);
}
function makeLegacyInstall(tmp: string): string {
const install = path.join(tmp, 'install');
fs.mkdirSync(path.join(install, 'ship', 'sections'), { recursive: true });
fs.writeFileSync(path.join(install, 'VERSION'), '1.66.0.0\n');
fs.writeFileSync(path.join(install, 'ship', 'SKILL.md'), 'canonical ship\n');
fs.writeFileSync(path.join(install, 'ship', 'sections', 'tests.md'), 'canonical section\n');
fs.writeFileSync(path.join(install, 'README.md'), 'readme\n');
git(install, 'init', '-b', 'main');
git(install, 'config', 'user.email', 't@t.test');
git(install, 'config', 'user.name', 't');
git(install, 'add', '-A');
git(install, 'commit', '-m', 'base', '-q');
return install;
}
function runMigration(install: string): { status: number | null; stdout: string } {
const r = spawnSync('bash', [MIGRATION], {
encoding: 'utf-8',
env: { ...process.env, GSTACK_INSTALL_DIR: install },
timeout: 15_000,
});
return { status: r.status, stdout: r.stdout };
}
test('restores render-class dirt, leaves user changes alone, idempotent', () => {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-migration-'));
try {
const install = makeLegacyInstall(tmp);
// Legacy render dirt + a genuine user edit + an untracked file.
fs.writeFileSync(path.join(install, 'ship', 'SKILL.md'), 'brain-aware rendered ship\n');
fs.writeFileSync(path.join(install, 'ship', 'sections', 'tests.md'), 'brain-aware section\n');
fs.writeFileSync(path.join(install, 'README.md'), 'user edit\n');
fs.writeFileSync(path.join(install, 'notes.txt'), 'untracked\n');
const r1 = runMigration(install);
expect(r1.status).toBe(0);
expect(r1.stdout).toContain('restored 2 tracked file(s)');
expect(fs.readFileSync(path.join(install, 'ship', 'SKILL.md'), 'utf-8')).toBe('canonical ship\n');
expect(fs.readFileSync(path.join(install, 'ship', 'sections', 'tests.md'), 'utf-8')).toBe('canonical section\n');
// The user's own edits are NOT the render footprint — untouched, reported.
expect(fs.readFileSync(path.join(install, 'README.md'), 'utf-8')).toBe('user edit\n');
expect(fs.existsSync(path.join(install, 'notes.txt'))).toBe(true);
expect(r1.stdout).toContain('left');
// Idempotent: nothing left in the footprint on the second run.
const r2 = runMigration(install);
expect(r2.status).toBe(0);
expect(r2.stdout).not.toContain('restored');
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
});
test('clean checkout, missing dir, and symlinked install are all silent no-ops', () => {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-migration-noop-'));
try {
const install = makeLegacyInstall(tmp);
const clean = runMigration(install);
expect(clean.status).toBe(0);
expect(clean.stdout.trim()).toBe('');
const missing = runMigration(path.join(tmp, 'does-not-exist'));
expect(missing.status).toBe(0);
const link = path.join(tmp, 'symlinked-install');
fs.symlinkSync(install, link);
const sym = runMigration(link);
expect(sym.status).toBe(0);
expect(sym.stdout.trim()).toBe('');
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
});
});