oneworks 0.1.0-alpha.2 → 0.1.0-beta.1

package/__tests__/cli.spec.ts

@@ -69,6 +69,23 @@ describe('bootstrap cli', () => {
     })
   })
 
+  it('routes runtime package cache versions from flags', () => {
+    expect(routeBootstrapCommand('runtime', [
+      'install',
+      'server',
+      '--version=2.3.4',
+      '--cache-version',
+      'dev-local'
+    ])).toEqual({
+      action: 'install',
+      cacheVersion: 'dev-local',
+      json: false,
+      kind: 'runtime-package',
+      target: 'server',
+      version: '2.3.4'
+    })
+  })
+
   it('routes unknown commands through the CLI package', () => {
     expect(routeBootstrapCommand('hello', [])).toEqual({
       commandName: 'oneworks',
@@ -197,6 +214,46 @@ describe('bootstrap cli', () => {
     expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('"requestedVersion":"1.2.3"'))
   })
 
+  it('dispatches runtime package installation with a cache version', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+    const installRuntimePackage = vi.fn(async () => ({
+      cacheVersion: 'dev-local',
+      installed: true,
+      installedVersion: '1.2.3',
+      latestInstalled: true,
+      latestVersion: '1.2.3',
+      packageName: '@oneworks/server',
+      requestedVersion: '1.2.3',
+      target: 'server' as const,
+      updateAvailable: false
+    }))
+    const cli = createBootstrapCli({
+      checkRuntimePackage: vi.fn(async () => {
+        throw new Error('unexpected check')
+      }),
+      installRuntimePackage,
+      launchDesktopApp: vi.fn(async () => {}),
+      launchInstalledPackage: vi.fn(async () => 0)
+    })
+
+    await cli.parseAsync([
+      'node',
+      'oneworks',
+      'runtime',
+      'install',
+      'server',
+      '--version=1.2.3',
+      '--cache-version=dev-local',
+      '--json'
+    ])
+
+    expect(installRuntimePackage).toHaveBeenCalledWith('server', {
+      cacheVersion: 'dev-local',
+      version: '1.2.3'
+    })
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('"cacheVersion":"dev-local"'))
+  })
+
   it('forwards --help after a routed command', async () => {
     const launchDesktopApp = vi.fn(async () => {})
     const launchInstalledPackage = vi.fn(async () => 0)

package/__tests__/npm-package.spec.ts

@@ -20,6 +20,8 @@ describe('bootstrap npm package env', () => {
     vi.stubEnv('ONEWORKS_BOOTSTRAP_DISABLE_BACKGROUND_REFRESH', '1')
     vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_CACHE_FIRST', undefined)
     vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_LOOKUP_TIMEOUT_MS', '1000')
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_TAG', undefined)
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_VERSION', undefined)
     vi.stubEnv('NPM_CONFIG_USERCONFIG', undefined)
     vi.stubEnv('npm_config_userconfig', undefined)
   })
@@ -40,8 +42,25 @@ describe('bootstrap npm package env', () => {
       `#!/usr/bin/env node
 const delay = Number.parseInt(process.env.ONEWORKS_TEST_NPM_VIEW_DELAY_MS || '0', 10)
 const version = process.env.ONEWORKS_TEST_NPM_VIEW_VERSION || '1.0.0'
+const exactVersions = JSON.parse(process.env.ONEWORKS_TEST_NPM_VIEW_EXACT_VERSIONS || '{}')
+const versions = JSON.parse(process.env.ONEWORKS_TEST_NPM_VIEW_VERSIONS || '[]')
 if (process.argv[2] === 'view') {
+  const spec = process.argv[3]
+  const field = process.argv[4]
   setTimeout(() => {
+    if (field === 'versions') {
+      process.stdout.write(JSON.stringify(versions.length > 0 ? versions : [version]) + '\\n')
+      return
+    }
+    if (Object.prototype.hasOwnProperty.call(exactVersions, spec)) {
+      process.stdout.write(JSON.stringify(exactVersions[spec]) + '\\n')
+      return
+    }
+    if (process.env.ONEWORKS_TEST_NPM_VIEW_FAIL_EXACT === '1' && /@\\d+\\.\\d+\\.\\d+/.test(spec)) {
+      process.stderr.write('not found\\n')
+      process.exitCode = 1
+      return
+    }
     process.stdout.write(JSON.stringify(version) + '\\n')
   }, delay)
 } else {
@@ -118,6 +137,7 @@ if (process.argv[2] === 'view') {
   })
 
   it('uses installed package cache before npm view when no metadata exists', async () => {
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_TAG', 'latest')
     await writeCachedPackage('@scope/pkg', '4.5.6')
 
     await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('4.5.6')
@@ -139,6 +159,55 @@ if (process.argv[2] === 'view') {
     expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('timed out after 20ms'))
   })
 
+  it('prefers the exact bootstrap prerelease version for runtime package resolution', async () => {
+    await installFakeNpm()
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_CACHE_FIRST', '0')
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_VERSION', '0.1.0-beta.0')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '0.1.0-alpha.0')
+    vi.stubEnv(
+      'ONEWORKS_TEST_NPM_VIEW_EXACT_VERSIONS',
+      JSON.stringify({
+        '@scope/pkg@0.1.0-beta.0': '0.1.0-beta.0'
+      })
+    )
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('0.1.0-beta.0')
+  })
+
+  it('falls back to the highest same-core bootstrap prerelease version', async () => {
+    await installFakeNpm()
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_CACHE_FIRST', '0')
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_VERSION', '0.1.0-beta.0')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_FAIL_EXACT', '1')
+    vi.stubEnv(
+      'ONEWORKS_TEST_NPM_VIEW_VERSIONS',
+      JSON.stringify([
+        '0.1.0-alpha.9',
+        '0.1.0-beta.1',
+        '0.1.0-beta.2',
+        '0.1.0-rc.0',
+        '0.1.0',
+        '0.1.1-beta.0'
+      ])
+    )
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('0.1.0-beta.2')
+  })
+
+  it('does not use an installed alpha cache for bootstrap beta resolution', async () => {
+    await installFakeNpm()
+    await writeCachedPackage('@scope/pkg', '0.1.0-alpha.0')
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_VERSION', '0.1.0-beta.0')
+    vi.stubEnv(
+      'ONEWORKS_TEST_NPM_VIEW_EXACT_VERSIONS',
+      JSON.stringify({
+        '@scope/pkg@0.1.0-beta.0': '0.1.0-beta.0'
+      })
+    )
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('0.1.0-beta.0')
+  })
+
   it('waits for npm view when no cached package version exists yet', async () => {
     await installFakeNpm()
     vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '3.0.0')

package/__tests__/runtime-package.spec.ts

@@ -26,13 +26,13 @@ describe('bootstrap runtime package commands', () => {
     await rm(tempDir, { force: true, recursive: true })
   })
 
-  const writeCachedPackage = async (packageName: string, version: string) => {
+  const writeCachedPackage = async (packageName: string, version: string, cacheVersion = version) => {
     const sanitizedName = packageName.replace(/^@/, '').replace(/[\\/]/g, '__')
     const packageDir = path.join(
       tempDir,
       '.oneworks/bootstrap/npm',
       sanitizedName,
-      version,
+      cacheVersion,
       'node_modules',
       ...packageName.split('/')
     )
@@ -190,6 +190,49 @@ process.exit(1)
     ).resolves.toBeUndefined()
   })
 
+  it('installs a runtime package under an explicit cache version', async () => {
+    vi.stubEnv('ONEWORKS_TEST_NPM_VERSION', '9.9.9')
+
+    await expect(installRuntimePackage('server', {
+      cacheVersion: 'dev-local',
+      version: '2.2.0'
+    })).resolves.toMatchObject({
+      cacheVersion: 'dev-local',
+      installedVersion: '2.2.0',
+      latestInstalled: true,
+      latestVersion: '2.2.0',
+      packageName: '@oneworks/server',
+      requestedVersion: '2.2.0',
+      target: 'server',
+      updateAvailable: false
+    })
+    await expect(
+      writeFile(
+        path.join(
+          tempDir,
+          '.oneworks/bootstrap/npm/oneworks__server/dev-local/node_modules/@oneworks/server/probe'
+        ),
+        'ok'
+      )
+    ).resolves.toBeUndefined()
+  })
+
+  it('uses the runtime package cache version env for check and install', async () => {
+    await writeCachedPackage('@oneworks/server', '2.2.0', 'dev-env')
+    vi.stubEnv('ONEWORKS_RUNTIME_PACKAGE_CACHE_VERSION', 'dev-env')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VERSION', '2.2.0')
+
+    await expect(checkRuntimePackage('server')).resolves.toMatchObject({
+      cacheVersion: 'dev-env',
+      installedVersion: '2.2.0',
+      latestInstalled: true,
+      latestVersion: '2.2.0',
+      packageName: '@oneworks/server',
+      target: 'server',
+      updateAvailable: false
+    })
+  })
+
   it('installs the latest client runtime package target', async () => {
     vi.stubEnv('ONEWORKS_TEST_NPM_VERSION', '2.2.0')
 
@@ -208,4 +251,10 @@ process.exit(1)
       'Runtime package version must be an exact semver version'
     )
   })
+
+  it('rejects unsafe runtime package cache versions', async () => {
+    await expect(checkRuntimePackage('cli', { cacheVersion: '../dev', version: '1.0.0' })).rejects.toThrow(
+      'Runtime package cache version contains unsupported characters'
+    )
+  })
 })

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "oneworks",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-beta.1",
+  "description": "One Works bootstrap launcher",
   "repository": {
     "type": "git",
     "url": "https://github.com/oneworks-ai/app.git",
     "directory": "apps/bootstrap"
   },
-  "description": "One Works bootstrap launcher",
   "oneworks": {
     "runtimeTranspile": true,
     "publishAliases": [
@@ -26,7 +26,7 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "commander": "^12.1.0",
-    "@oneworks/cli-helper": "0.1.0-alpha.0"
+    "@oneworks/cli-helper": "0.1.0-beta.1"
   },
   "scripts": {
     "test": "pnpm -C ../.. exec vitest run --workspace vitest.workspace.ts --project node apps/bootstrap/__tests__"

package/src/npm-package-cache.ts

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- package cache resolution keeps shared cache lookup and version fallback policy together. */
 import { createHash } from 'node:crypto'
 import { existsSync } from 'node:fs'
 import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
@@ -9,6 +10,12 @@ import { resolveBootstrapPackageCacheDir, resolveRealHomeDir } from './paths'
 const DEFAULT_PACKAGE_TAG = 'latest'
 const DEFAULT_PACKAGE_LOOKUP_TIMEOUT_MS = 1_000
 const DEFAULT_CACHE_FIRST = true
+const PACKAGE_CACHE_VERSION_PATTERN = /^[\w.+-]+$/u
+
+export const RUNTIME_PACKAGE_CACHE_VERSION_ENV = '__ONEWORKS_RUNTIME_PACKAGE_CACHE_VERSION__'
+export const PUBLIC_RUNTIME_PACKAGE_CACHE_VERSION_ENV = 'ONEWORKS_RUNTIME_PACKAGE_CACHE_VERSION'
+export const DESKTOP_DEV_RUNTIME_VERSION_ENV = '__ONEWORKS_DESKTOP_DEV_RUNTIME_VERSION__'
+export const PUBLIC_DESKTOP_DEV_RUNTIME_VERSION_ENV = 'ONEWORKS_DESKTOP_DEV_RUNTIME_VERSION'
 
 interface PublishedPackageVersionMetadata {
   lookupKey: string
@@ -58,8 +65,33 @@ export const shouldUseCachedPackageVersionFirst = () => {
   return !['0', 'false', 'no', 'off'].includes(rawValue)
 }
 
-export const resolvePackageCacheDir = (packageName: string, version: string) => (
-  path.join(resolveBootstrapPackageCacheDir(), 'npm', sanitizePackageName(packageName), version)
+export const normalizePackageCacheVersion = (value: string | undefined) => {
+  const normalized = value?.trim()
+  if (normalized == null || normalized === '') return undefined
+  if (!PACKAGE_CACHE_VERSION_PATTERN.test(normalized) || normalized === '.' || normalized === '..') {
+    throw new Error(`Runtime package cache version contains unsupported characters: ${normalized}.`)
+  }
+  return normalized
+}
+
+export const resolveRuntimePackageCacheVersion = () => (
+  normalizePackageCacheVersion(process.env[RUNTIME_PACKAGE_CACHE_VERSION_ENV]) ??
+    normalizePackageCacheVersion(process.env[PUBLIC_RUNTIME_PACKAGE_CACHE_VERSION_ENV]) ??
+    normalizePackageCacheVersion(process.env[DESKTOP_DEV_RUNTIME_VERSION_ENV]) ??
+    normalizePackageCacheVersion(process.env[PUBLIC_DESKTOP_DEV_RUNTIME_VERSION_ENV])
+)
+
+export const resolvePackageCacheDir = (
+  packageName: string,
+  version: string,
+  options: { cacheVersion?: string } = {}
+) => (
+  path.join(
+    resolveBootstrapPackageCacheDir(),
+    'npm',
+    sanitizePackageName(packageName),
+    normalizePackageCacheVersion(options.cacheVersion) ?? version
+  )
 )
 
 export const resolvePackageCacheRootDir = (packageName: string) => (
@@ -109,22 +141,29 @@ const readOptionalFile = async (filePath: string | undefined) => {
   }
 }
 
-const resolvePackageLookupKey = async (packageName: string) => {
+const resolvePackageLookupKey = async (
+  packageName: string,
+  options: { lookupScope?: string } = {}
+) => {
   const env = resolvePackageManagerEnv()
   const userConfig = env.npm_config_userconfig ?? env.NPM_CONFIG_USERCONFIG
   const userConfigContent = await readOptionalFile(userConfig)
+  const packageTag = options.lookupScope?.trim() || resolvePackageTag()
 
   return JSON.stringify({
     packageName,
-    packageTag: resolvePackageTag(),
+    packageTag,
     registry: env.npm_config_registry ?? env.NPM_CONFIG_REGISTRY ?? '',
     userConfig: userConfig ?? '',
     userConfigContentHash: userConfigContent == null ? '' : hashValue(userConfigContent)
   })
 }
 
-const resolvePackageVersionMetadataPath = async (packageName: string) => {
-  const lookupKey = await resolvePackageLookupKey(packageName)
+const resolvePackageVersionMetadataPath = async (
+  packageName: string,
+  options: { lookupScope?: string } = {}
+) => {
+  const lookupKey = await resolvePackageLookupKey(packageName, options)
   return {
     lookupKey,
     metadataPath: path.join(
@@ -134,8 +173,12 @@ const resolvePackageVersionMetadataPath = async (packageName: string) => {
   }
 }
 
-export const readPublishedPackageVersionMetadata = async (packageName: string) => {
-  const { lookupKey, metadataPath } = await resolvePackageVersionMetadataPath(packageName)
+export const readPublishedPackageVersionMetadata = async (
+  packageName: string,
+  options: { lookupScope?: string } = {}
+) => {
+  const packageTag = options.lookupScope?.trim() || resolvePackageTag()
+  const { lookupKey, metadataPath } = await resolvePackageVersionMetadataPath(packageName, options)
 
   try {
     const content = await readFile(metadataPath, 'utf8')
@@ -143,7 +186,7 @@ export const readPublishedPackageVersionMetadata = async (packageName: string) =
     if (
       parsed.lookupKey === lookupKey &&
       parsed.packageName === packageName &&
-      parsed.packageTag === resolvePackageTag() &&
+      parsed.packageTag === packageTag &&
       typeof parsed.version === 'string' &&
       parsed.version.trim()
     ) {
@@ -159,15 +202,20 @@ export const readPublishedPackageVersionMetadata = async (packageName: string) =
   return undefined
 }
 
-export const writePublishedPackageVersionMetadata = async (packageName: string, version: string) => {
-  const { lookupKey, metadataPath } = await resolvePackageVersionMetadataPath(packageName)
+export const writePublishedPackageVersionMetadata = async (
+  packageName: string,
+  version: string,
+  options: { lookupScope?: string } = {}
+) => {
+  const packageTag = options.lookupScope?.trim() || resolvePackageTag()
+  const { lookupKey, metadataPath } = await resolvePackageVersionMetadataPath(packageName, options)
   await ensureDirectory(path.dirname(metadataPath))
 
   const tempPath = `${metadataPath}.${process.pid}.${Date.now()}.tmp`
   const metadata: PublishedPackageVersionMetadata = {
     lookupKey,
     packageName,
-    packageTag: resolvePackageTag(),
+    packageTag,
     resolvedAt: new Date().toISOString(),
     version
   }

package/src/npm-package-install.ts

@@ -6,10 +6,12 @@ import {
   compareVersionLike,
   ensureDirectory,
   isExistingPath,
+  normalizePackageCacheVersion,
   resolvePackageCacheDir,
   resolvePackageCacheRootDir,
   resolvePackageInstallDir,
-  resolvePackageManagerEnv
+  resolvePackageManagerEnv,
+  resolveRuntimePackageCacheVersion
 } from './npm-package-cache'
 import { runBufferedCommand } from './process-utils'
 import { createBootstrapProgress } from './progress'
@@ -17,6 +19,7 @@ import { createBootstrapProgress } from './progress'
 const NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm'
 
 interface InstalledPackageInfo {
+  cacheVersion: string
   packageDir: string
   version: string
 }
@@ -36,7 +39,13 @@ export const readInstalledPackageVersion = async (packageDir: string) => {
   }
 }
 
-export const findInstalledPublishedPackageVersion = async (packageName: string) => {
+export const findInstalledPublishedPackageVersion = async (
+  packageName: string,
+  options: {
+    preferredVersion?: string
+    versionFilter?: (version: string) => boolean
+  } = {}
+) => {
   let versions: string[]
   try {
     versions = (await readdir(resolvePackageCacheRootDir(packageName), { withFileTypes: true }))
@@ -48,6 +57,9 @@ export const findInstalledPublishedPackageVersion = async (packageName: string)
 
   const installedVersions: string[] = []
   for (const version of versions) {
+    if (options.versionFilter != null && !options.versionFilter(version)) {
+      continue
+    }
     const packageDir = resolvePackageInstallDir(resolvePackageCacheDir(packageName, version), packageName)
     const installedVersion = await readInstalledPackageVersion(packageDir)
     if (installedVersion === version) {
@@ -55,6 +67,10 @@ export const findInstalledPublishedPackageVersion = async (packageName: string)
     }
   }
 
+  if (options.preferredVersion != null && installedVersions.includes(options.preferredVersion)) {
+    return options.preferredVersion
+  }
+
   return installedVersions.sort(compareVersionLike).at(-1)
 }
 
@@ -63,12 +79,19 @@ const formatInstallError = (message: string, stderr: string) => {
   return detail ? `${message}\n${detail}` : message
 }
 
-export const installPublishedPackage = async (packageName: string, version: string): Promise<InstalledPackageInfo> => {
-  const cacheDir = resolvePackageCacheDir(packageName, version)
+export const installPublishedPackage = async (
+  packageName: string,
+  version: string,
+  options: { cacheVersion?: string } = {}
+): Promise<InstalledPackageInfo> => {
+  const cacheVersion = normalizePackageCacheVersion(options.cacheVersion) ??
+    resolveRuntimePackageCacheVersion() ??
+    version
+  const cacheDir = resolvePackageCacheDir(packageName, version, { cacheVersion })
   const packageDir = resolvePackageInstallDir(cacheDir, packageName)
   const installedVersion = await readInstalledPackageVersion(packageDir)
   if (installedVersion === version) {
-    return { packageDir, version }
+    return { cacheVersion, packageDir, version }
   }
 
   const stagingDir = `${cacheDir}.tmp-${process.pid}-${Date.now()}`
@@ -76,7 +99,9 @@ export const installPublishedPackage = async (packageName: string, version: stri
   await ensureDirectory(stagingDir)
 
   const progress = createBootstrapProgress({
-    label: `installing ${packageName}@${version} into bootstrap cache`
+    label: cacheVersion === version
+      ? `installing ${packageName}@${version} into bootstrap cache`
+      : `installing ${packageName}@${version} into bootstrap cache ${cacheVersion}`
   })
   try {
     const result = await runBufferedCommand({
@@ -100,7 +125,11 @@ export const installPublishedPackage = async (packageName: string, version: stri
     await ensureDirectory(path.dirname(cacheDir))
     await rm(cacheDir, { recursive: true, force: true })
     await rename(stagingDir, cacheDir)
-    progress.finish(`cached ${packageName}@${version}`)
+    progress.finish(
+      cacheVersion === version
+        ? `cached ${packageName}@${version}`
+        : `cached ${packageName}@${version} as ${cacheVersion}`
+    )
   } catch (error) {
     progress.fail(`failed to cache ${packageName}@${version}`)
     await rm(stagingDir, { recursive: true, force: true }).catch(() => {})
@@ -108,6 +137,7 @@ export const installPublishedPackage = async (packageName: string, version: stri
   }
 
   return {
+    cacheVersion,
     packageDir: resolvePackageInstallDir(cacheDir, packageName),
     version
   }

package/src/npm-package.ts

@@ -8,14 +8,12 @@ import {
   readPublishedPackageVersionMetadata,
   resolvePackageLookupTimeoutMs,
   resolvePackageManagerEnv,
-  resolvePackageTag,
   shouldUseCachedPackageVersionFirst,
   writePublishedPackageVersionMetadata
 } from './npm-package-cache'
 import { findInstalledPublishedPackageVersion } from './npm-package-install'
-import { runBufferedCommand } from './process-utils'
-
-const NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+import { resolvePublishedPackageVersionFromRegistry } from './npm-registry'
+import { resolvePackageVersionRequest } from './package-version-request'
 
 export { resolvePackageManagerEnv } from './npm-package-cache'
 export { installPublishedPackage, resolvePackageBinEntrypoint } from './npm-package-install'
@@ -52,68 +50,21 @@ const spawnPackageVersionRefresh = (packageName: string) => {
   }
 }
 
-const resolvePublishedPackageVersionFromRegistry = async (
-  packageName: string,
-  options: { timeoutMs?: number } = {}
-) => {
-  const spec = `${packageName}@${resolvePackageTag()}`
-  const result = await runBufferedCommand({
-    command: NPM_BIN,
-    args: ['view', spec, 'version', '--json'],
-    env: resolvePackageManagerEnv(),
-    timeoutMs: options.timeoutMs
-  })
-
-  if (result.timedOut === true) {
-    return {
-      spec,
-      timedOut: true as const
-    }
-  }
-
-  if (result.code !== 0) {
-    throw new Error(`Failed to resolve published version for ${spec}:\n${result.stderr.trim()}`)
-  }
-
-  const normalizedOutput = result.stdout.trim()
-  if (!normalizedOutput) {
-    throw new Error(`No version was returned for ${spec}.`)
-  }
-
-  try {
-    const parsed = JSON.parse(normalizedOutput) as unknown
-    if (typeof parsed === 'string' && parsed.trim()) {
-      return {
-        spec,
-        version: parsed.trim()
-      }
-    }
-  } catch {
-    // fall through
-  }
-
-  const unquotedOutput = normalizedOutput.replace(/^"|"$/g, '').trim()
-  if (!unquotedOutput) {
-    throw new Error(`Invalid published version for ${spec}: ${normalizedOutput}`)
-  }
-
-  return {
-    spec,
-    version: unquotedOutput
-  }
-}
-
 export const resolvePublishedPackageVersion = async (
   packageName: string,
   options: { cacheFirst?: boolean } = {}
 ) => {
-  const cachedMetadata = await readPublishedPackageVersionMetadata(packageName)
+  const request = resolvePackageVersionRequest(packageName)
+  const cachedMetadata = await readPublishedPackageVersionMetadata(packageName, { lookupScope: request.lookupScope })
   if (cachedMetadata != null && (options.cacheFirst ?? shouldUseCachedPackageVersionFirst())) {
     spawnPackageVersionRefresh(packageName)
     return cachedMetadata.version
   }
 
-  const cachedInstalledVersion = await findInstalledPublishedPackageVersion(packageName)
+  const cachedInstalledVersion = await findInstalledPublishedPackageVersion(packageName, {
+    preferredVersion: request.exactVersion,
+    versionFilter: request.versionFilter
+  })
   if (cachedInstalledVersion != null && (options.cacheFirst ?? shouldUseCachedPackageVersionFirst())) {
     spawnPackageVersionRefresh(packageName)
     return cachedInstalledVersion
@@ -121,6 +72,7 @@ export const resolvePublishedPackageVersion = async (
 
   const registryResult = await resolvePublishedPackageVersionFromRegistry(
     packageName,
+    request,
     cachedMetadata == null
       ? {}
       : {
@@ -129,15 +81,17 @@ export const resolvePublishedPackageVersion = async (
   )
 
   if ('version' in registryResult) {
-    await writePublishedPackageVersionMetadata(packageName, registryResult.version)
+    await writePublishedPackageVersionMetadata(packageName, registryResult.version, {
+      lookupScope: request.lookupScope
+    })
     return registryResult.version
   }
 
   if (cachedMetadata == null) {
     // This is not expected because uncached lookups do not use a timeout.
-    const retryResult = await resolvePublishedPackageVersionFromRegistry(packageName)
+    const retryResult = await resolvePublishedPackageVersionFromRegistry(packageName, request)
     if ('version' in retryResult) {
-      await writePublishedPackageVersionMetadata(packageName, retryResult.version)
+      await writePublishedPackageVersionMetadata(packageName, retryResult.version, { lookupScope: request.lookupScope })
       return retryResult.version
     }
     throw new Error(`Failed to resolve published version for ${retryResult.spec}.`)

package/src/npm-registry.ts

@@ -0,0 +1,154 @@
+import process from 'node:process'
+
+import { resolvePackageManagerEnv } from './npm-package-cache'
+import { comparePackageVersions } from './package-version-request'
+import type { PackageVersionRequest } from './package-version-request'
+import { runBufferedCommand } from './process-utils'
+
+const NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+
+const parseVersionOutput = (spec: string, output: string) => {
+  const normalizedOutput = output.trim()
+  if (!normalizedOutput) {
+    throw new Error(`No version was returned for ${spec}.`)
+  }
+
+  try {
+    const parsed = JSON.parse(normalizedOutput) as unknown
+    if (typeof parsed === 'string' && parsed.trim()) {
+      return parsed.trim()
+    }
+  } catch {
+    // fall through
+  }
+
+  const unquotedOutput = normalizedOutput.replace(/^"|"$/g, '').trim()
+  if (!unquotedOutput) {
+    throw new Error(`Invalid published version for ${spec}: ${normalizedOutput}`)
+  }
+
+  return unquotedOutput
+}
+
+const resolvePublishedPackageVersionBySpec = async (
+  spec: string,
+  options: { allowMissing?: boolean; timeoutMs?: number } = {}
+) => {
+  const result = await runBufferedCommand({
+    command: NPM_BIN,
+    args: ['view', spec, 'version', '--json'],
+    env: resolvePackageManagerEnv(),
+    timeoutMs: options.timeoutMs
+  })
+
+  if (result.timedOut === true) {
+    return {
+      spec,
+      timedOut: true as const
+    }
+  }
+
+  if (result.code !== 0) {
+    if (options.allowMissing === true) {
+      return {
+        missing: true as const,
+        spec
+      }
+    }
+    throw new Error(`Failed to resolve published version for ${spec}:\n${result.stderr.trim()}`)
+  }
+
+  return {
+    spec,
+    version: parseVersionOutput(spec, result.stdout)
+  }
+}
+
+const parseVersionsOutput = (spec: string, output: string) => {
+  const normalizedOutput = output.trim()
+  if (!normalizedOutput) {
+    throw new Error(`No versions were returned for ${spec}.`)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(normalizedOutput) as unknown
+  } catch {
+    parsed = normalizedOutput.replace(/^"|"$/g, '').trim()
+  }
+
+  const versions = Array.isArray(parsed)
+    ? parsed.filter((version): version is string => typeof version === 'string' && version.trim() !== '')
+    : typeof parsed === 'string' && parsed.trim() !== ''
+    ? [parsed.trim()]
+    : []
+  if (versions.length === 0) {
+    throw new Error(`Invalid published versions for ${spec}: ${normalizedOutput}`)
+  }
+  return versions
+}
+
+const resolvePublishedPackageVersionsFromRegistry = async (
+  packageName: string,
+  options: { timeoutMs?: number } = {}
+) => {
+  const result = await runBufferedCommand({
+    command: NPM_BIN,
+    args: ['view', packageName, 'versions', '--json'],
+    env: resolvePackageManagerEnv(),
+    timeoutMs: options.timeoutMs
+  })
+
+  if (result.timedOut === true) {
+    return {
+      spec: packageName,
+      timedOut: true as const
+    }
+  }
+
+  if (result.code !== 0) {
+    throw new Error(`Failed to resolve published versions for ${packageName}:\n${result.stderr.trim()}`)
+  }
+
+  return {
+    spec: packageName,
+    versions: parseVersionsOutput(packageName, result.stdout)
+  }
+}
+
+export const resolvePublishedPackageVersionFromRegistry = async (
+  packageName: string,
+  request: PackageVersionRequest,
+  options: { timeoutMs?: number } = {}
+) => {
+  if (request.exactVersion == null) {
+    return await resolvePublishedPackageVersionBySpec(request.packageSpec, options)
+  }
+
+  const exactResult = await resolvePublishedPackageVersionBySpec(request.packageSpec, {
+    allowMissing: true,
+    timeoutMs: options.timeoutMs
+  })
+  if ('version' in exactResult || 'timedOut' in exactResult) {
+    return exactResult
+  }
+
+  const versionsResult = await resolvePublishedPackageVersionsFromRegistry(packageName, options)
+  if ('timedOut' in versionsResult) {
+    return versionsResult
+  }
+
+  const matchedVersion = versionsResult.versions
+    .filter(version => request.versionFilter == null || request.versionFilter(version))
+    .sort(comparePackageVersions)
+    .at(-1)
+  if (matchedVersion == null) {
+    throw new Error(
+      `No published version for ${packageName} matches bootstrap runtime series ${request.exactVersion}.`
+    )
+  }
+  return {
+    spec: `${packageName} versions`,
+    version: matchedVersion
+  }
+}

package/src/package-version-request.ts

@@ -0,0 +1,121 @@
+import { createRequire } from 'node:module'
+import process from 'node:process'
+
+import { compareVersionLike, resolvePackageTag } from './npm-package-cache'
+
+const BOOTSTRAP_PACKAGE_VERSION_ENV = 'ONEWORKS_BOOTSTRAP_PACKAGE_VERSION'
+
+interface ParsedSemver {
+  major: number
+  minor: number
+  patch: number
+  prerelease: string[]
+}
+
+export interface PackageVersionRequest {
+  exactVersion?: string
+  lookupScope: string
+  packageSpec: string
+  tag?: string
+  versionFilter?: (version: string) => boolean
+}
+
+const parseSemver = (version: string): ParsedSemver | undefined => {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(version.trim())
+  if (match == null) return undefined
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4]?.split('.') ?? []
+  }
+}
+
+const comparePrereleaseIdentifiers = (left: string, right: string) => {
+  const leftNumber = /^\d+$/u.test(left) ? Number(left) : undefined
+  const rightNumber = /^\d+$/u.test(right) ? Number(right) : undefined
+  if (leftNumber != null && rightNumber != null) return leftNumber - rightNumber
+  if (leftNumber != null) return -1
+  if (rightNumber != null) return 1
+  return left.localeCompare(right)
+}
+
+const compareSemver = (left: ParsedSemver, right: ParsedSemver) => {
+  const coreDiff = left.major - right.major || left.minor - right.minor || left.patch - right.patch
+  if (coreDiff !== 0) return coreDiff
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0
+  if (left.prerelease.length === 0) return 1
+  if (right.prerelease.length === 0) return -1
+  const maxLength = Math.max(left.prerelease.length, right.prerelease.length)
+  for (let index = 0; index < maxLength; index += 1) {
+    const leftPart = left.prerelease[index]
+    const rightPart = right.prerelease[index]
+    if (leftPart == null) return -1
+    if (rightPart == null) return 1
+    const diff = comparePrereleaseIdentifiers(leftPart, rightPart)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+export const comparePackageVersions = (left: string, right: string) => {
+  const leftSemver = parseSemver(left)
+  const rightSemver = parseSemver(right)
+  if (leftSemver != null && rightSemver != null) return compareSemver(leftSemver, rightSemver)
+  return compareVersionLike(left, right)
+}
+
+const hasSameSemverCore = (left: ParsedSemver, right: ParsedSemver) => (
+  left.major === right.major && left.minor === right.minor && left.patch === right.patch
+)
+
+const readBootstrapPackageVersion = () => {
+  const envVersion = process.env[BOOTSTRAP_PACKAGE_VERSION_ENV]?.trim()
+  if (envVersion) return envVersion
+
+  try {
+    const requireFromHere = createRequire(import.meta.url)
+    const packageJsonPath = requireFromHere.resolve('oneworks/package.json')
+    const packageJson = requireFromHere(packageJsonPath) as { version?: unknown }
+    return typeof packageJson.version === 'string' && packageJson.version.trim()
+      ? packageJson.version.trim()
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export const resolvePackageVersionRequest = (packageName: string): PackageVersionRequest => {
+  const explicitTag = process.env.ONEWORKS_BOOTSTRAP_PACKAGE_TAG?.trim()
+  if (explicitTag) {
+    return {
+      lookupScope: `tag:${explicitTag}`,
+      packageSpec: `${packageName}@${explicitTag}`,
+      tag: explicitTag
+    }
+  }
+
+  const bootstrapVersion = readBootstrapPackageVersion()
+  const parsedBootstrapVersion = bootstrapVersion == null ? undefined : parseSemver(bootstrapVersion)
+  const prereleaseChannel = parsedBootstrapVersion?.prerelease[0]
+  if (bootstrapVersion != null && parsedBootstrapVersion != null && prereleaseChannel != null) {
+    return {
+      exactVersion: bootstrapVersion,
+      lookupScope: `bootstrap:${bootstrapVersion}:channel:${prereleaseChannel}`,
+      packageSpec: `${packageName}@${bootstrapVersion}`,
+      versionFilter: (version) => {
+        const parsedVersion = parseSemver(version)
+        return parsedVersion != null &&
+          hasSameSemverCore(parsedVersion, parsedBootstrapVersion) &&
+          parsedVersion.prerelease[0] === prereleaseChannel
+      }
+    }
+  }
+
+  const tag = resolvePackageTag()
+  return {
+    lookupScope: `tag:${tag}`,
+    packageSpec: `${packageName}@${tag}`,
+    tag
+  }
+}

package/src/program.ts

@@ -35,6 +35,7 @@ type BootstrapTarget =
   }
   | {
     action: RuntimePackageAction
+    cacheVersion?: string
     json: boolean
     kind: 'runtime-package'
     target?: string
@@ -88,6 +89,7 @@ const parseRuntimePackageTarget = (args: string[]): BootstrapTarget => {
   }
 
   let version: string | undefined
+  let cacheVersion: string | undefined
   for (let index = 0; index < forwardedArgs.length; index += 1) {
     const arg = forwardedArgs[index]
     if (arg === '--version') {
@@ -109,6 +111,28 @@ const parseRuntimePackageTarget = (args: string[]): BootstrapTarget => {
       version = value
       forwardedArgs.splice(index, 1)
       index -= 1
+      continue
+    }
+
+    if (arg === '--cache-version') {
+      const value = forwardedArgs[index + 1]
+      if (value == null || value.trim() === '') {
+        throw new Error('Runtime package --cache-version requires a value.')
+      }
+      cacheVersion = value
+      forwardedArgs.splice(index, 2)
+      index -= 1
+      continue
+    }
+
+    if (arg?.startsWith('--cache-version=')) {
+      const value = arg.slice('--cache-version='.length)
+      if (value.trim() === '') {
+        throw new Error('Runtime package --cache-version requires a value.')
+      }
+      cacheVersion = value
+      forwardedArgs.splice(index, 1)
+      index -= 1
     }
   }
 
@@ -130,6 +154,7 @@ const parseRuntimePackageTarget = (args: string[]): BootstrapTarget => {
 
   return {
     action,
+    ...(cacheVersion != null ? { cacheVersion } : {}),
     json,
     kind: 'runtime-package',
     target: selectorTarget,
@@ -216,6 +241,7 @@ Examples:
   npx oneworks runtime check cli@0.1.0-alpha.0
   npx oneworks runtime install server
   npx oneworks runtime install server --version 0.1.0-alpha.0
+  npx oneworks runtime install server --version 0.1.0-alpha.0 --cache-version dev-local
   npx oneworks app
   npx oneworks app cache
   npx oneworks app --no-cache
@@ -240,15 +266,20 @@ Examples:
       }
 
       if (target.kind === 'runtime-package') {
+        const runtimeOptions: RuntimePackageOptions = {
+          ...(target.version == null ? {} : { version: target.version }),
+          ...(target.cacheVersion == null ? {} : { cacheVersion: target.cacheVersion })
+        }
+        const hasRuntimeOptions = Object.keys(runtimeOptions).length > 0
         let status: RuntimePackageStatus
         if (target.action === 'install') {
-          status = target.version == null
+          status = !hasRuntimeOptions
             ? await deps.installRuntimePackage(target.target)
-            : await deps.installRuntimePackage(target.target, { version: target.version })
+            : await deps.installRuntimePackage(target.target, runtimeOptions)
         } else {
-          status = target.version == null
+          status = !hasRuntimeOptions
             ? await deps.checkRuntimePackage(target.target)
-            : await deps.checkRuntimePackage(target.target, { version: target.version })
+            : await deps.checkRuntimePackage(target.target, runtimeOptions)
         }
         const output = target.json ? JSON.stringify(status) : formatRuntimePackageStatus(status)
         process.stdout.write(`${output}\n`)

package/src/runtime-package.ts

@@ -1,5 +1,10 @@
 import { resolvePublishedPackageVersion } from './npm-package'
-import { resolvePackageCacheDir, resolvePackageInstallDir } from './npm-package-cache'
+import {
+  normalizePackageCacheVersion,
+  resolvePackageCacheDir,
+  resolvePackageInstallDir,
+  resolveRuntimePackageCacheVersion
+} from './npm-package-cache'
 import {
   findInstalledPublishedPackageVersion,
   installPublishedPackage,
@@ -10,10 +15,12 @@ export type RuntimePackageAction = 'check' | 'install'
 export type RuntimePackageTarget = 'cli' | 'client' | 'server' | 'web'
 
 export interface RuntimePackageOptions {
+  cacheVersion?: string
   version?: string
 }
 
 export interface RuntimePackageStatus {
+  cacheVersion?: string
   installed: boolean
   installedVersion?: string
   latestInstalled: boolean
@@ -56,8 +63,11 @@ export const resolveRuntimePackageTarget = (value: string | undefined): RuntimeP
   )
 }
 
-const readVersionInstalledAt = async (packageName: string, version: string) => {
-  const packageDir = resolvePackageInstallDir(resolvePackageCacheDir(packageName, version), packageName)
+const readVersionInstalledAt = async (packageName: string, version: string, cacheVersion = version) => {
+  const packageDir = resolvePackageInstallDir(
+    resolvePackageCacheDir(packageName, version, { cacheVersion }),
+    packageName
+  )
   return await readInstalledPackageVersion(packageDir)
 }
 
@@ -70,12 +80,19 @@ const createRuntimePackageStatus = async (
   target: RuntimePackageTarget,
   packageName: string,
   targetVersion: string,
-  requestedVersion: string | undefined
+  requestedVersion: string | undefined,
+  requestedCacheVersion: string | undefined
 ): Promise<RuntimePackageStatus> => {
-  const installedVersion = await findInstalledPublishedPackageVersion(packageName)
-  const targetInstalled = await readVersionInstalledAt(packageName, targetVersion) === targetVersion
+  const cacheVersion = normalizePackageCacheVersion(requestedCacheVersion)
+  const resolvedCacheVersion = cacheVersion ?? targetVersion
+  const installedVersion = cacheVersion == null
+    ? await findInstalledPublishedPackageVersion(packageName)
+    : await readVersionInstalledAt(packageName, targetVersion, resolvedCacheVersion)
+  const targetInstalled =
+    await readVersionInstalledAt(packageName, targetVersion, resolvedCacheVersion) === targetVersion
 
   return {
+    ...(cacheVersion != null ? { cacheVersion } : {}),
     installed: installedVersion != null,
     ...(installedVersion != null ? { installedVersion } : {}),
     latestInstalled: targetInstalled,
@@ -83,7 +100,9 @@ const createRuntimePackageStatus = async (
     packageName,
     ...(requestedVersion != null ? { requestedVersion } : {}),
     target,
-    updateAvailable: requestedVersion != null ? !targetInstalled : installedVersion !== targetVersion
+    updateAvailable: requestedVersion != null || cacheVersion != null
+      ? !targetInstalled
+      : installedVersion !== targetVersion
   }
 }
 
@@ -94,8 +113,9 @@ export const checkRuntimePackage = async (
   const target = resolveRuntimePackageTarget(targetValue)
   const packageName = RUNTIME_PACKAGE_NAMES[target]
   const requestedVersion = normalizeRequestedVersion(options.version)
+  const cacheVersion = normalizePackageCacheVersion(options.cacheVersion) ?? resolveRuntimePackageCacheVersion()
   const targetVersion = requestedVersion ?? await resolveRuntimePackageVersion(packageName, options)
-  return await createRuntimePackageStatus(target, packageName, targetVersion, requestedVersion)
+  return await createRuntimePackageStatus(target, packageName, targetVersion, requestedVersion, cacheVersion)
 }
 
 export const installRuntimePackage = async (
@@ -105,19 +125,31 @@ export const installRuntimePackage = async (
   const target = resolveRuntimePackageTarget(targetValue)
   const packageName = RUNTIME_PACKAGE_NAMES[target]
   const requestedVersion = normalizeRequestedVersion(options.version)
+  const cacheVersion = normalizePackageCacheVersion(options.cacheVersion) ?? resolveRuntimePackageCacheVersion()
   const targetVersion = requestedVersion ?? await resolveRuntimePackageVersion(packageName, options)
-  await installPublishedPackage(packageName, targetVersion)
-  return await createRuntimePackageStatus(target, packageName, targetVersion, requestedVersion)
+  await installPublishedPackage(packageName, targetVersion, cacheVersion == null ? {} : { cacheVersion })
+  return await createRuntimePackageStatus(target, packageName, targetVersion, requestedVersion, cacheVersion)
 }
 
 export const formatRuntimePackageStatus = (status: RuntimePackageStatus) => {
   const current = status.installedVersion ?? 'not installed'
   if (status.requestedVersion != null) {
+    if (status.cacheVersion != null) {
+      return status.latestInstalled
+        ? `${status.packageName}@${status.requestedVersion} cached as ${status.cacheVersion}`
+        : `${status.packageName}@${status.requestedVersion} not cached as ${status.cacheVersion} (${current})`
+    }
     return status.latestInstalled
       ? `${status.packageName}@${status.requestedVersion} cached`
       : `${status.packageName}@${status.requestedVersion} not cached (${current})`
   }
 
+  if (status.cacheVersion != null) {
+    return status.latestInstalled
+      ? `${status.packageName}@${status.latestVersion} cached as ${status.cacheVersion}`
+      : `${status.packageName}@${status.latestVersion} not cached as ${status.cacheVersion} (${current})`
+  }
+
   const suffix = status.updateAvailable
     ? `update available: ${current} -> ${status.latestVersion}`
     : `up to date: ${status.latestVersion}`