oneworks 0.0.0 → 0.1.0-alpha.0

package/src/npm-package.ts

@@ -0,0 +1,151 @@
+import { Buffer } from 'node:buffer'
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import process from 'node:process'
+
+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'
+
+export { resolvePackageManagerEnv } from './npm-package-cache'
+export { installPublishedPackage, resolvePackageBinEntrypoint } from './npm-package-install'
+
+const resolveRefreshWorkerEntrypoint = () => {
+  const requireFromHere = createRequire(import.meta.url)
+  const packageJsonPath = requireFromHere.resolve('oneworks/package.json')
+  return path.join(path.dirname(packageJsonPath), 'package-version-refresh-worker.cjs')
+}
+
+const spawnPackageVersionRefresh = (packageName: string) => {
+  if (process.env.ONEWORKS_BOOTSTRAP_DISABLE_BACKGROUND_REFRESH === '1') {
+    return
+  }
+
+  try {
+    const payload = Buffer.from(JSON.stringify({ packageName }), 'utf8').toString('base64url')
+    const child = spawn(
+      process.execPath,
+      [
+        resolveRefreshWorkerEntrypoint(),
+        payload
+      ],
+      {
+        cwd: process.cwd(),
+        detached: true,
+        env: resolvePackageManagerEnv(),
+        stdio: 'ignore'
+      }
+    )
+    child.unref()
+  } catch {
+    // Keep bootstrap startup independent from background metadata refresh.
+  }
+}
+
+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)
+  if (cachedMetadata != null && (options.cacheFirst ?? shouldUseCachedPackageVersionFirst())) {
+    spawnPackageVersionRefresh(packageName)
+    return cachedMetadata.version
+  }
+
+  const cachedInstalledVersion = await findInstalledPublishedPackageVersion(packageName)
+  if (cachedInstalledVersion != null && (options.cacheFirst ?? shouldUseCachedPackageVersionFirst())) {
+    spawnPackageVersionRefresh(packageName)
+    return cachedInstalledVersion
+  }
+
+  const registryResult = await resolvePublishedPackageVersionFromRegistry(
+    packageName,
+    cachedMetadata == null
+      ? {}
+      : {
+        timeoutMs: resolvePackageLookupTimeoutMs()
+      }
+  )
+
+  if ('version' in registryResult) {
+    await writePublishedPackageVersionMetadata(packageName, registryResult.version)
+    return registryResult.version
+  }
+
+  if (cachedMetadata == null) {
+    // This is not expected because uncached lookups do not use a timeout.
+    const retryResult = await resolvePublishedPackageVersionFromRegistry(packageName)
+    if ('version' in retryResult) {
+      await writePublishedPackageVersionMetadata(packageName, retryResult.version)
+      return retryResult.version
+    }
+    throw new Error(`Failed to resolve published version for ${retryResult.spec}.`)
+  }
+
+  console.error(
+    `[bootstrap] npm view ${registryResult.spec} timed out after ${resolvePackageLookupTimeoutMs()}ms, using cached ${packageName}@${cachedMetadata.version}`
+  )
+  spawnPackageVersionRefresh(packageName)
+  return cachedMetadata.version
+}

package/src/package-config.ts

@@ -0,0 +1,23 @@
+let packageJson: Record<string, unknown> | undefined
+
+const getPackageJson = () => {
+  if (!packageJson) {
+    try {
+      // eslint-disable-next-line ts/no-require-imports
+      packageJson = require('oneworks/package.json') as Record<string, unknown>
+    } catch {
+      packageJson = {}
+    }
+  }
+
+  return packageJson
+}
+
+export const getBootstrapPackageConfig = (key: string, defaultValue = '') => {
+  const value = getPackageJson()[key]
+  return typeof value === 'string' ? value : defaultValue
+}
+
+export const getBootstrapVersion = () => getBootstrapPackageConfig('version', '0.0.0')
+
+export const getBootstrapDescription = () => getBootstrapPackageConfig('description', 'One Works bootstrap launcher')

package/src/package-launcher.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+import { readCliAdapterPackageRequest, resolveCliAdapterPackageDir } from './adapter-package-cache'
+import { installPublishedPackage, resolvePackageBinEntrypoint, resolvePublishedPackageVersion } from './npm-package'
+import { resolvePackageCacheDir, resolvePackageInstallDir, sanitizePackageName } from './npm-package-cache'
+import { resolveBootstrapDataDir } from './paths'
+import { runNodeEntrypoint } from './process-utils'
+
+export interface LaunchInstalledPackageOptions {
+  commandName?: string
+  forwardedArgs: string[]
+  packageName: string
+}
+
+const normalizeRuntimePackageDir = (value: string | undefined) => {
+  const trimmed = value?.trim()
+  return trimmed == null || trimmed === '' ? undefined : path.resolve(trimmed)
+}
+
+export const shouldResolveCliAdapterPackage = () => {
+  const cliPackageDir = normalizeRuntimePackageDir(process.env.__ONEWORKS_PROJECT_CLI_PACKAGE_DIR__)
+  const packageDir = normalizeRuntimePackageDir(process.env.__ONEWORKS_PROJECT_PACKAGE_DIR__)
+  return cliPackageDir == null || cliPackageDir === packageDir
+}
+
+const readActivePackageVersion = (packageName: string) => {
+  try {
+    const metadataPath = path.join(
+      resolveBootstrapDataDir(),
+      'module-updates',
+      `${sanitizePackageName(packageName)}.json`
+    )
+    const parsed = JSON.parse(readFileSync(metadataPath, 'utf8')) as {
+      packageName?: unknown
+      version?: unknown
+    }
+    if (parsed.packageName !== packageName || typeof parsed.version !== 'string') {
+      return undefined
+    }
+
+    const packageDir = resolvePackageInstallDir(resolvePackageCacheDir(packageName, parsed.version), packageName)
+    const packageJson = JSON.parse(readFileSync(path.join(packageDir, 'package.json'), 'utf8')) as {
+      name?: unknown
+      version?: unknown
+    }
+    return packageJson.name === packageName && packageJson.version === parsed.version
+      ? parsed.version
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export const launchInstalledPackage = async (input: LaunchInstalledPackageOptions) => {
+  const version = readActivePackageVersion(input.packageName) ?? await resolvePublishedPackageVersion(input.packageName)
+  console.error(`[bootstrap] using ${input.packageName}@${version}`)
+  const installedPackage = await installPublishedPackage(input.packageName, version)
+  const entryPath = await resolvePackageBinEntrypoint(installedPackage.packageDir, input.commandName)
+  const adapterPackageRequest = input.packageName === '@oneworks/cli' &&
+      shouldResolveCliAdapterPackage()
+    ? readCliAdapterPackageRequest(
+      input.forwardedArgs,
+      version,
+      process.env.__ONEWORKS_RUNTIME_PROTOCOL_CONSUMER_ADAPTER__
+    )
+    : undefined
+  const adapterPackageDir = adapterPackageRequest == null
+    ? undefined
+    : await resolveCliAdapterPackageDir(adapterPackageRequest)
+
+  return await runNodeEntrypoint(
+    entryPath,
+    input.forwardedArgs,
+    adapterPackageDir == null
+      ? {}
+      : {
+        env: {
+          ...process.env,
+          __ONEWORKS_PROJECT_CLI_PACKAGE_DIR__: adapterPackageDir
+        }
+      }
+  )
+}

package/src/paths.ts

@@ -0,0 +1,19 @@
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+export const resolveRealHomeDir = () => {
+  const realHome = process.env.__ONEWORKS_PROJECT_REAL_HOME__?.trim()
+  if (realHome) {
+    return realHome
+  }
+
+  return os.homedir()
+}
+
+export const resolveBootstrapDataDir = () => path.join(resolveRealHomeDir(), '.oneworks', 'bootstrap')
+
+export const resolveBootstrapPackageCacheDir = () => {
+  const packageCacheDir = process.env.__ONEWORKS_PROJECT_PACKAGE_CACHE_DIR__?.trim()
+  return packageCacheDir || resolveBootstrapDataDir()
+}

package/src/process-utils.ts

@@ -0,0 +1,126 @@
+import type { Buffer } from 'node:buffer'
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+
+interface RunBufferedCommandOptions {
+  args: string[]
+  command: string
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  stdio?: 'ignore' | 'inherit' | 'pipe'
+  timeoutMs?: number
+}
+
+export const runBufferedCommand = async (input: RunBufferedCommandOptions) => {
+  const child = spawn(input.command, input.args, {
+    cwd: input.cwd,
+    env: input.env,
+    stdio: input.stdio ?? 'pipe'
+  })
+
+  let stdout = ''
+  let stderr = ''
+  let timedOut = false
+  let killTimeout: NodeJS.Timeout | undefined
+  const timeout = input.timeoutMs != null && input.timeoutMs > 0
+    ? setTimeout(() => {
+      timedOut = true
+      child.kill('SIGTERM')
+      killTimeout = setTimeout(() => {
+        if (child.exitCode == null && child.signalCode == null) {
+          child.kill('SIGKILL')
+        }
+      }, 1_000)
+      killTimeout.unref()
+    }, input.timeoutMs)
+    : undefined
+
+  if (input.stdio !== 'inherit') {
+    child.stdout?.on('data', (chunk: Buffer | string) => {
+      stdout += String(chunk)
+    })
+    child.stderr?.on('data', (chunk: Buffer | string) => {
+      stderr += String(chunk)
+    })
+  }
+
+  return await new Promise<{
+    code: number
+    stderr: string
+    timedOut?: boolean
+    stdout: string
+  }>((resolve, reject) => {
+    child.once('error', (error) => {
+      if (timeout != null) {
+        clearTimeout(timeout)
+      }
+      if (killTimeout != null) {
+        clearTimeout(killTimeout)
+      }
+      reject(error)
+    })
+    child.once('exit', (code) => {
+      if (timeout != null) {
+        clearTimeout(timeout)
+      }
+      if (killTimeout != null) {
+        clearTimeout(killTimeout)
+      }
+      resolve({
+        code: code ?? 0,
+        stderr,
+        timedOut,
+        stdout
+      })
+    })
+  })
+}
+
+export const runNodeEntrypoint = async (
+  entryPath: string,
+  forwardedArgs: string[],
+  options: { env?: NodeJS.ProcessEnv } = {}
+) => {
+  const child = spawn(process.execPath, [entryPath, ...forwardedArgs], {
+    cwd: process.cwd(),
+    env: options.env ?? process.env,
+    stdio: 'inherit'
+  })
+
+  const forwardSignal = (signal: NodeJS.Signals) => {
+    if (!child.killed) {
+      child.kill(signal)
+    }
+  }
+
+  const handleSigint = () => {
+    forwardSignal('SIGINT')
+  }
+
+  const handleSigterm = () => {
+    forwardSignal('SIGTERM')
+  }
+
+  const cleanup = () => {
+    process.off('SIGINT', handleSigint)
+    process.off('SIGTERM', handleSigterm)
+  }
+
+  process.on('SIGINT', handleSigint)
+  process.on('SIGTERM', handleSigterm)
+
+  return await new Promise<number>((resolve, reject) => {
+    child.once('error', (error) => {
+      cleanup()
+      reject(error)
+    })
+    child.once('exit', (code, signal) => {
+      cleanup()
+      if (signal != null) {
+        process.kill(process.pid, signal)
+        return
+      }
+      resolve(code ?? 0)
+    })
+  })
+}

package/src/program.ts

@@ -0,0 +1,286 @@
+/* eslint-disable max-lines -- bootstrap CLI command routing is intentionally centralized. */
+import { Command } from 'commander'
+import process from 'node:process'
+
+import { launchDesktopApp } from './desktop-app'
+import type { DesktopInstallMode, LaunchDesktopAppOptions } from './desktop-app'
+import { getBootstrapDescription, getBootstrapVersion } from './package-config'
+import { launchInstalledPackage } from './package-launcher'
+import { checkRuntimePackage, formatRuntimePackageStatus, installRuntimePackage } from './runtime-package'
+import type { RuntimePackageAction, RuntimePackageOptions, RuntimePackageStatus } from './runtime-package'
+
+interface BootstrapCliDeps {
+  checkRuntimePackage: (target?: string, options?: RuntimePackageOptions) => Promise<RuntimePackageStatus>
+  installRuntimePackage: (target?: string, options?: RuntimePackageOptions) => Promise<RuntimePackageStatus>
+  launchDesktopApp: (options: LaunchDesktopAppOptions) => Promise<void>
+  launchInstalledPackage: (input: {
+    commandName?: string
+    forwardedArgs: string[]
+    packageName: string
+  }) => Promise<number>
+}
+
+type BootstrapTarget =
+  | {
+    forwardedArgs: string[]
+    installMode?: DesktopInstallMode
+    kind: 'desktop'
+    persistInstallMode?: boolean
+  }
+  | {
+    commandName?: string
+    forwardedArgs: string[]
+    kind: 'package'
+    packageName: string
+  }
+  | {
+    action: RuntimePackageAction
+    json: boolean
+    kind: 'runtime-package'
+    target?: string
+    version?: string
+  }
+
+const DEFAULT_DEPS: BootstrapCliDeps = {
+  checkRuntimePackage,
+  installRuntimePackage,
+  launchDesktopApp,
+  launchInstalledPackage
+}
+
+const parseDesktopTarget = (args: string[]): BootstrapTarget => {
+  const forwardedArgs = [...args]
+  let installMode: DesktopInstallMode | undefined
+  let persistInstallMode = false
+
+  if (forwardedArgs[0] === 'cache') {
+    forwardedArgs.shift()
+    installMode = 'cache'
+    persistInstallMode = true
+  }
+
+  const noCacheIndex = forwardedArgs.indexOf('--no-cache')
+  if (noCacheIndex >= 0) {
+    forwardedArgs.splice(noCacheIndex, 1)
+    installMode = 'user'
+    persistInstallMode = true
+  }
+
+  return {
+    forwardedArgs,
+    installMode,
+    kind: 'desktop',
+    persistInstallMode
+  }
+}
+
+const parseRuntimePackageTarget = (args: string[]): BootstrapTarget => {
+  const forwardedArgs = [...args]
+  const jsonIndex = forwardedArgs.indexOf('--json')
+  const json = jsonIndex >= 0
+  if (json) {
+    forwardedArgs.splice(jsonIndex, 1)
+  }
+
+  const action = forwardedArgs.shift()
+  if (action !== 'check' && action !== 'install') {
+    throw new Error('Runtime package command must be `check` or `install`.')
+  }
+
+  let version: string | undefined
+  for (let index = 0; index < forwardedArgs.length; index += 1) {
+    const arg = forwardedArgs[index]
+    if (arg === '--version') {
+      const value = forwardedArgs[index + 1]
+      if (value == null || value.trim() === '') {
+        throw new Error('Runtime package --version requires a value.')
+      }
+      version = value
+      forwardedArgs.splice(index, 2)
+      index -= 1
+      continue
+    }
+
+    if (arg?.startsWith('--version=')) {
+      const value = arg.slice('--version='.length)
+      if (value.trim() === '') {
+        throw new Error('Runtime package --version requires a value.')
+      }
+      version = value
+      forwardedArgs.splice(index, 1)
+      index -= 1
+    }
+  }
+
+  const targetSelector = forwardedArgs.shift()
+  if (forwardedArgs.length > 0) {
+    throw new Error(`Unsupported runtime package arguments: ${forwardedArgs.join(' ')}`)
+  }
+
+  const selectorAtIndex = targetSelector?.lastIndexOf('@') ?? -1
+  const selectorTarget = selectorAtIndex > 0 ? targetSelector?.slice(0, selectorAtIndex) : targetSelector
+  const selectorVersion = selectorAtIndex > 0 ? targetSelector?.slice(selectorAtIndex + 1) : undefined
+  if (selectorVersion != null && selectorVersion.trim() === '') {
+    throw new Error(`Runtime package target selector requires a version: ${targetSelector}.`)
+  }
+  if (version != null && selectorVersion != null && version !== selectorVersion) {
+    throw new Error(`Conflicting runtime package versions: ${selectorVersion} and ${version}.`)
+  }
+  const resolvedVersion = version ?? selectorVersion
+
+  return {
+    action,
+    json,
+    kind: 'runtime-package',
+    target: selectorTarget,
+    ...(resolvedVersion != null ? { version: resolvedVersion } : {})
+  }
+}
+
+export const routeBootstrapCommand = (command: string | undefined, args: string[]): BootstrapTarget | undefined => {
+  if (command == null || command.trim() === '') {
+    return undefined
+  }
+
+  if (command === 'web') {
+    return {
+      commandName: 'oneworks-web',
+      forwardedArgs: args,
+      kind: 'package',
+      packageName: '@oneworks/web'
+    }
+  }
+
+  if (command === 'server') {
+    return {
+      commandName: 'oneworks-server',
+      forwardedArgs: args,
+      kind: 'package',
+      packageName: '@oneworks/server'
+    }
+  }
+
+  if (command === 'runtime') {
+    return parseRuntimePackageTarget(args)
+  }
+
+  if (command === 'app') {
+    return parseDesktopTarget(args)
+  }
+
+  if (command === 'cli') {
+    return {
+      commandName: 'oneworks',
+      forwardedArgs: args,
+      kind: 'package',
+      packageName: '@oneworks/cli'
+    }
+  }
+
+  return {
+    commandName: 'oneworks',
+    forwardedArgs: [command, ...args],
+    kind: 'package',
+    packageName: '@oneworks/cli'
+  }
+}
+
+export const createBootstrapCli = (inputDeps: Partial<BootstrapCliDeps> = {}) => {
+  const deps: BootstrapCliDeps = {
+    ...DEFAULT_DEPS,
+    ...inputDeps
+  }
+  const program = new Command()
+
+  program
+    .name('oneworks')
+    .description(getBootstrapDescription())
+    .helpOption(false)
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .argument('[command]', 'Reserved commands: web, server, app, cli')
+    .argument('[args...]', 'Forwarded arguments for the delegated runtime')
+    .showHelpAfterError()
+    .addHelpText(
+      'after',
+      `
+Top-level flags:
+  --help, -h     Show bootstrap help
+  --version, -V  Print bootstrap version
+
+Examples:
+  npx oneworks summarize the repo
+  npx oneworks web --port 8787
+  npx oneworks server --host 0.0.0.0 --allow-cors
+  npx oneworks runtime check cli
+  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 app
+  npx oneworks app cache
+  npx oneworks app --no-cache
+  cd ~/work/project-a && npx oneworks app
+  cd ~/work/project-b && npx oneworks app
+`
+    )
+    .action(async (command: string | undefined, args: string[] = []) => {
+      const target = routeBootstrapCommand(command, args)
+      if (target == null) {
+        program.outputHelp()
+        return
+      }
+
+      if (target.kind === 'desktop') {
+        await deps.launchDesktopApp({
+          forwardedArgs: target.forwardedArgs,
+          installMode: target.installMode,
+          persistInstallMode: target.persistInstallMode
+        })
+        return
+      }
+
+      if (target.kind === 'runtime-package') {
+        let status: RuntimePackageStatus
+        if (target.action === 'install') {
+          status = target.version == null
+            ? await deps.installRuntimePackage(target.target)
+            : await deps.installRuntimePackage(target.target, { version: target.version })
+        } else {
+          status = target.version == null
+            ? await deps.checkRuntimePackage(target.target)
+            : await deps.checkRuntimePackage(target.target, { version: target.version })
+        }
+        const output = target.json ? JSON.stringify(status) : formatRuntimePackageStatus(status)
+        process.stdout.write(`${output}\n`)
+        return
+      }
+
+      const exitCode = await deps.launchInstalledPackage({
+        packageName: target.packageName,
+        commandName: target.commandName,
+        forwardedArgs: target.forwardedArgs
+      })
+
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  return program
+}
+
+export const runBootstrapCli = async (argv = process.argv) => {
+  const command = createBootstrapCli()
+  const userArgs = argv.slice(2)
+  if (userArgs.length === 0 || (userArgs.length === 1 && ['-h', '--help'].includes(userArgs[0] ?? ''))) {
+    command.outputHelp()
+    return
+  }
+
+  if (userArgs.length === 1 && ['-V', '--version'].includes(userArgs[0] ?? '')) {
+    process.stdout.write(`${getBootstrapVersion()}\n`)
+    return
+  }
+
+  await command.parseAsync(argv)
+}