oneworks 0.0.0 → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present One Works contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/__tests__/adapter-package-cache.spec.ts

@@ -0,0 +1,109 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  readCliAdapterPackageRequest,
+  resolveAdapterPackageName,
+  resolveCliAdapterPackageDir
+} from '../src/adapter-package-cache'
+
+const tempDirs: string[] = []
+
+afterEach(async () => {
+  vi.unstubAllEnvs()
+  await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+const writeCachedAdapterPackage = async (homeDir: string, packageName: string, version: string) => {
+  const cacheDir = path.join(
+    homeDir,
+    '.oneworks/bootstrap/adapter-packages',
+    packageName.replace(/^@/, '').replace(/[\\/]/g, '__'),
+    version
+  )
+  const packageDir = path.join(cacheDir, 'node_modules', ...packageName.split('/'))
+  await mkdir(packageDir, { recursive: true })
+  await writeFile(
+    path.join(packageDir, 'package.json'),
+    JSON.stringify({ name: packageName, version }, null, 2)
+  )
+  return cacheDir
+}
+
+describe('bootstrap adapter package cache', () => {
+  it('normalizes built-in adapter ids to adapter package names', () => {
+    expect(resolveAdapterPackageName('codex')).toBe('@oneworks/adapter-codex')
+    expect(resolveAdapterPackageName('adapter-codex')).toBe('@oneworks/adapter-codex')
+    expect(resolveAdapterPackageName('claude')).toBe('@oneworks/adapter-claude-code')
+    expect(resolveAdapterPackageName('@acme/custom-adapter')).toBe('@acme/custom-adapter')
+  })
+
+  it('reads adapter requests from forwarded CLI arguments', () => {
+    expect(readCliAdapterPackageRequest(['--adapter', 'codex'], '0.1.0-alpha.0')).toEqual({
+      adapter: 'codex',
+      cliVersion: '0.1.0-alpha.0'
+    })
+    expect(readCliAdapterPackageRequest(['-Aadapter-codex@0.132.0'], '0.1.0-alpha.0')).toEqual({
+      adapter: 'adapter-codex@0.132.0',
+      cliVersion: '0.1.0-alpha.0'
+    })
+    expect(readCliAdapterPackageRequest(['--resume', 'sess-id'], '0.1.0-alpha.0', 'codex')).toEqual({
+      adapter: 'codex',
+      cliVersion: '0.1.0-alpha.0'
+    })
+  })
+
+  it('resolves an existing user-home adapter package cache before installing', async () => {
+    const homeDir = await mkdtemp(path.join(tmpdir(), 'ow-bootstrap-adapter-cache-'))
+    tempDirs.push(homeDir)
+    vi.stubEnv('__ONEWORKS_PROJECT_REAL_HOME__', homeDir)
+
+    const cacheDir = await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.3.1')
+
+    await expect(
+      resolveCliAdapterPackageDir({
+        adapter: 'codex',
+        cliVersion: '3.2.4-alpha.5'
+      })
+    ).resolves.toBe(cacheDir)
+  })
+
+  it('uses the highest cached adapter package that satisfies the CLI semver floor', async () => {
+    const homeDir = await mkdtemp(path.join(tmpdir(), 'ow-bootstrap-adapter-cache-'))
+    tempDirs.push(homeDir)
+    vi.stubEnv('__ONEWORKS_PROJECT_REAL_HOME__', homeDir)
+
+    await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.3.9')
+    const compatibleCacheDir = await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.4.1')
+    await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.5.0-beta')
+    await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '4.0.0')
+
+    await expect(
+      resolveCliAdapterPackageDir({
+        adapter: 'codex',
+        cliVersion: '3.4.0-rc'
+      })
+    ).resolves.toBe(compatibleCacheDir)
+  })
+
+  it('preserves prerelease CLI versions when matching adapter package caches', async () => {
+    const homeDir = await mkdtemp(path.join(tmpdir(), 'ow-bootstrap-adapter-cache-'))
+    tempDirs.push(homeDir)
+    vi.stubEnv('__ONEWORKS_PROJECT_REAL_HOME__', homeDir)
+
+    await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.3.9')
+    const prereleaseCacheDir = await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.4.0-rc')
+    await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '3.5.0-beta')
+    await writeCachedAdapterPackage(homeDir, '@oneworks/adapter-codex', '4.0.0')
+
+    await expect(
+      resolveCliAdapterPackageDir({
+        adapter: 'codex',
+        cliVersion: '3.4.0-rc'
+      })
+    ).resolves.toBe(prereleaseCacheDir)
+  })
+})

package/__tests__/cli.spec.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createBootstrapCli, routeBootstrapCommand } from '../src/program'
+
+describe('bootstrap cli', () => {
+  it('routes reserved web command to the web package', () => {
+    expect(routeBootstrapCommand('web', ['--port', '8787'])).toEqual({
+      commandName: 'oneworks-web',
+      forwardedArgs: ['--port', '8787'],
+      kind: 'package',
+      packageName: '@oneworks/web'
+    })
+  })
+
+  it('routes app to the desktop launcher', () => {
+    expect(routeBootstrapCommand('app', [])).toEqual({
+      forwardedArgs: [],
+      kind: 'desktop',
+      persistInstallMode: false
+    })
+  })
+
+  it('routes app cache to the desktop launcher in cache mode', () => {
+    expect(routeBootstrapCommand('app', ['cache'])).toEqual({
+      forwardedArgs: [],
+      installMode: 'cache',
+      kind: 'desktop',
+      persistInstallMode: true
+    })
+  })
+
+  it('routes app --no-cache to the desktop launcher in user mode', () => {
+    expect(routeBootstrapCommand('app', ['--no-cache'])).toEqual({
+      forwardedArgs: [],
+      installMode: 'user',
+      kind: 'desktop',
+      persistInstallMode: true
+    })
+  })
+
+  it('routes runtime package checks', () => {
+    expect(routeBootstrapCommand('runtime', ['check', 'cli', '--json'])).toEqual({
+      action: 'check',
+      json: true,
+      kind: 'runtime-package',
+      target: 'cli'
+    })
+  })
+
+  it('routes runtime package versions from target selectors', () => {
+    expect(routeBootstrapCommand('runtime', ['check', 'server@1.2.3', '--json'])).toEqual({
+      action: 'check',
+      json: true,
+      kind: 'runtime-package',
+      target: 'server',
+      version: '1.2.3'
+    })
+  })
+
+  it('routes runtime package versions from flags', () => {
+    expect(routeBootstrapCommand('runtime', ['install', 'client', '--version=2.3.4'])).toEqual({
+      action: 'install',
+      json: false,
+      kind: 'runtime-package',
+      target: 'client',
+      version: '2.3.4'
+    })
+  })
+
+  it('routes unknown commands through the CLI package', () => {
+    expect(routeBootstrapCommand('hello', [])).toEqual({
+      commandName: 'oneworks',
+      forwardedArgs: ['hello'],
+      kind: 'package',
+      packageName: '@oneworks/cli'
+    })
+  })
+
+  it('dispatches the desktop launcher for app', async () => {
+    const launchDesktopApp = vi.fn(async () => {})
+    const launchInstalledPackage = vi.fn(async () => 0)
+    const cli = createBootstrapCli({
+      launchDesktopApp,
+      launchInstalledPackage
+    })
+
+    await cli.parseAsync(['node', 'oneworks', 'app'])
+
+    expect(launchDesktopApp).toHaveBeenCalledWith({
+      forwardedArgs: [],
+      installMode: undefined,
+      persistInstallMode: false
+    })
+    expect(launchInstalledPackage).not.toHaveBeenCalled()
+  })
+
+  it('dispatches cache mode for app cache', async () => {
+    const launchDesktopApp = vi.fn(async () => {})
+    const launchInstalledPackage = vi.fn(async () => 0)
+    const cli = createBootstrapCli({
+      launchDesktopApp,
+      launchInstalledPackage
+    })
+
+    await cli.parseAsync(['node', 'oneworks', 'app', 'cache'])
+
+    expect(launchDesktopApp).toHaveBeenCalledWith({
+      forwardedArgs: [],
+      installMode: 'cache',
+      persistInstallMode: true
+    })
+    expect(launchInstalledPackage).not.toHaveBeenCalled()
+  })
+
+  it('dispatches forwarded commands through the CLI package', async () => {
+    const launchDesktopApp = vi.fn(async () => {})
+    const launchInstalledPackage = vi.fn(async () => 0)
+    const cli = createBootstrapCli({
+      launchDesktopApp,
+      launchInstalledPackage
+    })
+
+    await cli.parseAsync(['node', 'oneworks', 'hello'])
+
+    expect(launchInstalledPackage).toHaveBeenCalledWith({
+      packageName: '@oneworks/cli',
+      commandName: 'oneworks',
+      forwardedArgs: ['hello']
+    })
+    expect(launchDesktopApp).not.toHaveBeenCalled()
+  })
+
+  it('dispatches runtime package installation without launching a runtime', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+    const checkRuntimePackage = vi.fn(async () => {
+      throw new Error('unexpected check')
+    })
+    const installRuntimePackage = vi.fn(async () => ({
+      installed: true,
+      installedVersion: '1.2.3',
+      latestInstalled: true,
+      latestVersion: '1.2.3',
+      packageName: '@oneworks/cli',
+      target: 'cli' as const,
+      updateAvailable: false
+    }))
+    const launchDesktopApp = vi.fn(async () => {})
+    const launchInstalledPackage = vi.fn(async () => 0)
+    const cli = createBootstrapCli({
+      checkRuntimePackage,
+      installRuntimePackage,
+      launchDesktopApp,
+      launchInstalledPackage
+    })
+
+    await cli.parseAsync(['node', 'oneworks', 'runtime', 'install', 'cli', '--json'])
+
+    expect(installRuntimePackage).toHaveBeenCalledWith('cli')
+    expect(checkRuntimePackage).not.toHaveBeenCalled()
+    expect(launchDesktopApp).not.toHaveBeenCalled()
+    expect(launchInstalledPackage).not.toHaveBeenCalled()
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('"packageName":"@oneworks/cli"'))
+  })
+
+  it('dispatches runtime package installation with a requested version', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+    const checkRuntimePackage = vi.fn(async () => {
+      throw new Error('unexpected check')
+    })
+    const installRuntimePackage = vi.fn(async () => ({
+      installed: true,
+      installedVersion: '1.2.3',
+      latestInstalled: true,
+      latestVersion: '1.2.3',
+      packageName: '@oneworks/cli',
+      requestedVersion: '1.2.3',
+      target: 'cli' as const,
+      updateAvailable: false
+    }))
+    const cli = createBootstrapCli({
+      checkRuntimePackage,
+      installRuntimePackage,
+      launchDesktopApp: vi.fn(async () => {}),
+      launchInstalledPackage: vi.fn(async () => 0)
+    })
+
+    await cli.parseAsync(['node', 'oneworks', 'runtime', 'install', 'cli@1.2.3', '--json'])
+
+    expect(installRuntimePackage).toHaveBeenCalledWith('cli', { version: '1.2.3' })
+    expect(checkRuntimePackage).not.toHaveBeenCalled()
+    expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('"requestedVersion":"1.2.3"'))
+  })
+
+  it('forwards --help after a routed command', async () => {
+    const launchDesktopApp = vi.fn(async () => {})
+    const launchInstalledPackage = vi.fn(async () => 0)
+    const cli = createBootstrapCli({
+      launchDesktopApp,
+      launchInstalledPackage
+    })
+
+    await cli.parseAsync(['node', 'oneworks', 'web', '--help'])
+
+    expect(launchInstalledPackage).toHaveBeenCalledWith({
+      packageName: '@oneworks/web',
+      commandName: 'oneworks-web',
+      forwardedArgs: ['--help']
+    })
+  })
+})

package/__tests__/desktop-app.spec.ts

@@ -0,0 +1,106 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { __TEST_ONLY__ } from '../src/desktop-app'
+
+describe('desktop asset selection', () => {
+  const release = {
+    tagName: 'pkg/oneworks-desktop/v0.1.7',
+    assets: [
+      { name: 'oneworks-0.1.7-mac-arm64.zip', url: 'https://example.com/mac-arm64.zip' },
+      { name: 'oneworks-0.1.7-linux-x86_64.AppImage', url: 'https://example.com/linux.AppImage' },
+      { name: 'oneworks-0.1.7-win-x64.exe', url: 'https://example.com/win.exe' }
+    ]
+  }
+
+  it('selects a matching macOS archive', () => {
+    expect(__TEST_ONLY__.selectDesktopAsset(release, {
+      platform: 'darwin',
+      arch: 'arm64'
+    })).toEqual(release.assets[0])
+  })
+
+  it('selects a matching Linux AppImage', () => {
+    expect(__TEST_ONLY__.selectDesktopAsset(release, {
+      platform: 'linux',
+      arch: 'x64'
+    })).toEqual(release.assets[1])
+  })
+
+  it('selects a matching Windows installer when present', () => {
+    expect(__TEST_ONLY__.selectDesktopAsset(release, {
+      platform: 'win32',
+      arch: 'x64'
+    })).toEqual(release.assets[2])
+  })
+})
+
+describe('desktop install mode resolution', () => {
+  const originalRealHome = process.env.__ONEWORKS_PROJECT_REAL_HOME__
+  const originalStdinIsTTY = process.stdin.isTTY
+  const originalStdoutIsTTY = process.stdout.isTTY
+  let tempHomeDir = ''
+
+  beforeEach(async () => {
+    tempHomeDir = await mkdtemp(path.join(os.tmpdir(), 'ow-bootstrap-'))
+    process.env.__ONEWORKS_PROJECT_REAL_HOME__ = tempHomeDir
+  })
+
+  afterEach(async () => {
+    if (originalRealHome == null) {
+      delete process.env.__ONEWORKS_PROJECT_REAL_HOME__
+    } else {
+      process.env.__ONEWORKS_PROJECT_REAL_HOME__ = originalRealHome
+    }
+    Object.defineProperty(process.stdin, 'isTTY', { configurable: true, value: originalStdinIsTTY })
+    Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: originalStdoutIsTTY })
+    await rm(tempHomeDir, { recursive: true, force: true })
+  })
+
+  it('uses an explicit cache mode without prompting', async () => {
+    await expect(__TEST_ONLY__.resolveInstallMode({
+      explicitInstallMode: 'cache',
+      persistInstallMode: true
+    })).resolves.toBe('cache')
+    await expect(__TEST_ONLY__.readDesktopPreference()).resolves.toEqual({
+      installMode: 'cache'
+    })
+  })
+
+  it('uses an explicit user mode and stores it as the default', async () => {
+    await expect(__TEST_ONLY__.resolveInstallMode({
+      explicitInstallMode: 'user',
+      persistInstallMode: true
+    })).resolves.toBe('user')
+    await expect(__TEST_ONLY__.readDesktopPreference()).resolves.toEqual({
+      installMode: 'user'
+    })
+  })
+
+  it('defaults to user mode when no tty is available', async () => {
+    Object.defineProperty(process.stdin, 'isTTY', { configurable: true, value: false })
+    Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: false })
+
+    await expect(__TEST_ONLY__.resolveInstallMode({
+      explicitInstallMode: undefined,
+      persistInstallMode: false
+    })).resolves.toBe('user')
+  })
+
+  it('reuses the stored cache preference', async () => {
+    await mkdir(path.join(tempHomeDir, '.oneworks', 'bootstrap', 'desktop'), { recursive: true })
+    await writeFile(
+      path.join(tempHomeDir, '.oneworks', 'bootstrap', 'desktop', 'preferences.json'),
+      `${JSON.stringify({ installMode: 'cache' }, null, 2)}\n`
+    )
+
+    await expect(__TEST_ONLY__.resolveInstallMode({
+      explicitInstallMode: undefined,
+      persistInstallMode: false
+    })).resolves.toBe('cache')
+  })
+})

package/__tests__/npm-package.spec.ts

@@ -0,0 +1,149 @@
+import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { resolvePackageManagerEnv, resolvePublishedPackageVersion } from '../src/npm-package'
+
+describe('bootstrap npm package env', () => {
+  const originalCwd = process.cwd()
+  const originalPath = process.env.PATH
+  let tempDir: string
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(path.join(os.tmpdir(), 'oneworks-bootstrap-npm-'))
+    process.chdir(tempDir)
+    vi.restoreAllMocks()
+    vi.stubEnv('__ONEWORKS_PROJECT_REAL_HOME__', tempDir)
+    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('NPM_CONFIG_USERCONFIG', undefined)
+    vi.stubEnv('npm_config_userconfig', undefined)
+  })
+
+  afterEach(async () => {
+    process.chdir(originalCwd)
+    vi.restoreAllMocks()
+    vi.unstubAllEnvs()
+    await rm(tempDir, { force: true, recursive: true })
+  })
+
+  const installFakeNpm = async () => {
+    const binDir = path.join(tempDir, 'bin')
+    const npmBin = path.join(binDir, 'npm')
+    await mkdir(binDir, { recursive: true })
+    await writeFile(
+      npmBin,
+      `#!/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'
+if (process.argv[2] === 'view') {
+  setTimeout(() => {
+    process.stdout.write(JSON.stringify(version) + '\\n')
+  }, delay)
+} else {
+  process.exit(1)
+}
+`,
+      'utf8'
+    )
+    await chmod(npmBin, 0o755)
+    vi.stubEnv('PATH', [binDir, originalPath].filter(Boolean).join(path.delimiter))
+  }
+
+  const writeCachedPackage = async (packageName: string, version: string) => {
+    const sanitizedName = packageName.replace(/^@/, '').replace(/[\\/]/g, '__')
+    const packageDir = path.join(
+      tempDir,
+      '.oneworks/bootstrap/npm',
+      sanitizedName,
+      version,
+      'node_modules',
+      ...packageName.split('/')
+    )
+    await mkdir(packageDir, { recursive: true })
+    await writeFile(
+      path.join(packageDir, 'package.json'),
+      JSON.stringify({ name: packageName, version }),
+      'utf8'
+    )
+  }
+
+  it('uses the project npmrc as npm userconfig', async () => {
+    const projectNpmrc = path.join(process.cwd(), '.npmrc')
+    await writeFile(projectNpmrc, '@oneworks:registry=https://registry.npmjs.org/\n')
+
+    const env = resolvePackageManagerEnv()
+
+    expect(env.NPM_CONFIG_USERCONFIG).toBe(projectNpmrc)
+    expect(env.npm_config_userconfig).toBe(projectNpmrc)
+    expect(env.NPM_CONFIG_REPLACE_REGISTRY_HOST).toBe('never')
+    expect(env.npm_config_replace_registry_host).toBe('never')
+  })
+
+  it('keeps an explicit npm userconfig override', async () => {
+    const explicitUserConfig = path.join(tempDir, 'custom.npmrc')
+    await writeFile(path.join(tempDir, '.npmrc'), '@oneworks:registry=https://registry.npmjs.org/\n')
+    vi.stubEnv('NPM_CONFIG_USERCONFIG', explicitUserConfig)
+
+    const env = resolvePackageManagerEnv()
+
+    expect(env.NPM_CONFIG_USERCONFIG).toBe(explicitUserConfig)
+    expect(env.npm_config_userconfig).toBe(explicitUserConfig)
+  })
+
+  it('records fast npm view results for later launches', async () => {
+    await installFakeNpm()
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_CACHE_FIRST', '0')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '1.2.3')
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('1.2.3')
+
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '2.0.0')
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('2.0.0')
+  })
+
+  it('uses cached package versions without blocking on npm view by default', async () => {
+    await installFakeNpm()
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '1.2.3')
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('1.2.3')
+
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '9.9.9')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_DELAY_MS', '200')
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('1.2.3')
+  })
+
+  it('uses installed package cache before npm view when no metadata exists', async () => {
+    await writeCachedPackage('@scope/pkg', '4.5.6')
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('4.5.6')
+  })
+
+  it('uses cached package versions when npm view exceeds the startup budget in refresh-first mode', async () => {
+    await installFakeNpm()
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_CACHE_FIRST', '0')
+    vi.stubEnv('ONEWORKS_BOOTSTRAP_PACKAGE_LOOKUP_TIMEOUT_MS', '20')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '1.2.3')
+
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('1.2.3')
+
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_VERSION', '9.9.9')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_DELAY_MS', '200')
+    await expect(resolvePublishedPackageVersion('@scope/pkg')).resolves.toBe('1.2.3')
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('timed out after 20ms'))
+  })
+
+  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')
+    vi.stubEnv('ONEWORKS_TEST_NPM_VIEW_DELAY_MS', '50')
+
+    await expect(resolvePublishedPackageVersion('@scope/uncached')).resolves.toBe('3.0.0')
+  })
+})

package/__tests__/package-launcher.spec.ts

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { shouldResolveCliAdapterPackage } from '../src/package-launcher'
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe('bootstrap package launcher', () => {
+  it('resolves adapter packages when the loader only defaulted CLI package dir to bootstrap itself', () => {
+    vi.stubEnv('__ONEWORKS_PROJECT_PACKAGE_DIR__', '/runtime/bootstrap')
+    vi.stubEnv('__ONEWORKS_PROJECT_CLI_PACKAGE_DIR__', '/runtime/bootstrap')
+
+    expect(shouldResolveCliAdapterPackage()).toBe(true)
+  })
+
+  it('preserves an explicit external CLI package dir', () => {
+    vi.stubEnv('__ONEWORKS_PROJECT_PACKAGE_DIR__', '/runtime/bootstrap')
+    vi.stubEnv('__ONEWORKS_PROJECT_CLI_PACKAGE_DIR__', '/runtime/adapter-cache')
+
+    expect(shouldResolveCliAdapterPackage()).toBe(false)
+  })
+})