fix(upgrade): resolve stable channel to latest release tag, not a stable branch (#2167)

glennmichael123 · web-flow · commit 368314ebacff · 2026-07-24T18:44:19.000+08:00
`buddy upgrade` (default channel and `--stable`) resolved the stable channel to a git ref named `stable` and fetched `api.github.com/repos/stacksjs/stacks/tarball/stable`. No `stable` branch or tag exists — releases are cut as `vX.Y.Z` tags by release.yml — so every default upgrade 404'd. Only `--from` and `--version` worked. Resolve the stable channel to the latest published `vX.Y.Z` tag instead: - add `resolveLatestStableTag()` (git ls-remote --tags) + a pure `pickLatestStableTag()` semver picker - `resolveUpgradeContext()` takes the resolved tag (stays pure/sync); the async caller resolves it only when the run lands on stable, falling back to the installed version tag when offline - teach `getRemoteSha()` to resolve tags (refs/tags + deref) so the up-to-date short-circuit works for the tag-based stable channel Fixes #2117
diff --git a/storage/framework/core/actions/src/upgrade/framework-utils.ts b/storage/framework/core/actions/src/upgrade/framework-utils.ts
@@ -14,17 +14,20 @@ export interface UpgradeContext {
  * Resolve the target channel and git ref from CLI options and persisted channel.
  * Priority: --version > --canary > --stable > persisted channel
  *
- * Branch model: `main` is the bleeding-edge "dump everything" branch; `stable`
- * is the vetted branch that PRs are merged into from `main` once main is proven.
- * So the `stable` channel tracks the `stable` branch (vetted) and the `canary`
- * channel tracks the `main` branch (bleeding edge). A pinned `--version` still
- * resolves to the matching `vX` tag.
+ * Release model: `main` is the bleeding-edge "dump everything" branch, and each
+ * release is cut as a `vX.Y.Z` git tag (see `.github/workflows/release.yml`,
+ * which triggers on `push: tags: ['v*']`). There is deliberately no long-lived
+ * `stable` branch. So the `canary` channel tracks the `main` branch (bleeding
+ * edge) and the `stable` channel tracks the latest published `vX.Y.Z` tag —
+ * passed in as `latestStableRef` because resolving it needs the network, which
+ * this pure function stays free of. A pinned `--version` resolves directly to
+ * the matching `vX` tag.
  */
 export function resolveUpgradeContext(options: {
   version?: string
   canary?: boolean
   stable?: boolean
-}, currentChannel: 'stable' | 'canary'): UpgradeContext {
+}, currentChannel: 'stable' | 'canary', latestStableRef: string): UpgradeContext {
   const targetVersion = options.version
 
   if (targetVersion) {
@@ -40,8 +43,8 @@ export function resolveUpgradeContext(options: {
   }
 
   if (options.stable) {
-    // stable tracks the vetted `stable` branch.
-    return { channel: 'stable', ref: 'stable' }
+    // stable tracks the latest published release tag.
+    return { channel: 'stable', ref: latestStableRef }
   }
 
   if (currentChannel === 'canary') {
@@ -50,7 +53,67 @@ export function resolveUpgradeContext(options: {
     return { channel: 'canary', ref: 'main' }
   }
 
-  return { channel: 'stable', ref: 'stable' }
+  return { channel: 'stable', ref: latestStableRef }
+}
+
+/** Compare two [major, minor, patch] tuples. Returns >0 if `a` is newer. */
+function compareVersionParts(a: [number, number, number], b: [number, number, number]): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
+}
+
+/**
+ * Pick the highest stable release tag from a list of tag names. Only clean
+ * `vMAJOR.MINOR.PATCH` tags qualify — pre-releases (`v1.0.0-beta.1`), annotated
+ * deref entries (`…^{}`), and non-version tags are ignored. Returns null when
+ * nothing qualifies.
+ */
+export function pickLatestStableTag(tags: string[]): string | null {
+  const re = /^v(\d+)\.(\d+)\.(\d+)$/
+  let best: { tag: string, parts: [number, number, number] } | null = null
+
+  for (const tag of tags) {
+    const m = re.exec(tag.trim())
+    if (!m) continue
+    const parts: [number, number, number] = [Number(m[1]), Number(m[2]), Number(m[3])]
+    if (!best || compareVersionParts(parts, best.parts) > 0)
+      best = { tag: tag.trim(), parts }
+  }
+
+  return best?.tag ?? null
+}
+
+/**
+ * Resolve the latest published stable release tag (e.g. `"v0.70.163"`) by
+ * listing the remote's `v*` tags. The stable channel installs this tag rather
+ * than a branch, because releases are cut as tags and no `stable` branch
+ * exists. Returns null if the tags can't be listed (offline / no git), letting
+ * the caller fall back to the currently-installed version.
+ */
+export async function resolveLatestStableTag(): Promise<string | null> {
+  try {
+    const proc = Bun.spawn({
+      // `--refs` drops the `^{}` dereferenced annotated-tag entries, leaving
+      // clean `refs/tags/vX.Y.Z` lines.
+      cmd: ['git', 'ls-remote', '--tags', '--refs', 'https://github.com/stacksjs/stacks.git', 'v*'],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const out = await new Response(proc.stdout).text()
+    if ((await proc.exited) !== 0)
+      return null
+
+    const tags = out
+      .split('\n')
+      .map(line => line.split('\t')[1]?.replace('refs/tags/', ''))
+      .filter((t): t is string => !!t)
+
+    return pickLatestStableTag(tags)
+  }
+  catch {
+    // git missing / offline — fail soft; the caller falls back to the
+    // installed version tag.
+    return null
+  }
 }
 
 /**
diff --git a/storage/framework/core/actions/src/upgrade/framework.ts b/storage/framework/core/actions/src/upgrade/framework.ts
@@ -20,6 +20,7 @@ import {
   readChannel,
   readSyncedVersion,
   readVersion,
+  resolveLatestStableTag,
   resolveSuccessMessage,
   resolveUpgradeContext,
   resolveUpgradeMessage,
@@ -79,11 +80,25 @@ if (!existsSync(p.projectPath('storage/framework/core'))) {
 const channelFile = join(projectRoot, '.stacks-channel')
 const versionFile = join(projectRoot, '.stacks-version')
 const currentChannel = readChannel(channelFile)
-const ctx = resolveUpgradeContext(options, currentChannel)
 
 const corePkgPath = p.projectPath('storage/framework/core/buddy/package.json')
 const currentVersion = readVersion(corePkgPath)
 
+// The stable channel installs the latest published `vX.Y.Z` tag (there is no
+// `stable` branch — releases are cut as tags). Only resolve it when the run
+// will actually land on stable: a pinned `--version` and the canary channel
+// don't need it, so we skip the network call. If the remote tags can't be
+// listed (offline / no git), fall back to the currently-installed version tag
+// so we never target a non-existent ref.
+const willResolveStable = !options.version && !options.canary && (!!options.stable || currentChannel !== 'canary')
+let latestStableRef = ''
+if (willResolveStable) {
+  latestStableRef = (await resolveLatestStableTag())
+    ?? (currentVersion ? `v${currentVersion}` : 'main')
+}
+
+const ctx = resolveUpgradeContext(options, currentChannel, latestStableRef)
+
 // Source resolution. Explicit `--from` wins. Otherwise auto-detect a sibling
 // stacks checkout for instant offline updates. If neither is available,
 // fall back to gitit (GitHub).
@@ -530,16 +545,31 @@ async function getRemoteSha(context: UpgradeContext, fromLocal: boolean, stacksR
       return (await head.exited) === 0 && SHA_RE.test(h) ? h.toLowerCase() : null
     }
 
-    // GitHub: ls-remote prints "<sha>\trefs/heads/<ref>" lines.
+    // GitHub: ls-remote prints "<sha>\t<ref>" lines. The ref can be a branch
+    // (canary → refs/heads/main) or a tag (stable → refs/tags/vX.Y.Z), so we
+    // ask for both. For an annotated tag, git also emits a `refs/tags/…^{}`
+    // line carrying the dereferenced *commit* sha — prefer it so the short-
+    // circuit compares like-for-like against the synced commit.
     const proc = Bun.spawn({
-      cmd: ['git', 'ls-remote', 'https://github.com/stacksjs/stacks.git', `refs/heads/${context.ref}`],
+      cmd: [
+        'git',
+        'ls-remote',
+        'https://github.com/stacksjs/stacks.git',
+        `refs/heads/${context.ref}`,
+        `refs/tags/${context.ref}`,
+        `refs/tags/${context.ref}^{}`,
+      ],
       stdout: 'pipe',
       stderr: 'pipe',
     })
     const out = await new Response(proc.stdout).text()
     if ((await proc.exited) !== 0)
       return null
-    const m = out.match(/^([0-9a-f]{40})\s/i)
+
+    const lines = out.split('\n').filter(Boolean)
+    const deref = lines.find(l => l.includes('^{}'))
+    const chosen = deref ?? lines[0]
+    const m = chosen?.match(/^([0-9a-f]{40})\s/i)
     return m?.[1] ? m[1].toLowerCase() : null
   }
   catch {
diff --git a/storage/framework/core/actions/tests/upgrade-framework.test.ts b/storage/framework/core/actions/tests/upgrade-framework.test.ts
@@ -5,6 +5,7 @@ import { join } from 'node:path'
 
 const {
   resolveUpgradeContext,
+  pickLatestStableTag,
   buildTemplateString,
   readVersion,
   readChannel,
@@ -36,17 +37,22 @@ afterEach(() => {
 
 // ─── resolveUpgradeContext ───────────────────────────────────────────────────
 
+// The resolved latest stable tag is passed into resolveUpgradeContext (the
+// network lookup lives in the async caller). Tests inject a fixture tag so the
+// pure resolution stays deterministic.
+const STABLE = 'v9.9.9'
+
 describe('resolveUpgradeContext', () => {
   describe('default behavior', () => {
-    it('should default to the stable channel + stable branch when no options and channel is stable', () => {
-      const ctx = resolveUpgradeContext({}, 'stable')
+    it('should default to the stable channel + latest stable tag when no options and channel is stable', () => {
+      const ctx = resolveUpgradeContext({}, 'stable', STABLE)
       expect(ctx.channel).toBe('stable')
-      expect(ctx.ref).toBe('stable')
+      expect(ctx.ref).toBe(STABLE)
       expect(ctx.targetVersion).toBeUndefined()
     })
 
     it('should stay on canary (main branch) if current channel is canary and no flags', () => {
-      const ctx = resolveUpgradeContext({}, 'canary')
+      const ctx = resolveUpgradeContext({}, 'canary', STABLE)
       expect(ctx.channel).toBe('canary')
       expect(ctx.ref).toBe('main')
       expect(ctx.targetVersion).toBeUndefined()
@@ -55,94 +61,126 @@ describe('resolveUpgradeContext', () => {
 
   describe('--canary flag', () => {
     it('should switch to canary (main branch) when --canary is set', () => {
-      const ctx = resolveUpgradeContext({ canary: true }, 'stable')
+      const ctx = resolveUpgradeContext({ canary: true }, 'stable', STABLE)
       expect(ctx.channel).toBe('canary')
       expect(ctx.ref).toBe('main')
     })
 
     it('should stay on canary (main branch) when already on canary and --canary is set', () => {
-      const ctx = resolveUpgradeContext({ canary: true }, 'canary')
+      const ctx = resolveUpgradeContext({ canary: true }, 'canary', STABLE)
       expect(ctx.channel).toBe('canary')
       expect(ctx.ref).toBe('main')
     })
   })
 
   describe('--stable flag', () => {
-    it('should switch to the stable branch when --stable is set from canary', () => {
-      const ctx = resolveUpgradeContext({ stable: true }, 'canary')
+    it('should switch to the latest stable tag when --stable is set from canary', () => {
+      const ctx = resolveUpgradeContext({ stable: true }, 'canary', STABLE)
       expect(ctx.channel).toBe('stable')
-      expect(ctx.ref).toBe('stable')
+      expect(ctx.ref).toBe(STABLE)
     })
 
-    it('should stay on the stable branch when already stable and --stable is set', () => {
-      const ctx = resolveUpgradeContext({ stable: true }, 'stable')
+    it('should stay on the latest stable tag when already stable and --stable is set', () => {
+      const ctx = resolveUpgradeContext({ stable: true }, 'stable', STABLE)
       expect(ctx.channel).toBe('stable')
-      expect(ctx.ref).toBe('stable')
+      expect(ctx.ref).toBe(STABLE)
     })
   })
 
   describe('--version flag', () => {
     it('should use version tag without v prefix', () => {
-      const ctx = resolveUpgradeContext({ version: '0.70.23' }, 'stable')
+      const ctx = resolveUpgradeContext({ version: '0.70.23' }, 'stable', STABLE)
       expect(ctx.channel).toBe('stable')
       expect(ctx.ref).toBe('v0.70.23')
       expect(ctx.targetVersion).toBe('0.70.23')
     })
 
     it('should use version tag with v prefix as-is', () => {
-      const ctx = resolveUpgradeContext({ version: 'v0.70.23' }, 'stable')
+      const ctx = resolveUpgradeContext({ version: 'v0.70.23' }, 'stable', STABLE)
       expect(ctx.channel).toBe('stable')
       expect(ctx.ref).toBe('v0.70.23')
       expect(ctx.targetVersion).toBe('v0.70.23')
     })
 
     it('should take priority over --canary', () => {
-      const ctx = resolveUpgradeContext({ version: '0.70.23', canary: true }, 'stable')
+      const ctx = resolveUpgradeContext({ version: '0.70.23', canary: true }, 'stable', STABLE)
       expect(ctx.channel).toBe('stable')
       expect(ctx.ref).toBe('v0.70.23')
       expect(ctx.targetVersion).toBe('0.70.23')
     })
 
     it('should take priority over --stable', () => {
-      const ctx = resolveUpgradeContext({ version: '0.70.23', stable: true }, 'canary')
+      const ctx = resolveUpgradeContext({ version: '0.70.23', stable: true }, 'canary', STABLE)
       expect(ctx.channel).toBe('stable')
       expect(ctx.ref).toBe('v0.70.23')
     })
 
     it('should take priority over persisted canary channel', () => {
-      const ctx = resolveUpgradeContext({ version: '0.70.23' }, 'canary')
+      const ctx = resolveUpgradeContext({ version: '0.70.23' }, 'canary', STABLE)
       expect(ctx.channel).toBe('stable')
       expect(ctx.ref).toBe('v0.70.23')
     })
 
     it('should handle semver-only strings', () => {
-      const ctx = resolveUpgradeContext({ version: '1.0.0' }, 'stable')
+      const ctx = resolveUpgradeContext({ version: '1.0.0' }, 'stable', STABLE)
       expect(ctx.ref).toBe('v1.0.0')
     })
 
     it('should handle pre-release version strings', () => {
-      const ctx = resolveUpgradeContext({ version: '1.0.0-beta.1' }, 'stable')
+      const ctx = resolveUpgradeContext({ version: '1.0.0-beta.1' }, 'stable', STABLE)
       expect(ctx.ref).toBe('v1.0.0-beta.1')
     })
   })
 
   describe('flag priority', () => {
     it('--version beats --canary beats --stable beats persisted channel', () => {
       // version > canary
-      const v = resolveUpgradeContext({ version: '1.0.0', canary: true, stable: true }, 'canary')
+      const v = resolveUpgradeContext({ version: '1.0.0', canary: true, stable: true }, 'canary', STABLE)
       expect(v.ref).toBe('v1.0.0')
 
       // canary > stable (when no version)
-      const c = resolveUpgradeContext({ canary: true, stable: true }, 'stable')
+      const c = resolveUpgradeContext({ canary: true, stable: true }, 'stable', STABLE)
       expect(c.channel).toBe('canary')
 
       // stable > persisted canary (when no version/canary)
-      const s = resolveUpgradeContext({ stable: true }, 'canary')
+      const s = resolveUpgradeContext({ stable: true }, 'canary', STABLE)
       expect(s.channel).toBe('stable')
+      expect(s.ref).toBe(STABLE)
     })
   })
 })
 
+// ─── pickLatestStableTag ─────────────────────────────────────────────────────
+
+describe('pickLatestStableTag', () => {
+  it('picks the highest vX.Y.Z tag by semver, not lexically', () => {
+    expect(pickLatestStableTag(['v0.70.9', 'v0.70.162', 'v0.70.52', 'v0.9.99'])).toBe('v0.70.162')
+  })
+
+  it('compares major/minor/patch numerically', () => {
+    expect(pickLatestStableTag(['v1.0.0', 'v0.99.99', 'v1.2.0', 'v1.10.0'])).toBe('v1.10.0')
+  })
+
+  it('ignores pre-releases, deref entries, and non-version tags', () => {
+    expect(pickLatestStableTag([
+      'v0.70.163-beta.1',
+      'v0.70.163^{}',
+      'latest',
+      'browser-extension-v2.0.0',
+      'v0.70.162',
+    ])).toBe('v0.70.162')
+  })
+
+  it('trims whitespace around tags', () => {
+    expect(pickLatestStableTag(['  v0.70.10  ', 'v0.70.2'])).toBe('v0.70.10')
+  })
+
+  it('returns null when no clean version tag qualifies', () => {
+    expect(pickLatestStableTag(['latest', 'v1.0.0-rc.1', ''])).toBeNull()
+    expect(pickLatestStableTag([])).toBeNull()
+  })
+})
+
 describe('local framework source selection', () => {
   it('does not auto-detect a checkout for an exact version pin', () => {
     expect(shouldAutoDetectLocalStacks({ version: '0.70.104' })).toBe(false)
