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

package/__tests__/cli.spec.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
+import bootstrapPackageJson from '../package.json'
+import { getBootstrapVersion } from '../src/package-config'
 import { createBootstrapCli, routeBootstrapCommand } from '../src/program'
 
 describe('bootstrap cli', () => {
@@ -67,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',
@@ -76,6 +95,10 @@ describe('bootstrap cli', () => {
     })
   })
 
+  it('reads the current bootstrap package version', () => {
+    expect(getBootstrapVersion()).toBe(bootstrapPackageJson.version)
+  })
+
   it('dispatches the desktop launcher for app', async () => {
     const launchDesktopApp = vi.fn(async () => {})
     const launchInstalledPackage = vi.fn(async () => 0)
@@ -191,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__/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.1",
+  "version": "0.1.0-beta.0",
+  "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.0"
   },
   "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) => (

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
 }
@@ -63,12 +66,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 +86,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 +112,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 +124,7 @@ export const installPublishedPackage = async (packageName: string, version: stri
   }
 
   return {
+    cacheVersion,
     packageDir: resolvePackageInstallDir(cacheDir, packageName),
     version
   }

package/src/package-config.ts

@@ -4,7 +4,7 @@ const getPackageJson = () => {
   if (!packageJson) {
     try {
       // eslint-disable-next-line ts/no-require-imports
-      packageJson = require('oneworks/package.json') as Record<string, unknown>
+      packageJson = require('../package.json') as Record<string, unknown>
     } catch {
       packageJson = {}
     }

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}`