@astrale-os/cli 1.0.0-beta.23 → 1.0.0-beta.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.23",
+  "version": "1.0.0-beta.25",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -57,6 +57,7 @@
     "jose": "^6.1.3",
     "ora": "^9.0.0",
     "ts-morph": "^25.0.1",
+    "tsconfig-paths": "4.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.4.3"
   },

package/src/ui/__tests__/ui.test.ts

@@ -330,6 +330,97 @@ describe('UI release and runner contracts', () => {
     )
   })
 
+  test('resolves the immutable release commit when the anonymous GitHub API is rate limited', async () => {
+    const seen: string[] = []
+    const fallback = mockFetch(seen)
+    const fetcher = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input)
+      if (url.includes('/git/ref/tags/')) {
+        seen.push(url)
+        return Response.json({ message: 'API rate limit exceeded' }, { status: 403 })
+      }
+      if (url.includes('/releases/tag/')) {
+        seen.push(url)
+        return new Response(
+          `<a data-hovercard-type="commit" href="/astrale-os/ui/commit/${'b'.repeat(40)}">decoy</a>
+           <a href="/astrale-os/ui/tree/v0.3.0-beta.0">repository navigation</a>
+           ${'x'.repeat(35_000)}
+           <a href="/astrale-os/ui/tree/v0.3.0-beta.0">tag</a>
+           <a data-hovercard-type="commit" href="/astrale-os/ui/commit/${commit}">commit</a>`,
+          { headers: { 'content-type': 'text/html' } },
+        )
+      }
+      return fallback(input, init)
+    }) as typeof fetch
+
+    const release = await resolveUiRelease('0.3.0-beta.0', fetcher)
+
+    expect(release.commit).toBe(commit)
+    expect(seen).toContain('https://github.com/astrale-os/ui/releases/tag/v0.3.0-beta.0')
+    expect(seen).toContain(
+      'https://raw.githubusercontent.com/astrale-os/ui/' + commit + '/tooling/compatibility.json',
+    )
+  })
+
+  test('rejects a release page without an exact Astrale UI commit target', async () => {
+    const fetcher = (async (input: string | URL | Request) => {
+      const url = String(input)
+      if (url.includes('/git/ref/tags/')) return new Response('limited', { status: 403 })
+      if (url.includes('/releases/tag/')) return new Response('<main>release unavailable</main>')
+      throw new Error('release snapshot must not be fetched')
+    }) as typeof fetch
+
+    await expect(resolveUiRelease('0.3.0-beta.0', fetcher)).rejects.toMatchObject({
+      code: 'UI_REGISTRY_UNAVAILABLE',
+      message: 'UI ref v0.3.0-beta.0 did not resolve to a commit.',
+    })
+  })
+
+  test('does not replace an authoritative missing tag with release-page HTML', async () => {
+    const seen: string[] = []
+    const fetcher = (async (input: string | URL | Request) => {
+      const url = String(input)
+      seen.push(url)
+      if (url.includes('/git/ref/tags/')) return new Response('missing', { status: 404 })
+      throw new Error('release page must not be fetched')
+    }) as typeof fetch
+
+    await expect(resolveUiRelease('0.3.0-beta.0', fetcher)).rejects.toMatchObject({
+      code: 'UI_REGISTRY_UNAVAILABLE',
+      message: 'UI ref v0.3.0-beta.0 returned HTTP 404.',
+    })
+    expect(seen).toEqual(['https://api.github.com/repos/astrale-os/ui/git/ref/tags/v0.3.0-beta.0'])
+  })
+
+  test('bounds declared and streamed release-page HTML before reading a snapshot', async () => {
+    for (const oversized of [
+      new Response('large', { headers: { 'content-length': '1048577' } }),
+      new Response(
+        new ReadableStream({
+          start(controller) {
+            controller.enqueue(new Uint8Array(1_048_577))
+            controller.close()
+          },
+        }),
+      ),
+    ]) {
+      const seen: string[] = []
+      const fetcher = (async (input: string | URL | Request) => {
+        const url = String(input)
+        seen.push(url)
+        if (url.includes('/git/ref/tags/')) return new Response('limited', { status: 403 })
+        if (url.includes('/releases/tag/')) return oversized
+        throw new Error('release snapshot must not be fetched')
+      }) as typeof fetch
+
+      await expect(resolveUiRelease('0.3.0-beta.0', fetcher)).rejects.toMatchObject({
+        code: 'UI_REGISTRY_UNAVAILABLE',
+        message: 'UI release v0.3.0-beta.0 exceeds the supported response size.',
+      })
+      expect(seen).toHaveLength(2)
+    }
+  })
+
   test('admits a release theme as one canonical consumer-owned CSS target', async () => {
     const release = await resolveUiRelease('0.3.0-beta.0', themeFetch())
     expect(release.registry.items).toEqual([
@@ -1209,6 +1300,201 @@ describe('UI source operations', () => {
     ).rejects.toBeInstanceOf(UiError)
   })
 
+  test('records multi-file component targets resolved through the consumer components alias', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: {
+          paths: { '@/*': ['./src/*'], '@/components/*': ['./app/ui/*'] },
+        },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'src/index.css'),
+      "@import '@astrale-os/ui/theme.css';\n@import '@astrale-os/ui/presets/astrale.css';\n",
+    )
+    const sidebar = path.join(root, 'src/components/astrale/component/sidebar/sidebar.tsx')
+    const hook = path.join(root, 'src/components/astrale/component/sidebar/use-mobile.ts')
+
+    const planned = await addUi(
+      ['component/sidebar'],
+      { project: root, dryRun: true, yes: true },
+      {
+        fetcher: mockFetch([], componentRegistry),
+        runner: async () => ({ code: 0, stdout: 'planned', stderr: '' }),
+      },
+    )
+    expect(planned.sources).toEqual([
+      expect.objectContaining({
+        files: [
+          'src/components/astrale/component/sidebar/sidebar.tsx',
+          'src/components/astrale/component/sidebar/use-mobile.ts',
+        ],
+      }),
+    ])
+
+    await addUi(
+      ['component/sidebar'],
+      { project: root, yes: true },
+      {
+        fetcher: mockFetch([], componentRegistry),
+        runner: async () => {
+          await mkdir(path.dirname(sidebar), { recursive: true })
+          await writeFile(sidebar, 'export const Sidebar = true\n')
+          await writeFile(hook, 'export const useMobile = true\n')
+          return { code: 0, stdout: '', stderr: '' }
+        },
+      },
+    )
+
+    const written = JSON.parse(await readFile(path.join(root, 'astrale-ui.lock.json'), 'utf8'))
+    expect(written.items['component/sidebar'].files).toEqual({
+      'src/components/astrale/component/sidebar/sidebar.tsx': digest(
+        'export const Sidebar = true\n',
+      ),
+      'src/components/astrale/component/sidebar/use-mobile.ts': digest(
+        'export const useMobile = true\n',
+      ),
+    })
+    expect((await doctorUi(root)).healthy).toBe(true)
+  })
+
+  test('resolves a components alias through package imports before tsconfig paths', async () => {
+    const root = await lockedFixture()
+    const manifestPath = path.join(root, 'package.json')
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+    manifest.imports = { '#app/*': './src/app/*' }
+    await writeFile(manifestPath, JSON.stringify(manifest))
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '#app/components' },
+      }),
+    )
+
+    const planned = await addUi(
+      ['pattern/chart/line/basic'],
+      { project: root, dryRun: true, yes: true },
+      {
+        fetcher: mockFetch(),
+        runner: async () => ({ code: 0, stdout: 'planned', stderr: '' }),
+      },
+    )
+
+    expect(planned.sources).toEqual([
+      expect.objectContaining({
+        files: ['src/app/components/astrale/pattern/chart/line-basic.tsx'],
+      }),
+    ])
+  })
+
+  test('rejects an unresolved package-import alias before invoking shadcn', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '#missing/components' },
+      }),
+    )
+    let invoked = false
+
+    await expect(
+      addUi(
+        ['pattern/chart/line/basic'],
+        { project: root, yes: true },
+        {
+          fetcher: mockFetch(),
+          runner: async () => {
+            invoked = true
+            return { code: 0, stdout: '', stderr: '' }
+          },
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(invoked).toBe(false)
+  })
+
+  test('resolves an extended JSONC baseUrl with the pinned shadcn config loader', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await mkdir(path.join(root, 'config'), { recursive: true })
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      '{\n  // shadcn loads this root config.\n  "extends": "./config/base.json",\n}\n',
+    )
+    await writeFile(
+      path.join(root, 'config/base.json'),
+      '{\n  "compilerOptions": {\n    "baseUrl": "..",\n    "paths": { "@/*": ["frontend/src/*"], },\n  },\n}\n',
+    )
+
+    const planned = await addUi(
+      ['pattern/chart/line/basic'],
+      { project: root, dryRun: true, yes: true },
+      {
+        fetcher: mockFetch(),
+        runner: async () => ({ code: 0, stdout: 'planned', stderr: '' }),
+      },
+    )
+
+    expect(planned.sources).toEqual([
+      expect.objectContaining({
+        files: ['frontend/src/components/astrale/pattern/chart/line-basic.tsx'],
+      }),
+    ])
+  })
+
+  test('rejects an alias mapping outside the project before invoking shadcn', async () => {
+    const root = await lockedFixture()
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      JSON.stringify({ compilerOptions: { paths: { '@/*': ['../outside/*'] } } }),
+    )
+    let invoked = false
+
+    await expect(
+      addUi(
+        ['pattern/chart/line/basic'],
+        { project: root, yes: true },
+        {
+          fetcher: mockFetch(),
+          runner: async () => {
+            invoked = true
+            return { code: 0, stdout: '', stderr: '' }
+          },
+        },
+      ),
+    ).rejects.toMatchObject({ code: 'UI_PROJECT_UNSUPPORTED' })
+    expect(invoked).toBe(false)
+  })
+
   test('restores the exact locked UI dependency after shadcn applies its compatible range', async () => {
     const root = await lockedFixture()
     const installed = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
@@ -1335,10 +1621,22 @@ describe('UI source operations', () => {
     expect(invoked).toBe(false)
   })
 
-  test('restores declared files and package state after a partial shadcn failure', async () => {
+  test('restores alias-resolved files and package state after a partial shadcn failure', async () => {
     const root = await lockedFixture()
-    const first = path.join(root, 'components/astrale/pattern/chart/line-basic.tsx')
-    const second = path.join(root, 'components/astrale/pattern/chart/summary.tsx')
+    await writeFile(
+      path.join(root, 'components.json'),
+      JSON.stringify({
+        style: 'base-nova',
+        tailwind: { css: 'src/index.css' },
+        aliases: { components: '@/components' },
+      }),
+    )
+    await writeFile(
+      path.join(root, 'tsconfig.json'),
+      JSON.stringify({ compilerOptions: { paths: { '@/*': ['./src/*'] } } }),
+    )
+    const first = path.join(root, 'src/components/astrale/pattern/chart/line-basic.tsx')
+    const second = path.join(root, 'src/components/astrale/pattern/chart/summary.tsx')
     await mkdir(path.dirname(first), { recursive: true })
     await writeFile(first, 'consumer original\n')
     const twoFileRegistry: UiRegistry = {

package/src/ui/lock.ts

@@ -32,7 +32,7 @@ export function parseUiLock(value: unknown): UiLock {
   }
   for (const [address, item] of Object.entries(lock.items)) {
     if (
-      !/^(?:(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+|theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.test(
+      !/^(?:component\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*|(?:pattern|block)\/[a-z0-9-]+\/[a-z0-9-/]+|theme\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.test(
         address,
       ) ||
       !isRecord(item) ||

package/src/ui/operations.ts

@@ -17,6 +17,7 @@ import {
   assertSupportedUiProject,
   discoverUiProject,
   projectRelative,
+  resolveUiRegistryTarget,
   type UiProject,
 } from './project'
 import {
@@ -724,13 +725,19 @@ export async function addUi(
     return addReleasedTheme(themes[0]!, itemDocuments[0]!, project, options)
   }
   await rejectLocalChanges(project, lock, items, options.overwrite === true)
-  const targets = (
+  const declaredTargets = items.flatMap((item) =>
+    item.files.flatMap((file) => (file.target ? [file.target] : [])),
+  )
+  const resolvedTargets = new Map(
     await Promise.all(
-      items.flatMap((item) =>
-        item.files
-          .filter((file) => file.target)
-          .map((file) => assertSafePlannedTarget(project, file.target!)),
+      declaredTargets.map(
+        async (target) => [target, await resolveUiRegistryTarget(project, target)] as const,
       ),
+    ),
+  )
+  const targets = (
+    await Promise.all(
+      [...resolvedTargets.values()].map((target) => assertSafePlannedTarget(project, target)),
     )
   ).filter((target, index, all) => all.indexOf(target) === index)
   const invocation = shadcnInvocation(project.manager, release.compatibility.shadcn, [
@@ -802,7 +809,9 @@ export async function addUi(
       sources: itemDocuments.map((item) => ({
         address: item.meta.canonicalAddress,
         dependencies: item.dependencies ?? [],
-        files: item.files.map((file) => file.target).filter(Boolean),
+        files: item.files
+          .map((file) => (file.target ? resolvedTargets.get(file.target) : undefined))
+          .filter(Boolean),
       })),
       command: [invocation.file, ...invocation.args],
       output: result.stdout,
@@ -824,7 +833,7 @@ export async function addUi(
       const files: Record<string, string> = {}
       for (const file of item.files) {
         if (!file.target) continue
-        const target = await safeTarget(project, file.target)
+        const target = await safeTarget(project, resolvedTargets.get(file.target)!)
         files[projectRelative(project, target)] = digest(await readFile(target))
       }
       lock.items[item.meta.canonicalAddress] = {

package/src/ui/project.ts

@@ -1,5 +1,6 @@
 import { access, lstat, readFile, realpath } from 'node:fs/promises'
 import path from 'node:path'
+import { loadConfig } from 'tsconfig-paths'
 
 import { UiError, type PackageManager } from './model'
 
@@ -40,6 +41,119 @@ async function readManifest(target: string): Promise<Record<string, unknown>> {
   }
 }
 
+function pathPatternMatch(pattern: string, candidate: string): string | undefined {
+  const wildcard = pattern.indexOf('*')
+  if (wildcard === -1) return pattern === candidate ? '' : undefined
+  const prefix = pattern.slice(0, wildcard)
+  const suffix = pattern.slice(wildcard + 1)
+  if (!candidate.startsWith(prefix) || !candidate.endsWith(suffix)) return undefined
+  return candidate.slice(prefix.length, candidate.length - suffix.length)
+}
+
+function resolvePackageImport(project: UiProject, candidate: string): string | undefined {
+  const imports = project.packageJson.imports
+  if (!imports || typeof imports !== 'object' || Array.isArray(imports)) return undefined
+  const matches = Object.entries(imports as Record<string, unknown>)
+    .flatMap(([pattern, target]) => {
+      const wildcard = pathPatternMatch(pattern, candidate)
+      if (wildcard === undefined || typeof target !== 'string' || !target.startsWith('./'))
+        return []
+      const wildcardIndex = pattern.indexOf('*')
+      return [
+        {
+          exact: wildcardIndex === -1,
+          prefixLength: wildcardIndex === -1 ? pattern.length : wildcardIndex,
+          suffixLength: wildcardIndex === -1 ? 0 : pattern.length - wildcardIndex - 1,
+          target: target.replaceAll('*', wildcard),
+        },
+      ]
+    })
+    .sort(
+      (left, right) =>
+        Number(right.exact) - Number(left.exact) ||
+        right.prefixLength - left.prefixLength ||
+        right.suffixLength - left.suffixLength,
+    )
+  return matches[0] ? path.resolve(project.root, matches[0].target) : undefined
+}
+
+async function resolveAlias(project: UiProject, candidate: string): Promise<string | undefined> {
+  const config = loadConfig(project.root)
+  if (config.resultType === 'failed') return undefined
+  const matches: Array<{
+    exact: boolean
+    prefixLength: number
+    suffixLength: number
+    resolved: string
+  }> = []
+  for (const [pattern, replacements] of Object.entries(config.paths)) {
+    const wildcard = pathPatternMatch(pattern, candidate)
+    if (wildcard === undefined) continue
+    const replacement = replacements?.[0]
+    if (!replacement) continue
+    const wildcardIndex = pattern.indexOf('*')
+    matches.push({
+      exact: wildcardIndex === -1,
+      prefixLength: wildcardIndex === -1 ? pattern.length : wildcardIndex,
+      suffixLength: wildcardIndex === -1 ? 0 : pattern.length - wildcardIndex - 1,
+      resolved: path.resolve(config.absoluteBaseUrl, replacement.replaceAll('*', wildcard)),
+    })
+  }
+  matches.sort(
+    (left, right) =>
+      Number(right.exact) - Number(left.exact) ||
+      right.prefixLength - left.prefixLength ||
+      right.suffixLength - left.suffixLength,
+  )
+  const best = matches[0]
+  if (!best) return undefined
+  const ambiguous = matches.some(
+    (match) =>
+      match.exact === best.exact &&
+      match.prefixLength === best.prefixLength &&
+      match.suffixLength === best.suffixLength &&
+      match.resolved !== best.resolved,
+  )
+  if (ambiguous) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'The components alias resolves to conflicting project paths.',
+      'Keep one authoritative compilerOptions.paths mapping for the components alias.',
+    )
+  }
+  return best.resolved
+}
+
+export async function resolveUiRegistryTarget(
+  project: UiProject,
+  declaredTarget: string,
+): Promise<string> {
+  if (!declaredTarget.startsWith('components/')) return declaredTarget
+  const components = await readFile(project.componentsPath, 'utf8')
+    .then((value) => JSON.parse(value) as { aliases?: { components?: unknown } })
+    .catch(() => undefined)
+  const componentsAlias = components?.aliases?.components
+  if (typeof componentsAlias !== 'string' || componentsAlias.length === 0) return declaredTarget
+  const suffix = declaredTarget.slice('components/'.length)
+  const directAlias = /^(?:\.?\.?\/|src\/|app\/|frontend\/|components\/)/u.test(componentsAlias)
+  const resolved =
+    resolvePackageImport(project, componentsAlias) ??
+    (await resolveAlias(project, componentsAlias)) ??
+    (directAlias ? path.resolve(project.root, componentsAlias) : undefined)
+  if (!resolved) {
+    throw new UiError(
+      'UI_PROJECT_UNSUPPORTED',
+      'components.json alias cannot be resolved through tsconfig.json or jsconfig.json.',
+      'Define a matching compilerOptions.paths entry for ' + componentsAlias + '.',
+    )
+  }
+  const relative = path.relative(project.root, path.join(resolved, suffix))
+  if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new UiError('UI_PROJECT_UNSUPPORTED', 'components.json alias escapes the project.')
+  }
+  return relative.split(path.sep).join('/')
+}
+
 function hasReactTailwind(manifest: Record<string, unknown>): boolean {
   const dependencies = {
     ...(manifest.dependencies as Record<string, string> | undefined),

package/src/ui/release.ts

@@ -2,11 +2,17 @@ import { UiError, type UiCompatibility, type UiRegistry, type UiRelease } from '
 
 const NPM_PACKAGE = 'https://registry.npmjs.org/@astrale-os/ui'
 const GITHUB_API = 'https://api.github.com/repos/astrale-os/ui'
+const GITHUB_WEB = 'https://github.com/astrale-os/ui'
 const RAW = 'https://raw.githubusercontent.com/astrale-os/ui'
 const MAX_DOCUMENT_BYTES = 1_048_576
 const MAX_REGISTRY_DOCUMENTS = 100
 
 type Fetch = typeof fetch
+class HttpStatusError extends Error {
+  constructor(readonly status: number) {
+    super('HTTP ' + status)
+  }
+}
 type RegistrySource = {
   name?: string
   homepage?: string
@@ -23,8 +29,24 @@ async function json<T>(fetcher: Fetch, url: string, label: string): Promise<T> {
       cause,
     })
   }
+  const body = await responseText(response, label)
+  try {
+    return JSON.parse(body) as T
+  } catch (cause) {
+    throw new UiError('UI_REGISTRY_UNAVAILABLE', label + ' returned malformed JSON.', undefined, {
+      cause,
+    })
+  }
+}
+
+async function responseText(response: Response, label: string): Promise<string> {
   if (!response.ok) {
-    throw new UiError('UI_REGISTRY_UNAVAILABLE', label + ' returned HTTP ' + response.status + '.')
+    throw new UiError(
+      'UI_REGISTRY_UNAVAILABLE',
+      label + ' returned HTTP ' + response.status + '.',
+      undefined,
+      { cause: new HttpStatusError(response.status) },
+    )
   }
   const declaredLength = Number(response.headers.get('content-length'))
   if (Number.isFinite(declaredLength) && declaredLength > MAX_DOCUMENT_BYTES) {
@@ -52,13 +74,7 @@ async function json<T>(fetcher: Fetch, url: string, label: string): Promise<T> {
     body.set(chunk, offset)
     offset += chunk.byteLength
   }
-  try {
-    return JSON.parse(new TextDecoder().decode(body)) as T
-  } catch (cause) {
-    throw new UiError('UI_REGISTRY_UNAVAILABLE', label + ' returned malformed JSON.', undefined, {
-      cause,
-    })
-  }
+  return new TextDecoder().decode(body)
 }
 
 export async function resolveUiRelease(
@@ -76,11 +92,19 @@ export async function resolveUiRelease(
     throw new UiError('UI_REGISTRY_UNAVAILABLE', 'Invalid UI beta release version: ' + version)
   }
   const ref = 'v' + version
-  const reference = await json<{
-    object: { type: 'commit' | 'tag'; sha: string; url: string }
-  }>(fetcher, GITHUB_API + '/git/ref/tags/' + encodeURIComponent(ref), 'UI ref ' + ref)
-  const commit =
-    reference.object.type === 'commit'
+  const commit = await resolveReleaseCommit(ref, fetcher)
+  if (!/^[0-9a-f]{40}$/u.test(commit)) {
+    throw new UiError('UI_REGISTRY_UNAVAILABLE', 'UI ref ' + ref + ' did not resolve to a commit.')
+  }
+  return readUiReleaseSnapshot({ version, ref, commit }, fetcher)
+}
+
+async function resolveReleaseCommit(ref: string, fetcher: Fetch): Promise<string> {
+  try {
+    const reference = await json<{
+      object: { type: 'commit' | 'tag'; sha: string; url: string }
+    }>(fetcher, GITHUB_API + '/git/ref/tags/' + encodeURIComponent(ref), 'UI ref ' + ref)
+    return reference.object.type === 'commit'
       ? reference.object.sha
       : (
           await json<{ object: { sha: string } }>(
@@ -89,10 +113,41 @@ export async function resolveUiRelease(
             'annotated UI tag ' + ref,
           )
         ).object.sha
-  if (!/^[0-9a-f]{40}$/u.test(commit)) {
+  } catch (cause) {
+    const status =
+      cause instanceof UiError && cause.cause instanceof HttpStatusError
+        ? cause.cause.status
+        : undefined
+    if (status !== 403 && status !== 429 && !(status !== undefined && status >= 500)) throw cause
+  }
+
+  const label = 'UI release ' + ref
+  let response: Response
+  try {
+    response = await fetcher(GITHUB_WEB + '/releases/tag/' + encodeURIComponent(ref), {
+      headers: { accept: 'text/html' },
+    })
+  } catch (cause) {
+    throw new UiError('UI_REGISTRY_UNAVAILABLE', 'Unable to reach ' + label + '.', undefined, {
+      cause,
+    })
+  }
+  const html = await responseText(response, label)
+  const marker = 'href="/astrale-os/ui/tree/' + ref + '"'
+  const markerOffset = html.lastIndexOf(marker)
+  const releaseHeader = markerOffset < 0 ? '' : html.slice(markerOffset, markerOffset + 8_192)
+  const commits = new Set(
+    [
+      ...releaseHeader.matchAll(
+        /data-hovercard-type=["']commit["'][^>]+href=["']\/astrale-os\/ui\/commit\/([0-9a-f]{40})["']/gu,
+      ),
+    ].map((match) => match[1]),
+  )
+  const commit = commits.size === 1 ? commits.values().next().value : undefined
+  if (!commit) {
     throw new UiError('UI_REGISTRY_UNAVAILABLE', 'UI ref ' + ref + ' did not resolve to a commit.')
   }
-  return readUiReleaseSnapshot({ version, ref, commit }, fetcher)
+  return commit
 }
 
 export async function readUiReleaseSnapshot(