From e8800287d54fc424f5b1fd814167fe7685ccc60f Mon Sep 17 00:00:00 2001 From: Dennis Alexis Valin Dittrich Date: Sat, 5 Sep 2026 10:17:21 +0200 Subject: [PATCH] enhance(#4153): fail closed unresolved update targets (#4237) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * test(#4153): cover unresolved update target * fix(#4153): fail closed unresolved update target * test(#4153): require a concrete recovery installer * fix(#4153): use concrete unresolved recovery command * chore(#4153): bind changeset to fork PR * test(#4153): cover portable update diagnostics * fix(#4153): keep update diagnostics portable * fix(#4153): harden update version diagnostics * test(#4153): reject jq in update version checks * test(#4153): expose step-local parser gap * fix(#4153): keep JSON parsing step-local * docs(#4153): align update target guidance * test(#4153): expose workflow runtime fallback * test(#4153): expose resolver runtime fallback * fix(#4153): leave unknown workflow runtime empty * fix(#4153): stop inferring Claude for unknown targets * test(#4153): preserve Claude workflow targeting * test(#4153): preserve known runtime directory identity * fix(#4153): recognize Claude workflow paths * fix(#4153): reuse known runtime directory identities * chore(#4153): acknowledge emitted workflow growth The fail-closed diagnostic and known-runtime preservation deliberately add 48 emitted bytes. Emitted-Drift-Ack-Growth: update.md — explicit unresolved-target diagnostics and known-runtime preservation * test(#4153): expose missing Windsurf workflow contract * docs(#4153): document Windsurf update targets * chore(#4153): bind changeset to upstream PR * fix(#4153): gate unresolved-target exit before the VERSION-missing fallback The VERSION-missing bullet in get_installed_version sat before the UPDATE_TARGET_UNRESOLVED exit and shared its trigger condition (version 0.0.0). An LLM agent reading the workflow top-to-bottom could satisfy "proceed to install" without ever reaching the fail-closed exit this PR adds, reopening the ill-defined mutating path #4153 closes. Reorder so the unresolved-target gate runs first and scope the VERSION-missing bullet to require an already-resolved target. Also drop two vacuous mutationSpies entries: they checked '--sync'/ '--reapply' (commands/gsd/update.md content) against `step`, a slice of workflows/update.md — always -1 regardless of correctness. Those routes bypass get_installed_version entirely and are already covered by install.test.cjs, reapply-patches.test.cjs, and skill-frontmatter-contract.test.cjs. * chore(#4153): point changeset pr field at fork PR #10 for fork CI * test(#4153): guard RUNTIME_DIRS/update.md table parity, confirm narrowing intent Nit 1: update.md's PREFERRED_RUNTIME prose and RUNTIME_DIRS (src/update-context.cts) are two independently maintained copies of the same runtime->dir mapping with no parity check; add one so a future edit to either surface without the other fails loudly instead of silently drifting. Nit 2: call out in the changeset that a custom --config-dir matching no known runtime, marker file, or env var now resolves unresolved instead of silently defaulting to claude -- this narrowing is intentional, it's the fail-closed behavior #4153 asks for. * fix(#4153): drop dead $UC fallback in check_latest_version's uc_field, cover unresolved-runtime fast path agy (gemini-3.8-flash-high) adversarial review of the full PR: 1. check_latest_version's uc_field() copy-pasted get_installed_version's `${2:-$UC}` fallback, but every call site here passes $2 explicitly and $UC does not exist in this step's scope -- dead, misleading reference. Use $2 directly. 2. No unit test covered resolveUpdateContext's preferredConfigDir fast path returning runtime: '' for a custom --config-dir matching no RUNTIME_DIRS suffix, marker file, or env var (the exact fail-closed case #4153 adds). Added. A third finding (update.md:90 using /gsd:update vs docs using /gsd-update) was investigated and rejected: /gsd:update is the actual registered Claude Code command name (commands/gsd/update.md name: gsd:update) and is locked by this PR's own test (tests/update-workflow.test.cjs); /gsd-update is a separate, pre-existing, intentional prose convention used in audience-facing docs (README/INVENTORY/FEATURES). Not a defect. * chore(#4153): backfill changeset pr field to upstream PR #4237 --------- Co-authored-by: CI Rebase Check Co-authored-by: Test Co-authored-by: Tom Boucher --- .changeset/calm-pandas-greet.md | 5 + docs/how-to/update-gsd.md | 6 ++ gsd-core/workflows/update.md | 77 ++++++++-------- src/update-context.cts | 8 +- tests/update-context.test.cjs | 49 +++++++++- tests/update-workflow.test.cjs | 159 ++++++++++++++++++++++++++++++-- 6 files changed, 252 insertions(+), 52 deletions(-) create mode 100644 .changeset/calm-pandas-greet.md diff --git a/.changeset/calm-pandas-greet.md b/.changeset/calm-pandas-greet.md new file mode 100644 index 000000000..57ff01ff4 --- /dev/null +++ b/.changeset/calm-pandas-greet.md @@ -0,0 +1,5 @@ +--- +type: Changed +pr: 4237 +--- +**`/gsd-update` now stops when it cannot resolve an installed update target** — use the installer explicitly for a fresh install. This includes a custom `--config-dir` whose directory name matches no known runtime and has no runtime marker file or env var (previously silently defaulted to `claude`; now intentionally unresolved). (#4153) diff --git a/docs/how-to/update-gsd.md b/docs/how-to/update-gsd.md index 188fa79be..05fbaf4b1 100644 --- a/docs/how-to/update-gsd.md +++ b/docs/how-to/update-gsd.md @@ -30,6 +30,12 @@ Restart your runtime after the update to pick up new commands and agents. --- +## If the update target cannot be resolved + +`UPDATE_TARGET_UNRESOLVED` means GSD could not identify an installed runtime to update. No update, cache clear, or installer run occurred. Rerun `/gsd-update` from a valid installed runtime, or use the [standard installer](install-on-your-runtime.md#standard-install) for a fresh install. + +--- + ## Flags | Flag | What it does | diff --git a/gsd-core/workflows/update.md b/gsd-core/workflows/update.md index 83b510299..4862267c5 100644 --- a/gsd-core/workflows/update.md +++ b/gsd-core/workflows/update.md @@ -14,7 +14,7 @@ Detect the installed GSD version, scope, runtime, and config dir. First, derive `PREFERRED_CONFIG_DIR` and `PREFERRED_RUNTIME` from the invoking prompt's `execution_context` path — this is the one input only the workflow knows: - If the path contains `/gsd-core/workflows/update.md`, strip that suffix and store the remainder as `PREFERRED_CONFIG_DIR`. -- Infer `PREFERRED_RUNTIME` from the path: `/.codex/` -> `codex`; `/.gemini/antigravity-ide/`, `/.gemini/antigravity-cli/`, `/.gemini/antigravity/`, `/.agents/` or `/.agent/` -> `antigravity` (`.agents` is the canonical local Antigravity install dir (#791); `.agent` is the legacy form (#503); see bin/install.js `getDirName('antigravity')`); `/.config/kilo/` or `/.kilo/` -> `kilo`; `/.config/opencode/` or `/.opencode/` -> `opencode`; otherwise `claude`. +- Infer `PREFERRED_RUNTIME` from the path: `/.claude/` -> `claude`; `/.codex/` -> `codex`; `/.gemini/antigravity-ide/`, `/.gemini/antigravity-cli/`, `/.gemini/antigravity/`, `/.agents/` or `/.agent/` -> `antigravity` (`.agents` is the canonical local Antigravity install dir (#791); `.agent` is the legacy form (#503); see bin/install.js `getDirName('antigravity')`); `/.windsurf/`, `/.devin/` -> `windsurf`; `/.config/kilo/` or `/.kilo/` -> `kilo`; `/.config/opencode/` or `/.opencode/` -> `opencode`; otherwise leave it empty. Then resolve the install context via the deterministic projection (#498). **Do NOT re-derive scope, runtime, or version by hand** — `update-context` owns that cascade in tested code (`gsd-core/bin/lib/update-context.cjs`), the same way `check-latest-version` owns the package name (#2992): @@ -50,17 +50,17 @@ if [ -n "$UC" ]; then # then silently degrades to the fresh-install fallback. The field name is # passed as argv, never interpolated into the script text. uc_field() { - printf '%s' "$UC" | node -e "let d='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const v=JSON.parse(d)[process.argv[1]];process.stdout.write(v==null?'':String(v));}catch{}})" "$1" 2>/dev/null + printf '%s' "${2:-$UC}" | node -e "let d='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const v=JSON.parse(d)[process.argv[1]];process.stdout.write(v==null?'':String(v));}catch{}})" "$1" 2>/dev/null } INSTALLED_VERSION="$(uc_field installedVersion)" INSTALL_SCOPE="$(uc_field scope)" TARGET_RUNTIME="$(uc_field runtime)" GSD_DIR="$(uc_field gsdDir)" else - # No tool resolvable / projection failed -> treat as a fresh install. + # No tool resolvable / projection failed -> no update target is known. INSTALLED_VERSION="0.0.0" INSTALL_SCOPE="UNKNOWN" - TARGET_RUNTIME="claude" + TARGET_RUNTIME="" GSD_DIR="" fi @@ -73,15 +73,26 @@ echo "$GSD_DIR" Parse output: - Line 1 = installed version (`0.0.0` means unknown version) - Line 2 = install scope (`LOCAL`, `GLOBAL`, or `UNKNOWN`) -- Line 3 = target runtime (`claude`, `opencode`, `kilo`, `codex`, `antigravity`) -- Line 4 = resolved GSD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini`); empty if scope is `UNKNOWN`. Capture this as `GSD_DIR` and pass it to subsequent steps so they don't re-derive the runtime path. -- If scope is `UNKNOWN`, proceed to install using the `--claude --global` fallback. +- Line 3 = target runtime (`claude`, `opencode`, `kilo`, `codex`, `antigravity`, `windsurf`); empty when no installed target is resolved +- Line 4 = resolved GSD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini`); empty when no installed target is resolved. Capture this as `GSD_DIR` and pass it to subsequent steps so they don't re-derive the runtime path. `update-context` reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so `CWD=$HOME` does not misdetect as LOCAL), env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in `tests/update-context.test.cjs`. If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install. -**If VERSION file missing (version resolves to `0.0.0`):** report the installed version as Unknown and proceed to install (treated as `0.0.0` for comparison). +**If `INSTALL_SCOPE` is `UNKNOWN`, `TARGET_RUNTIME` is empty, or `GSD_DIR` is empty:** this gate takes precedence over the VERSION-missing case below — a fully-unresolved target also reports version `0.0.0`, and must exit here rather than fall through to "proceed to install". + +```text +UPDATE_TARGET_UNRESOLVED + +GSD could not resolve an installed update target. No update was performed. + +Rerun from a valid installed runtime: `/gsd:update`. For a fresh installation, run `npx -y --package=@opengsd/gsd-core@latest -- gsd-core --global`. +``` + +Exit. + +**Otherwise, if VERSION file missing (version resolves to `0.0.0`) but the target above resolved:** report the installed version as Unknown and proceed to install (treated as `0.0.0` for comparison). @@ -121,34 +132,31 @@ Extract `section_manifest` from `INIT_UPDATE` — gates the `channel-banner` sec Check npm for latest version via the deterministic script. **Do NOT run `npm view` or `npm search` directly** — the package name must come from the script, not from a free choice at execution time. (#2992: LLM-driven prescriptions of npm package names produced wrong-package queries; moving the package name into a script constant closes that gap.) -The `GSD_DIR` value emitted by `get_installed_version` (line 4) resolves to the runtime-specific config dir (`~/.claude/`, `~/.gemini/`, `~/.codex/`, etc.), so the script invocation works for every runtime — not just Claude. If `GSD_DIR` is empty (scope `UNKNOWN`), skip this step and go directly to install. +The `GSD_DIR` value emitted by `get_installed_version` (line 4) resolves to the runtime-specific config dir (`~/.claude/`, `~/.gemini/`, `~/.codex/`, etc.), so the script invocation works for every runtime — not just Claude. An unresolved target exits in `get_installed_version` before this step. -`LATEST_RESULT` is a JSON document with the documented shape `{ ok: bool, version: string, reason: string, detail?: string }`. Parse via `jq` ONLY when the script actually ran. When `GSD_DIR` is empty (scope `UNKNOWN`), skip the check entirely and seed the parsed fields with their no-op values so downstream logic does not mistake an unset `LATEST_RESULT` for a failed network check (#2993 CR feedback): +`LATEST_RESULT` is a JSON document with the documented shape `{ ok: bool, version: string, reason: string, detail?: string }`. Parse it with the Node-only `uc_field` helper. When the script cannot run or returns nothing, preserve its failure as a meaningful diagnostic (#2993 CR feedback): ```bash -if [ -z "$GSD_DIR" ]; then - # No install detected — fall through to install step; version-check is skipped. - LATEST_RESULT="" +uc_field() { + printf '%s' "$2" | node -e "let d='';process.stdin.setEncoding('utf8');process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const v=JSON.parse(d)[process.argv[1]];process.stdout.write(v==null?'':String(v));}catch{}})" "$1" 2>/dev/null +} +if LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json --tag "$TAG" 2>/dev/null)"; then LATEST_STATUS=0 +else + LATEST_STATUS=$? +fi +# #2993 CR: when node is missing or the script doesn't exist, LATEST_RESULT +# is empty. Fail the check with a meaningful reason instead of a blank +# diagnostic. +if [ -n "$LATEST_RESULT" ]; then + LATEST_OK="$(uc_field ok "$LATEST_RESULT")" + LATEST_OK="${LATEST_OK:-false}" + LATEST_VERSION="$(uc_field version "$LATEST_RESULT")" + LATEST_REASON="$(uc_field reason "$LATEST_RESULT")" +else LATEST_OK=false LATEST_VERSION="" - LATEST_REASON="no_install_detected" -else - LATEST_RESULT="$(node "$GSD_DIR/gsd-core/bin/check-latest-version.cjs" --json --tag "$TAG" 2>/dev/null)" - LATEST_STATUS=$? - # #2993 CR: when node is missing or the script doesn't exist, LATEST_RESULT - # is empty and piping it to `jq` produces a parse error on stderr while - # leaving LATEST_OK / LATEST_REASON as empty strings. Fail the check with a - # meaningful reason instead of a blank diagnostic. - if [ -n "$LATEST_RESULT" ]; then - LATEST_OK="$(printf '%s' "$LATEST_RESULT" | jq -r '.ok // false')" - LATEST_VERSION="$(printf '%s' "$LATEST_RESULT" | jq -r '.version // empty')" - LATEST_REASON="$(printf '%s' "$LATEST_RESULT" | jq -r '.reason // empty')" - else - LATEST_OK=false - LATEST_VERSION="" - LATEST_REASON="script_not_found_or_node_unavailable" - fi + LATEST_REASON="script_not_found_or_node_unavailable" fi ``` @@ -305,8 +313,8 @@ detected in `get_installed_version`: ```bash # RUNTIME_DIR is the resolved config directory (e.g. ~/.config/opencode, ~/.gemini). -# get_installed_version emits it as GSD_DIR (LOCAL or GLOBAL install dir, or empty -# when scope is UNKNOWN). Empty RUNTIME_DIR skips the backup below. +# get_installed_version emits it as GSD_DIR for a resolved LOCAL or GLOBAL install. +# The unresolved-target gate exits before this step; the empty guard remains defensive. RUNTIME_DIR="$GSD_DIR" ``` @@ -387,11 +395,6 @@ npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --local npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG" --global ``` -**If UNKNOWN install:** -```bash -npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core --claude --global -``` - Capture output. If install fails, show error and exit. Clear the update cache so statusline indicator disappears: diff --git a/src/update-context.cts b/src/update-context.cts index 4e24dfe57..673f4e4ac 100644 --- a/src/update-context.cts +++ b/src/update-context.cts @@ -89,13 +89,17 @@ export function inferPreferredRuntime({ fs, env, preferredConfigDir }: InferPref if (fs.exists(path.join(preferredConfigDir, 'opencode.json')) || fs.exists(path.join(preferredConfigDir, 'opencode.jsonc'))) return 'opencode'; if (fs.exists(path.join(preferredConfigDir, CODEX_CONFIG_MARKER))) return 'codex'; + const resolved = path.resolve(preferredConfigDir); + const known = RUNTIME_DIRS.find(([, reldir]) => + resolved.endsWith(path.sep + reldir.split('/').join(path.sep))); + if (known) return known[0]; } if (env['CODEX_HOME']) return 'codex'; if (env['ANTIGRAVITY_CONFIG_DIR']) return 'antigravity'; if (env['KILO_CONFIG_DIR'] || env['KILO_CONFIG']) return 'kilo'; if (env['OPENCODE_CONFIG_DIR'] || env['OPENCODE_CONFIG']) return 'opencode'; if (env['CLAUDE_CONFIG_DIR']) return 'claude'; - return 'claude'; + return ''; } export interface EnvRuntimeDirsOpts { @@ -213,7 +217,7 @@ export function resolveUpdateContext({ if (globalRuntime) { return { installedVersion: '0.0.0', scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir }; } - return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: 'claude', gsdDir: '' }; + return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: '', gsdDir: '' }; } export interface LoadUpdateContextOpts { diff --git a/tests/update-context.test.cjs b/tests/update-context.test.cjs index 33d47b75e..55535c8a4 100644 --- a/tests/update-context.test.cjs +++ b/tests/update-context.test.cjs @@ -19,7 +19,7 @@ const { PROBE_TIMEOUT_MS } = require('./helpers/timeouts.cjs'); const ROOT = path.join(__dirname, '..'); const GSD_TOOLS = path.join(ROOT, 'gsd-core', 'bin', 'gsd-tools.cjs'); const { cleanup } = require('./helpers.cjs'); -const { resolveUpdateContext } = require( +const { RUNTIME_DIRS, inferPreferredRuntime, resolveUpdateContext } = require( path.join(ROOT, 'gsd-core', 'bin', 'lib', 'update-context.cjs'), ); @@ -49,6 +49,21 @@ const CWD = '/work/proj'; function ver(dir) { return `${dir}/gsd-core/VERSION`; } function marker(dir) { return `${dir}/gsd-core/workflows/update.md`; } +test('unknown preferred config does not infer Claude', () => { + assert.equal(inferPreferredRuntime({ fs: fakeFs({}), env: {}, preferredConfigDir: '/opt/unknown' }), ''); +}); + +test('known runtime directories infer their table runtime without config markers', () => { + for (const [runtime, relativeDir] of RUNTIME_DIRS) { + const preferredConfigDir = path.resolve(HOME, relativeDir); + assert.equal( + inferPreferredRuntime({ fs: fakeFs({}), env: {}, preferredConfigDir }), + runtime, + preferredConfigDir, + ); + } +}); + describe('resolveUpdateContext: scope cascade', () => { test('GLOBAL claude install under $HOME/.claude', () => { const fs = fakeFs({ [ver(`${HOME}/.claude`)]: '1.40.0\n', [marker(`${HOME}/.claude`)]: 'x' }); @@ -84,9 +99,29 @@ describe('resolveUpdateContext: scope cascade', () => { assert.equal(r.runtime, 'codex'); }); - test('no install anywhere -> UNKNOWN / claude / empty gsdDir', () => { + test('no install anywhere -> UNKNOWN / empty runtime / empty gsdDir', () => { const r = resolveUpdateContext({ home: HOME, cwd: CWD, env: {}, fs: fakeFs({}) }); - assert.deepEqual(r, { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: 'claude', gsdDir: '' }); + assert.deepEqual(r, { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: '', gsdDir: '' }); + assert.deepEqual( + resolveUpdateContext({ home: HOME, cwd: CWD, env: {}, fs: fakeFs({}) }), + r, + 'unresolved resolution must remain deterministic', + ); + }); + + test('multiple installs honor an explicit preferred runtime', () => { + const claude = `${HOME}/.claude`; + const codex = `${HOME}/.codex`; + const fs = fakeFs({ + [ver(claude)]: '1.40.0\n', [marker(claude)]: 'x', + [ver(codex)]: '1.41.0\n', [marker(codex)]: 'x', + }); + const r = resolveUpdateContext({ + home: HOME, cwd: CWD, env: {}, fs, preferredRuntime: 'codex', + }); + assert.equal(r.runtime, 'codex'); + assert.equal(r.scope, 'GLOBAL'); + assert.ok(sameDir(r.gsdDir, codex), `gsdDir was ${r.gsdDir}`); }); }); @@ -120,6 +155,14 @@ describe('resolveUpdateContext: runtime probing + env overrides', () => { assert.ok(sameDir(r.gsdDir, custom), `gsdDir was ${r.gsdDir}`); assert.equal(r.installedVersion, '1.41.0'); }); + + test('preferredConfigDir fast-path: unknown dir with no preferredRuntime resolves runtime empty (#4153)', () => { + const custom = '/opt/custom-gsd'; + const fs = fakeFs({ [ver(custom)]: '1.0.0\n', [marker(custom)]: 'x' }); + const r = resolveUpdateContext({ home: HOME, cwd: CWD, env: {}, fs, preferredConfigDir: custom }); + assert.equal(r.scope, 'GLOBAL'); + assert.equal(r.runtime, '', 'a dir matching no RUNTIME_DIRS suffix, marker, or env must fail closed, not default to claude'); + }); }); describe('gsd-tools update-context (CLI): emits the JSON contract', () => { diff --git a/tests/update-workflow.test.cjs b/tests/update-workflow.test.cjs index 1149fc194..2bc79f5ae 100644 --- a/tests/update-workflow.test.cjs +++ b/tests/update-workflow.test.cjs @@ -30,6 +30,7 @@ const { describe, test } = require('node:test'); const assert = require('node:assert/strict'); const fs = require('node:fs'); const path = require('node:path'); +const { extractFencedBlock } = require('../gsd-core/bin/lib/markdown-sectionizer.cjs'); const UPDATE_MD = path.join(__dirname, '..', 'gsd-core', 'workflows', 'update.md'); @@ -39,6 +40,92 @@ function codeOnly(file) { return fs.readFileSync(file, 'utf8'); } +describe('#4153 regression: unresolved update targets stop before later workflow steps', () => { + const src = codeOnly(UPDATE_MD); + const start = src.indexOf(''); + const end = src.indexOf('', start); + + test('the unresolved path is explicit, ordered, and contains no mutation', () => { + assert.ok(start >= 0, 'get_installed_version step must exist'); + assert.ok(end > start, 'get_installed_version step must close'); + const step = src.slice(start, end); + const unresolved = step.indexOf('UPDATE_TARGET_UNRESOLVED'); + const exit = step.indexOf('Exit.', unresolved); + + assert.ok(unresolved >= 0, 'unresolved target must have a typed result'); + assert.match(step, /TARGET_RUNTIME=""/); + assert.match(step, /GSD_DIR=""/); + assert.match( + step, + /otherwise leave (?:it )?empty/, + 'an unrecognized execution_context path must not infer Claude', + ); + assert.match(step, /`\/\.claude\/` -> `claude`/); + assert.match(step, /`\/\.windsurf\/`, `\/\.devin\/` -> `windsurf`/); + assert.doesNotMatch(step, /otherwise `?claude`?\./); + assert.match(step, /INSTALL_SCOPE` is `UNKNOWN`, `TARGET_RUNTIME` is empty, or `GSD_DIR` is empty/); + assert.match(step, /rerun from a valid installed runtime/i); + assert.match(step, /Rerun from a valid installed runtime: `\/gsd:update`\./); + assert.match(step, /npx -y --package=@opengsd\/gsd-core@latest -- gsd-core --global/); + assert.match(step, /target runtime \(`claude`, `opencode`, `kilo`, `codex`, `antigravity`, `windsurf`\)/); + assert.ok(exit > unresolved, 'unresolved target must exit before the next step'); + + const versionMissing = step.indexOf('VERSION file missing'); + assert.ok(versionMissing >= 0, 'VERSION-missing bullet must exist'); + assert.ok( + unresolved < versionMissing, + 'unresolved-target gate must precede the VERSION-missing bullet, or the ' + + 'fully-unresolved case (version 0.0.0 AND unresolved target) can fall ' + + 'through to "proceed to install" instead of exiting', + ); + assert.match( + step, + /Otherwise, if VERSION file missing.*but the target above resolved/, + 'VERSION-missing bullet must be explicitly scoped to exclude the unresolved-target case', + ); + + const mutationSpies = [ + { name: 'version check', text: src, needle: 'check-latest-version.cjs', after: end }, + { name: 'custom-file detection', text: src, needle: 'detect-custom-files --config-dir', after: end }, + { name: 'resolved installer', text: src, needle: 'npx -y --package=@opengsd/gsd-core@"$TAG" -- gsd-core "$RUNTIME_FLAG"', after: end }, + { name: 'update-cache removal', text: src, needle: 'rm -f "$HOME/.cache/gsd/gsd-update-check"', after: end }, + { name: 'restore apply', text: src, needle: 'restore-custom-files --config-dir "$GSD_DIR" --apply', after: end }, + { name: 'patch check', text: src, needle: 'check_local_patches', after: end }, + ]; + for (const { name, text, needle, after } of mutationSpies) { + assert.equal(step.indexOf(needle), -1, `unresolved path reaches ${name}`); + assert.ok(text.indexOf(needle, after) >= after, `${name} must remain after the exit`); + } + }); + + test('latest-result parsing stays Node-only and preserves the false default', () => { + const latestStart = src.indexOf(''); + const latestEnd = src.indexOf('', latestStart); + + assert.ok(latestStart >= 0, 'check_latest_version step must exist'); + assert.ok(latestEnd > latestStart, 'check_latest_version step must close'); + const latest = src.slice(latestStart, latestEnd); + const latestBash = extractFencedBlock(latest, 'bash'); + + assert.ok(latestBash, 'check_latest_version must contain a bash block'); + assert.doesNotMatch(latestBash, /\bjq\b/, 'latest-result parsing must not invoke jq'); + assert.match( + latestBash, + /uc_field\(\)\s*\{/, + 'check_latest_version must define its JSON parser in the same shell block that invokes it', + ); + assert.match( + latest, + /if LATEST_RESULT="\$\(node [^\n]+\)"; then\s+LATEST_STATUS=0\s+else\s+LATEST_STATUS=\$\?\s+fi/, + 'latest-version failure must be captured when errexit is active', + ); + assert.match(latest, /LATEST_OK="\$\(uc_field ok "\$LATEST_RESULT"\)"/); + assert.match(latest, /LATEST_OK="\$\{LATEST_OK:-false\}"/); + assert.match(latest, /LATEST_VERSION="\$\(uc_field version "\$LATEST_RESULT"\)"/); + assert.match(latest, /LATEST_REASON="\$\(uc_field reason "\$LATEST_RESULT"\)"/); + }); +}); + describe('#498 regression: update.md backup uses GSD_DIR, not the removed LOCAL_DIR/GLOBAL_DIR', () => { const src = codeOnly(UPDATE_MD); @@ -108,10 +195,14 @@ test('issue #815: version check threads the tag through check-latest-version.cjs test('issue #815: install uses the selected tag, not a hardcoded @latest', () => { const robust = WF.match(/npx -y --package=@opengsd\/gsd-core@"\$TAG" -- gsd-core/g) || []; - assert.ok(robust.length >= 3, `expected >=3 tag-parameterized npx invocations, found ${robust.length}`); - assert.doesNotMatch(WF, /--package=@opengsd\/gsd-core@latest -- gsd-core/, + const runUpdateStart = WF.indexOf(''); + const runUpdateEnd = WF.indexOf('', runUpdateStart); + assert.ok(runUpdateStart >= 0 && runUpdateEnd > runUpdateStart, 'run_update step must exist'); + const runUpdate = WF.slice(runUpdateStart, runUpdateEnd); + assert.ok(robust.length >= 2, `expected >=2 tag-parameterized npx invocations, found ${robust.length}`); + assert.doesNotMatch(runUpdate, /--package=@opengsd\/gsd-core@latest -- gsd-core/, 'install lines must not hardcode @latest once --next exists'); - assert.doesNotMatch(WF, /--package=@opengsd\/gsd-core@(?:latest|next|beta|canary|rc) -- gsd-core/, + assert.doesNotMatch(runUpdate, /--package=@opengsd\/gsd-core@(?:latest|next|beta|canary|rc) -- gsd-core/, 'install lines must use the $TAG variable, never a hardcoded dist-tag literal'); }); @@ -223,14 +314,62 @@ __t3130('bug #3130: update.md contains no bare npx invocations (cache-stale form ); }); -__t3130('bug #3130: update.md has >=3 robust npx invocations (--package= + -- separator)', () => { - // Three sibling invocations: local, global, and unknown/fallback. - // The tag is now a $TAG variable (latest by default, next under --next/--rc). - const robust = (src3130.match(/npx -y --package=@opengsd\/gsd-core@\S+ -- gsd-core/g) || []); - assert3130.ok( - robust.length >= 3, - `Expected >=3 robust npx invocations in update.md, found ${robust.length}`, +__t3130('bug #3130: update.md has exactly two robust resolved-install invocations', () => { + const start = src3130.indexOf(''); + const end = src3130.indexOf('', start); + assert3130.ok(start >= 0 && end > start, 'run_update step must exist'); + const robust = (src3130.slice(start, end).match(/npx -y --package=@opengsd\/gsd-core@\S+ -- gsd-core/g) || []); + assert3130.strictEqual( + robust.length, + 2, + `Expected two resolved-install npx invocations in update.md, found ${robust.length}`, ); }); }); } + +// ──────────────────────────────────────────────────────────────────────── +// #4153 review nit: update.md's PREFERRED_RUNTIME prose table and +// src/update-context.cts's RUNTIME_DIRS constant are two independently +// maintained representations of the same runtime -> dir mapping. Nothing +// enforced they stay in sync; this parity check does. +// ──────────────────────────────────────────────────────────────────────── +{ + const { test: __t4153parity } = require('node:test'); + const assert4153parity = require('node:assert/strict'); + const path4153parity = require('node:path'); + const fs4153parity = require('node:fs'); + const { RUNTIME_DIRS: RUNTIME_DIRS_4153 } = require( + path4153parity.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'update-context.cjs'), + ); + const { splitLines: splitLines4153parity } = require('../gsd-core/bin/lib/text-lines.cjs'); + + __t4153parity('update.md PREFERRED_RUNTIME table matches RUNTIME_DIRS', () => { + const src = fs4153parity.readFileSync( + path4153parity.join(__dirname, '..', 'gsd-core', 'workflows', 'update.md'), + 'utf8', + ); + const line = splitLines4153parity(src).find((l) => l.includes('Infer `PREFERRED_RUNTIME` from the path')); + assert4153parity.ok(line, 'PREFERRED_RUNTIME inference line must exist'); + + // Each clause: one or more backtick-quoted `/dir/` tokens, `->`, a + // backtick-quoted runtime name. The trailing "otherwise leave it empty" + // clause has no `->` and is intentionally skipped. + const docPairs = new Set(); + for (const clause of line.split(';')) { + const arrow = clause.indexOf('->'); + if (arrow === -1) continue; + const dirs = [...clause.slice(0, arrow).matchAll(/`\/([^`]+)\/`/g)].map((m) => m[1]); + const runtime = clause.slice(arrow + 2).match(/`([a-z]+)`/)?.[1]; + assert4153parity.ok(runtime, `clause must name a runtime: ${clause}`); + for (const dir of dirs) docPairs.add(`${runtime}:${dir}`); + } + + const tablePairs = new Set(RUNTIME_DIRS_4153.map(([runtime, dir]) => `${runtime}:${dir}`)); + assert4153parity.deepEqual( + [...docPairs].sort(), + [...tablePairs].sort(), + 'update.md PREFERRED_RUNTIME prose and RUNTIME_DIRS must list the same runtime -> dir pairs', + ); + }); +}