fix(sync): skip a dsh release whose dependency closure is unpublished

Nightly sync selected 0.1.5-rc.3, then failed because dsh-web-app requires a sidebar package version that npm never published. Stay on the pinned release until that closure resolves.

Author: Blackman99

.changeset/dsh-sync-skip-broken.md

@@ -0,0 +1,6 @@
+---
+'codsh-cli': patch
+'codsh-bundle': patch
+---
+
+`pnpm run sync:dsh` stays on the newest `@deepseek-ai/dsh` release whose dependency closure is fully published, so a harness release that names a missing package no longer fails the nightly sync.

CONTRIBUTING.md

@@ -48,7 +48,7 @@ what the surface emitted and what the terminal did with it, and the emitted
 half is gone by the time anyone looks; replaying the file through a terminal
 emulator reproduces the screen it drew. Off unless the variable is set.
 
-`pnpm run sync:dsh` tracks published `@deepseek-ai/dsh-*` releases. This repo never forks the harness.
+`pnpm run sync:dsh` tracks published `@deepseek-ai/dsh-*` releases and skips a release whose `@deepseek-ai/*` dependency closure is not fully published. This repo never forks the harness.
 
 `pnpm run build` also bundles the React Flow Web panorama from `ship-web-app.tsx`
 with `scripts/build-ship-web.mjs`. Its JavaScript and CSS are published under

scripts/dsh-release-policy.mjs

@@ -1,20 +1,36 @@
-import { compare, maxSatisfying, valid, validRange } from 'semver'
+import { compare, maxSatisfying, minVersion, valid, validRange } from 'semver'
 
 /** Compare two valid SemVer release strings. */
 export const compareVersions = compare
 
+/**
+ * npm abbreviated metadata for one package.
+ * @typedef {object} RegistryMetadata
+ * @property {Record<string, { dependencies?: Record<string, string> }>} versions
+ * @property {Record<string, string>} dist-tags
+ */
+
 /**
  * Pick the harness target from registry metadata.
  *
  * The promoted `latest` tag is an explicit opt-in to a new release line. An
  * untagged version is eligible only when a lockfile-free install of the current
  * range could resolve it; this keeps catching same-core RC drift without
  * silently opting into an unrelated alpha line.
- * @param {{ versions: Record<string, unknown>, 'dist-tags': Record<string, string> }} metadata - npm registry metadata.
+ *
+ * A newer candidate is installable only when every required `@deepseek-ai/*`
+ * range in its dependency closure has a published version. The harness has
+ * shipped a meta-package whose dependency was never published; selecting that
+ * version makes the sync install fail before CI can open a PR. A broken newer
+ * release leaves the manifest's current version in place: ranges such as
+ * `^0.1.5-rc.2` can float onto that broken release, while the committed
+ * lockfile still installs.
+ * @param {RegistryMetadata} metadata - npm registry metadata for `@deepseek-ai/dsh`.
  * @param {string} currentRange - current @deepseek-ai/dsh manifest range.
- * @returns {string} selected harness version.
+ * @param {(name: string) => Promise<RegistryMetadata>} [loadMetadata] - registry lookup used while walking the closure. Required when a candidate might pull in packages other than `@deepseek-ai/dsh`.
+ * @returns {Promise<string>} selected harness version.
  */
-export function selectDshTarget(metadata, currentRange) {
+export async function selectDshTarget(metadata, currentRange, loadMetadata) {
   const range = validRange(currentRange)
   if (range === null) throw new Error(`invalid @deepseek-ai/dsh range: ${currentRange}`)
 
@@ -26,5 +42,57 @@ export function selectDshTarget(metadata, currentRange) {
   }
 
   const installable = maxSatisfying(versions, range)
-  return installable !== null && compare(latest, installable) < 0 ? installable : latest
+  const candidate = installable !== null && compare(latest, installable) < 0 ? installable : latest
+  if (await closureResolves(metadata, candidate, loadMetadata)) return candidate
+
+  const pinned = minVersion(range)?.version
+  if (pinned && versions.includes(pinned) && compare(pinned, candidate) < 0) return pinned
+  throw new Error(`no installable @deepseek-ai/dsh release at or below ${candidate}`)
+}
+
+/**
+ * @param {RegistryMetadata} rootMetadata
+ * @param {string} version
+ * @param {(name: string) => Promise<RegistryMetadata>} [loadMetadata]
+ */
+async function closureResolves(rootMetadata, version, loadMetadata) {
+  /** @type {Map<string, RegistryMetadata>} */
+  const cache = new Map([['@deepseek-ai/dsh', rootMetadata]])
+  /** @type {Set<string>} */
+  const seen = new Set()
+  /** @type {Array<[string, string]>} */
+  const pending = [['@deepseek-ai/dsh', version]]
+
+  while (pending.length > 0) {
+    const [name, wanted] = pending.pop()
+    const key = `${name}@${wanted}`
+    if (seen.has(key)) continue
+    seen.add(key)
+
+    const metadata = cache.get(name) ?? await load(name, loadMetadata)
+    cache.set(name, metadata)
+    const published = Object.keys(metadata.versions)
+    const resolved = maxSatisfying(published, wanted)
+    if (resolved === null) return false
+
+    const manifest = metadata.versions[resolved]
+    for (const [dependency, dependencyRange] of Object.entries(manifest.dependencies ?? {})) {
+      if (!dependency.startsWith('@deepseek-ai/')) continue
+      if (validRange(dependencyRange) === null) return false
+      pending.push([dependency, dependencyRange])
+    }
+  }
+  return true
+}
+
+/**
+ * @param {string} name
+ * @param {(name: string) => Promise<RegistryMetadata>} [loadMetadata]
+ * @returns {Promise<RegistryMetadata>}
+ */
+function load(name, loadMetadata) {
+  if (loadMetadata === undefined) {
+    throw new Error(`registry lookup required to resolve ${name}`)
+  }
+  return loadMetadata(name)
 }

scripts/dsh-release-policy.spec.mjs

@@ -1,48 +1,112 @@
 import { describe, expect, it } from 'vitest'
 import { selectDshTarget } from './dsh-release-policy.mjs'
 
-const metadata = (versions, latest) => ({
-  versions: Object.fromEntries(versions.map(version => [version, {}])),
+const metadata = (versions, latest, dependencies = {}) => ({
+  versions: Object.fromEntries(versions.map(version => [version, {
+    dependencies: dependencies[version] ?? {},
+  }])),
   'dist-tags': { latest },
 })
 
+const registryOf = (entries) => async (name) => {
+  const found = entries[name]
+  if (found === undefined) throw new Error(`unexpected registry lookup: ${name}`)
+  return found
+}
+
 describe('selectDshTarget', () => {
-  it('ignores an unpromoted prerelease from the next release line', () => {
+  it('ignores an unpromoted prerelease from the next release line', async () => {
     const registry = metadata(['0.1.1-rc.2', '0.1.2-alpha.2'], '0.1.1-rc.2')
 
-    expect(selectDshTarget(registry, '^0.1.1-rc.2')).toBe('0.1.1-rc.2')
+    await expect(selectDshTarget(registry, '^0.1.1-rc.2')).resolves.toBe('0.1.1-rc.2')
   })
 
-  it('keeps tracking an untagged prerelease on the current core version', () => {
+  it('keeps tracking an untagged prerelease on the current core version', async () => {
     const registry = metadata(['0.1.0-rc.7', '0.1.0-rc.8'], '0.1.0-rc.7')
 
-    expect(selectDshTarget(registry, '^0.1.0-rc.7')).toBe('0.1.0-rc.8')
+    await expect(selectDshTarget(registry, '^0.1.0-rc.7')).resolves.toBe('0.1.0-rc.8')
   })
 
-  it('follows latest when it explicitly promotes a new release line', () => {
+  it('follows latest when it explicitly promotes a new release line', async () => {
     const registry = metadata(
       ['0.1.1-rc.2', '0.1.2-alpha.2', '0.2.0', '0.3.0-alpha.1'],
       '0.2.0',
     )
 
-    expect(selectDshTarget(registry, '^0.1.1-rc.2')).toBe('0.2.0')
+    await expect(selectDshTarget(registry, '^0.1.1-rc.2')).resolves.toBe('0.2.0')
   })
 
-  it('orders numeric prerelease identifiers with SemVer rules', () => {
+  it('orders numeric prerelease identifiers with SemVer rules', async () => {
     const registry = metadata(['0.1.1-alpha.2', '0.1.1-alpha.10'], '0.1.1-alpha.2')
 
-    expect(selectDshTarget(registry, '^0.1.1-alpha.2')).toBe('0.1.1-alpha.10')
+    await expect(selectDshTarget(registry, '^0.1.1-alpha.2')).resolves.toBe('0.1.1-alpha.10')
   })
 
-  it('rejects an invalid current range', () => {
+  it('rejects an invalid current range', async () => {
     const registry = metadata(['0.1.1-rc.2'], '0.1.1-rc.2')
 
-    expect(() => selectDshTarget(registry, 'not-a-range')).toThrow(/range/i)
+    await expect(selectDshTarget(registry, 'not-a-range')).rejects.toThrow(/range/i)
   })
 
-  it('rejects an invalid latest tag', () => {
+  it('rejects an invalid latest tag', async () => {
     const registry = metadata(['0.1.1-rc.2'], 'not-a-version')
 
-    expect(() => selectDshTarget(registry, '^0.1.1-rc.2')).toThrow(/latest/i)
+    await expect(selectDshTarget(registry, '^0.1.1-rc.2')).rejects.toThrow(/latest/i)
+  })
+
+  it('keeps the current pin when a newer candidate names an unpublished package', async () => {
+    const dsh = metadata(
+      ['0.1.5-rc.2', '0.1.5-rc.3'],
+      '0.1.5-rc.2',
+      {
+        '0.1.5-rc.2': { '@deepseek-ai/dsh-web-app': '^0.1.5-rc.2' },
+        '0.1.5-rc.3': { '@deepseek-ai/dsh-web-app': '^0.1.5-rc.3' },
+      },
+    )
+    const webApp = metadata(
+      ['0.1.5-rc.2', '0.1.5-rc.3'],
+      '0.1.5-rc.2',
+      {
+        '0.1.5-rc.2': { '@deepseek-ai/dsh-client-ui-sidebar-documentpreview': '^0.1.5-rc.2' },
+        '0.1.5-rc.3': { '@deepseek-ai/dsh-client-ui-sidebar-documentpreview': '^0.1.5-rc.3' },
+      },
+    )
+    const preview = metadata(['0.1.5-rc.2'], '0.1.5-rc.2')
+    const loadMetadata = registryOf({
+      '@deepseek-ai/dsh-web-app': webApp,
+      '@deepseek-ai/dsh-client-ui-sidebar-documentpreview': preview,
+    })
+
+    await expect(selectDshTarget(dsh, '^0.1.5-rc.2', loadMetadata)).resolves.toBe('0.1.5-rc.2')
+  })
+
+  it('accepts a candidate once every required dependency version is published', async () => {
+    const dsh = metadata(
+      ['0.1.5-rc.2', '0.1.5-rc.3'],
+      '0.1.5-rc.2',
+      { '0.1.5-rc.3': { '@deepseek-ai/dsh-web-app': '^0.1.5-rc.3' } },
+    )
+    const webApp = metadata(
+      ['0.1.5-rc.3'],
+      '0.1.5-rc.3',
+      { '0.1.5-rc.3': { 'js-yaml': '^4.2.0' } },
+    )
+
+    await expect(selectDshTarget(dsh, '^0.1.5-rc.2', registryOf({
+      '@deepseek-ai/dsh-web-app': webApp,
+    }))).resolves.toBe('0.1.5-rc.3')
+  })
+
+  it('fails when the only published release has an unresolvable dependency closure', async () => {
+    const dsh = metadata(
+      ['0.1.5-rc.3'],
+      '0.1.5-rc.3',
+      { '0.1.5-rc.3': { '@deepseek-ai/dsh-web-app': '^0.1.5-rc.3' } },
+    )
+    const webApp = metadata(['0.1.5-rc.2'], '0.1.5-rc.2')
+
+    await expect(selectDshTarget(dsh, '^0.1.5-rc.3', registryOf({
+      '@deepseek-ai/dsh-web-app': webApp,
+    }))).rejects.toThrow(/no installable/)
   })
 })

scripts/sync-dsh.mjs

@@ -96,7 +96,7 @@ if (dshRange === undefined) throw new Error('no @deepseek-ai/dsh range found in
 // also track the highest version a lockfile-free install would resolve: the
 // harness has published same-core RCs without moving its tags. An unrelated
 // alpha tag is neither signal and must not silently move codsh onto that line.
-const dshLatest = selectDshTarget(dshMeta, dshRange)
+const dshLatest = await selectDshTarget(dshMeta, dshRange, registry)
 if (dshLatest !== dshMeta['dist-tags'].latest) {
   console.log(`note: @deepseek-ai/dsh publishes ${dshLatest}, but its latest tag still reads ${dshMeta['dist-tags'].latest}\n`)
 }