Files

Dennis Alexis Valin Dittrich e8800287d5 enhance(#4153 ): fail closed unresolved update targets (#4237 )

* 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 <ci@gsd-redux>
Co-authored-by: Test <test@test.com>
Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

2026-09-05 04:17:21 -04:00

7.9 KiB

Raw Blame History

How to update GSD Core

Update an existing GSD Core install to the latest release, preview the changelog before committing, and recover any local customisations that the update would overwrite.

What you need: The same runtime GSD is installed for. The update command re-runs the installer under the hood, so it needs Node.js and npx available (same requirement as the original install).

The standard update path

From inside your AI runtime, run:

/gsd-update

GSD will:

Detect the installed version and install scope (global or local).
Check npm for the latest release of @opengsd/gsd-core.
Fetch the changelog and show you what changed between your installed version and the latest.
Ask for confirmation before touching anything.
Back up any user-added files found inside GSD-managed directories to gsd-user-files-backup/.
Run the installer (npx @opengsd/gsd-core@latest --<runtime> --<scope>).
Clear the update-check cache so the statusline indicator resets.
Offer to restore the user-added files it backed up in step 5.
Report whether locally modified GSD files were backed up to gsd-local-patches/.

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 for a fresh install.

Flags

Flag	What it does
`--sync`	After updating, sync skills from the GSD registry
`--reapply`	After updating, merge locally modified GSD files back in from `gsd-local-patches/`
`--next` / `--rc`	Target the `@next` RC dist-tag instead of `@latest` (installs or refreshes a release candidate; see ADR #660)

/gsd-update --sync        # Update and sync skills
/gsd-update --reapply     # Update and reapply local patches
/gsd-update --next        # Install from the @next RC dist-tag

Install or refresh a release candidate

GSD publishes release candidates on the @next npm dist-tag (established by ADR #660). To install or refresh from that channel:

/gsd-update --next
# or equivalently:
/gsd-update --rc

The full update flow applies — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all run normally. The only difference is that check-latest-version.cjs resolves the @next tag and npx installs from @opengsd/gsd-core@next.

Only latest and next are supported channels; no arbitrary dist-tag can be passed (the script enforces an allowlist and exits with code 2 on an invalid tag).

Omitting --next/--rc keeps targeting @latest (stable channel, no change in behavior).

Reviewing the changelog before updating

/gsd-update always shows the changelog diff between your installed version and the latest before it asks for confirmation. You do not need to visit GitHub separately. The output looks like:

## GSD Update Available

Installed: 1.39.0
Latest:    1.41.0

### What's New

---

[changelog entries for 1.40.0 and 1.41.0]

---

Proceed with update? [Yes, update now / No, cancel]

If the changelog cannot be fetched (no network access, npm outage), the update still proceeds after confirmation — it does not block on changelog availability.

Recovering local customisations

Files you added inside GSD-managed directories

If you placed custom files inside directories that GSD owns (for example, custom agents prefixed with gsd- or extra files in commands/gsd/), the installer detects them and copies them to gsd-user-files-backup/ before wiping those directories.

After the new version is installed, the update offers to put them back. You get a list of what was backed up, then a choice:

Restore them now — each file is copied back to its original location and the update reports what it restored.
Leave them in the backup — nothing is copied; the backup stays exactly where it is.

Either way the backup is never deleted, so declining is not destructive and you can restore later.

Before copying anything back, the restore runs a compatibility pass against the version that was just installed and attaches a warning to any file that looks like it may no longer work — one that references a workflow or /gsd: command the new release retired, or a skill missing its name / description frontmatter. Warnings are advisory: the file is still restored, with the warning shown next to it, so you can decide whether to fix it.

Two cases are skipped rather than restored, because restoring would destroy something:

The new release now ships a file at that exact path (your custom file would overwrite GSD's).
A different file is already sitting at that path (restoring would overwrite your current version).

Both stay in the backup and are reported with the reason.

To restore later — or after an update where you declined — run the same operation directly:

node <config-dir>/gsd-core/bin/gsd-tools.cjs restore-custom-files --config-dir <config-dir> --apply

Drop --apply to preview what would be restored without writing anything.

Files you placed outside GSD-managed directories — custom agents not prefixed with gsd-, custom commands outside commands/gsd/, your CLAUDE.md files, and custom hooks — are never touched by the installer.

GSD files you modified directly

If you edited a file that GSD installed (for example, tweaking an agent's system prompt), the installer detects the modification via a hash comparison against its manifest, backs the file up to gsd-local-patches/, and then replaces it with the new version. After the update:

/gsd-update --reapply

This merges your modifications from gsd-local-patches/ back into the newly installed files.

If you skipped --reapply after a previous update and want to apply patches now:

/gsd-update --reapply

It is safe to run --reapply on its own without triggering a new download — if you are already on the latest version, GSD skips the install step and goes straight to reapplying patches.

When npm is unavailable

If npx @opengsd/gsd-core@latest fails due to an npm outage, network restrictions, or because you are working from the source repository, use the manual update procedure in docs/manual-update.md. That document covers pulling the latest commit, building the hooks dist, and running node bin/install.js directly.

If you are already on the latest version

/gsd-update exits early with a confirmation message — no download, no install, no restart needed.

Installer migrations

Each GSD release may include installer migrations that rename, move, or retire managed files. The migration layer runs automatically before the new package payload is written. Migrations that would affect files you have modified prompt for confirmation rather than acting silently. For the full design and runtime-configuration contract registry, see docs/installer-migrations.md.

CLI version-skew warning

GSD warns (to stderr, non-blocking) when the resolved gsd-tools.cjs is outside your project root while a project-local install exists — a sign that a global install (often a retired @gsd-build/sdk canary) is shadowing your project-local GSD. The warning names the resolved path and, for the @gsd-build/sdk case, gives the removal command:

npm uninstall -g @gsd-build/sdk

If you see this warning, remove the stale global package so gsd_run resolves the project-local install.

7.9 KiB Raw Blame History