@shawnstack/quickforge 1.7.4 → 1.7.5

package/server/cloud/identity.mjs

@@ -0,0 +1,355 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { CloudApiError } from './client.mjs'
+
+const SESSION_INVALID_CODES = new Set(['refresh_token_reused', 'installation_revoked', 'invalid_refresh_token'])
+const DEVICE_PENDING_CODES = new Set(['authorization_pending', 'pending'])
+const DEVICE_SLOW_DOWN_CODES = new Set(['slow_down'])
+const DEVICE_DENIED_CODES = new Set(['access_denied', 'authorization_declined', 'denied'])
+const DEVICE_EXPIRED_CODES = new Set(['expired_token', 'device_code_expired', 'expired'])
+const DEVICE_NETWORK_CODES = new Set(['cloud_unavailable', 'service_unavailable', 'temporarily_unavailable'])
+const DEVICE_NETWORK_CAUSE_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENETDOWN', 'ENETUNREACH', 'EHOSTUNREACH', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_SOCKET'])
+const DEVICE_CLIENT_ID = 'quickforge-desktop'
+const MODEL_CACHE_TTL_MS = 60_000
+const MODEL_CACHE_HARD_TTL_MS = 5 * 60_000
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+function tokenExpiry(expiresIn) {
+  const seconds = Number(expiresIn)
+  return Date.now() + Math.max(1, Number.isFinite(seconds) ? seconds : 300) * 1000
+}
+
+function publicAccountSummary(value) {
+  if (!value || typeof value !== 'object') return undefined
+  const summary = {}
+  for (const field of ['id', 'email', 'plan']) {
+    const candidate = value[field]
+    if (typeof candidate === 'string' && candidate) summary[field] = candidate
+  }
+  return Object.keys(summary).length ? summary : undefined
+}
+
+function isDeviceFlowNetworkError(error) {
+  if (error instanceof CloudApiError) {
+    return error.retryable === true
+      || error.status >= 500
+      || DEVICE_NETWORK_CODES.has(error.code)
+  }
+  const causeCode = error?.cause?.code || error?.code
+  return error instanceof TypeError || DEVICE_NETWORK_CAUSE_CODES.has(causeCode)
+}
+
+function registrationHash(record, serviceUrl) {
+  return createHash('sha256').update(JSON.stringify({
+    installationName: record.installationName,
+    platform: record.platform,
+    clientVersion: record.clientVersion,
+    publicKey: record.publicKey,
+    serviceUrl,
+  })).digest('base64url')
+}
+
+export class CloudIdentityManager {
+  constructor({ client, store, serviceUrl } = {}) {
+    if (!client || !store) throw new Error('CloudIdentityManager requires client and store.')
+    this.client = client
+    this.store = store
+    this.serviceUrl = String(serviceUrl || client.baseUrl?.href || '')
+    if (!this.serviceUrl) throw new Error('CloudIdentityManager requires a service URL.')
+    this.accessToken = undefined
+    this.accessExpiresAt = 0
+    this.refreshPromise = undefined
+    this.devicePollPromise = undefined
+    this.modelsCache = undefined
+    this.modelsCachedAt = 0
+    this.modelsPromise = undefined
+  }
+
+  async status() {
+    let record = await this.store.read()
+    if (record.pendingDeviceFlow && Number(record.pendingDeviceFlow.expiresAt) <= Date.now()) {
+      record = await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+    }
+    const publicStatus = await this.store.readPublic()
+    const sessionServiceMismatch = Boolean(record.refreshToken && record.sessionCloudUrl !== this.serviceUrl)
+    const pendingServiceMismatch = Boolean(record.pendingDeviceFlow && record.pendingDeviceFlow.sessionCloudUrl !== this.serviceUrl)
+    return (sessionServiceMismatch || pendingServiceMismatch)
+      ? { ...publicStatus, sessionServiceMismatch: true }
+      : publicStatus
+  }
+
+  assertSessionService(record) {
+    if (record.refreshToken && record.sessionCloudUrl !== this.serviceUrl) {
+      throw new CloudApiError('The saved QuickForge Cloud session belongs to a different or unknown service. Rebuild the local Cloud identity before continuing.', {
+        status: 409,
+        code: 'cloud_session_service_mismatch',
+      })
+    }
+    if (record.pendingDeviceFlow && record.pendingDeviceFlow.sessionCloudUrl !== this.serviceUrl) {
+      throw new CloudApiError('The pending QuickForge Cloud sign-in belongs to a different service. Cancel or rebuild the local Cloud identity before continuing.', {
+        status: 409,
+        code: 'cloud_session_service_mismatch',
+      })
+    }
+  }
+
+  async startGuest({ signal } = {}) {
+    let record = await this.store.read()
+    this.assertSessionService(record)
+    if (record.rotateInstallationBeforeRegistration) {
+      record = await this.store.rotateInstallation()
+    } else {
+      record = await this.store.ensureInstallation()
+    }
+    const requestHash = registrationHash(record, this.serviceUrl)
+    let idempotencyKey = record.pendingRegistrationKey
+    if (!UUID_PATTERN.test(idempotencyKey || '') || record.pendingRegistrationHash !== requestHash) {
+      idempotencyKey = randomUUID()
+      await this.store.update((current) => ({
+        ...current,
+        pendingRegistrationKey: idempotencyKey,
+        pendingRegistrationHash: requestHash,
+      }))
+    }
+
+    const tokens = await this.client.registerGuest({
+      installationName: record.installationName,
+      platform: record.platform,
+      clientVersion: record.clientVersion,
+      publicKey: record.publicKey,
+    }, idempotencyKey, signal)
+
+    this.setAccess(tokens)
+    await this.store.update((current) => ({
+      ...current,
+      mode: tokens.identityMode || 'guest',
+      installationId: tokens.installationId,
+      refreshToken: tokens.refreshToken,
+      sessionCloudUrl: this.serviceUrl,
+      pendingRegistrationKey: undefined,
+      pendingRegistrationHash: undefined,
+      pendingDeviceFlow: undefined,
+    }))
+    return this.getStatusWithRemoteSummary(signal)
+  }
+
+  async startDeviceFlow({ signal } = {}) {
+    let record = await this.store.read()
+    this.assertSessionService(record)
+    if (record.mode === 'account' && record.refreshToken) {
+      throw new CloudApiError('QuickForge Cloud is already connected to an account.', { status: 409, code: 'cloud_account_already_connected' })
+    }
+    if (record.mode === 'local') {
+      await this.startGuest({ signal })
+      record = await this.store.read()
+    }
+    if (!record.refreshToken || !record.installationId) {
+      throw new CloudApiError('QuickForge Cloud guest session is required before account sign-in.', { status: 409, code: 'cloud_not_connected' })
+    }
+    this.assertSessionService(record)
+    const accessToken = await this.access({ signal })
+    const authorization = await this.client.authorizeDevice(accessToken, record.installationId, DEVICE_CLIENT_ID, signal)
+    const expiresIn = Math.max(1, Number(authorization?.expiresIn) || 600)
+    const interval = Math.max(1, Number(authorization?.interval) || 5)
+    const pendingDeviceFlow = {
+      deviceCode: String(authorization?.deviceCode || ''),
+      userCode: String(authorization?.userCode || ''),
+      verificationUri: String(authorization?.verificationUri || ''),
+      verificationUriComplete: String(authorization?.verificationUriComplete || ''),
+      expiresAt: Date.now() + expiresIn * 1000,
+      interval,
+      status: 'pending',
+      sessionCloudUrl: this.serviceUrl,
+    }
+    if (!pendingDeviceFlow.deviceCode || !pendingDeviceFlow.userCode || !pendingDeviceFlow.verificationUri) {
+      throw new CloudApiError('QuickForge Cloud returned an invalid device authorization response.', { code: 'invalid_device_authorization_response' })
+    }
+    await this.store.update((current) => ({ ...current, pendingDeviceFlow }))
+    return this.status()
+  }
+
+  async pollDeviceFlow(options = {}) {
+    if (this.devicePollPromise) return this.devicePollPromise
+    this.devicePollPromise = this.pollDeviceFlowOnce(options)
+      .finally(() => { this.devicePollPromise = undefined })
+    return this.devicePollPromise
+  }
+
+  async pollDeviceFlowOnce({ signal } = {}) {
+    const record = await this.store.read()
+    this.assertSessionService(record)
+    const pending = record.pendingDeviceFlow
+    if (!pending?.deviceCode) {
+      throw new CloudApiError('There is no pending QuickForge Cloud sign-in.', { status: 409, code: 'cloud_device_flow_not_pending' })
+    }
+    if (Number(pending.expiresAt) <= Date.now()) {
+      await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+      return { ...(await this.status()), deviceFlowResult: 'expired' }
+    }
+    try {
+      const tokens = await this.client.exchangeDeviceCode(pending.deviceCode, DEVICE_CLIENT_ID, signal)
+      if (!tokens?.refreshToken || !tokens?.accessToken) {
+        throw new CloudApiError('QuickForge Cloud returned an invalid account token response.', { code: 'invalid_token_response' })
+      }
+      this.setAccess(tokens)
+      this.modelsCache = undefined
+      this.modelsCachedAt = 0
+      this.modelsPromise = undefined
+      await this.store.update((current) => ({
+        ...current,
+        mode: 'account',
+        installationId: tokens.installationId || current.installationId,
+        refreshToken: tokens.refreshToken,
+        sessionCloudUrl: this.serviceUrl,
+        pendingDeviceFlow: undefined,
+        account: undefined,
+      }))
+      return { ...(await this.getStatusWithRemoteSummary(signal)), deviceFlowResult: 'success' }
+    } catch (error) {
+      if (DEVICE_PENDING_CODES.has(error?.code)) return { ...(await this.status()), deviceFlowResult: 'pending' }
+      if (DEVICE_SLOW_DOWN_CODES.has(error?.code)) {
+        await this.store.update((current) => ({
+          ...current,
+          pendingDeviceFlow: current.pendingDeviceFlow
+            ? { ...current.pendingDeviceFlow, interval: Math.max(1, Number(current.pendingDeviceFlow.interval) || 5) + 5, status: 'slow_down' }
+            : undefined,
+        }))
+        return { ...(await this.status()), deviceFlowResult: 'slow_down' }
+      }
+      if (DEVICE_DENIED_CODES.has(error?.code) || DEVICE_EXPIRED_CODES.has(error?.code)) {
+        await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+        return { ...(await this.status()), deviceFlowResult: DEVICE_DENIED_CODES.has(error?.code) ? 'denied' : 'expired' }
+      }
+      if (isDeviceFlowNetworkError(error)) {
+        return { ...(await this.status()), deviceFlowResult: 'network' }
+      }
+      throw error
+    }
+  }
+
+  async cancelDeviceFlow() {
+    const record = await this.store.read()
+    this.assertSessionService(record)
+    await this.store.update((current) => ({ ...current, pendingDeviceFlow: undefined }))
+    return this.status()
+  }
+
+  setAccess(tokens) {
+    this.accessToken = tokens?.accessToken
+    this.accessExpiresAt = tokenExpiry(tokens?.expiresIn)
+  }
+
+  async clearInvalidSession({ rotateInstallationBeforeRegistration = false } = {}) {
+    this.clearMemory()
+    await this.store.clearSession({ rotateInstallationBeforeRegistration })
+  }
+
+  clearMemory() {
+    this.accessToken = undefined
+    this.accessExpiresAt = 0
+    this.refreshPromise = undefined
+    this.devicePollPromise = undefined
+    this.modelsCache = undefined
+    this.modelsCachedAt = 0
+    this.modelsPromise = undefined
+  }
+
+  async resetIdentity() {
+    this.clearMemory()
+    await this.store.rotateInstallation()
+  }
+
+  async refresh({ signal } = {}) {
+    if (this.refreshPromise) return this.refreshPromise
+    this.refreshPromise = (async () => {
+      const record = await this.store.read()
+      if (!record.refreshToken) throw new CloudApiError('QuickForge Cloud is not connected.', { status: 401, code: 'cloud_not_connected' })
+      this.assertSessionService(record)
+      try {
+        const tokens = await this.client.refresh(record.refreshToken, signal)
+        if (!tokens?.refreshToken) throw new CloudApiError('QuickForge Cloud did not rotate the refresh token.', { code: 'invalid_token_response' })
+        this.setAccess(tokens)
+        await this.store.update((current) => ({
+          ...current,
+          mode: tokens.identityMode || current.mode || 'guest',
+          installationId: tokens.installationId || current.installationId,
+          refreshToken: tokens.refreshToken,
+          sessionCloudUrl: this.serviceUrl,
+        }))
+        return this.accessToken
+      } catch (error) {
+        if (SESSION_INVALID_CODES.has(error?.code)) {
+          await this.clearInvalidSession({ rotateInstallationBeforeRegistration: true })
+        }
+        throw error
+      }
+    })().finally(() => { this.refreshPromise = undefined })
+    return this.refreshPromise
+  }
+
+  async access({ signal, forceRefresh = false } = {}) {
+    if (!forceRefresh && this.accessToken && this.accessExpiresAt > Date.now() + 30_000) return this.accessToken
+    return this.refresh({ signal })
+  }
+
+  async withAccessToken(operation, { signal } = {}) {
+    let token = await this.access({ signal })
+    try {
+      return await operation(token)
+    } catch (error) {
+      if (!(error instanceof CloudApiError) || error.status !== 401) throw error
+      token = await this.access({ signal, forceRefresh: true })
+      return operation(token)
+    }
+  }
+
+  async getStatusWithRemoteSummary(signal) {
+    const local = await this.status()
+    if (!local.hasSession) return local
+    try {
+      const [remoteAccount, usage] = await Promise.all([this.me(signal), this.usage(signal)])
+      const account = publicAccountSummary(remoteAccount)
+      await this.store.update((record) => ({ ...record, account }))
+      return { ...(await this.status()), account, usage, cloudAvailable: true }
+    } catch (error) {
+      return { ...local, cloudAvailable: false, cloudError: error?.code || 'cloud_unavailable' }
+    }
+  }
+
+  me(signal) { return this.withAccessToken((token) => this.client.me(token, signal), { signal }) }
+  usage(signal) { return this.withAccessToken((token) => this.client.usage(token, signal), { signal }) }
+  installations(signal) { return this.withAccessToken((token) => this.client.installations(token, signal), { signal }) }
+  revokeInstallation(id, signal) {
+    return this.withAccessToken((token) => this.client.revokeInstallation(token, id, signal), { signal })
+  }
+  async logout({ signal } = {}) {
+    const record = await this.store.read()
+    if (!record.refreshToken || !record.installationId) {
+      await this.clearInvalidSession()
+      return
+    }
+    this.assertSessionService(record)
+    await this.revokeInstallation(record.installationId, signal)
+    this.clearMemory()
+    await this.store.clearSession({ rotateInstallationBeforeRegistration: true })
+  }
+  async models(signal, { refresh = false, allowStale = true } = {}) {
+    const age = Date.now() - this.modelsCachedAt
+    if (!refresh && this.modelsCache && age < MODEL_CACHE_TTL_MS) return this.modelsCache
+    if (this.modelsPromise) return this.modelsPromise
+    this.modelsPromise = this.withAccessToken((token) => this.client.models(token, signal), { signal })
+      .then((response) => {
+        this.modelsCache = Array.isArray(response?.items) ? response.items : []
+        this.modelsCachedAt = Date.now()
+        return this.modelsCache
+      })
+      .catch((error) => {
+        if (allowStale && this.modelsCache && age < MODEL_CACHE_HARD_TTL_MS) return this.modelsCache
+        throw error
+      })
+      .finally(() => { this.modelsPromise = undefined })
+    return this.modelsPromise
+  }
+  chat(payload, idempotencyKey, signal) {
+    return this.withAccessToken((token) => this.client.chat(token, payload, idempotencyKey, signal), { signal })
+  }
+}

package/server/cloud/index.mjs

@@ -0,0 +1,7 @@
+export { readCloudConfig, parseCloudBaseUrl, cloudEndpoint } from './config.mjs'
+export { readCloudServiceConfig, saveCloudServiceConfig, publicCloudServiceConfig, DEFAULT_CLOUD_URL } from './service-config.mjs'
+export { CloudClient, CloudApiError } from './client.mjs'
+export { createCloudCredentialStore, publicCloudCredentialRecord } from './credential-store.mjs'
+export { CloudIdentityManager } from './identity.mjs'
+export { ManagedCloudModels, isManagedCloudModel, toPublicCloudModel, QUICKFORGE_CLOUD_PROVIDER } from './models.mjs'
+export { createCloudRuntime, getCloudRuntime, invalidateCloudRuntime, resolveManagedCloudProvider } from './runtime.mjs'

package/server/cloud/models.mjs

@@ -0,0 +1,80 @@
+import { randomUUID } from 'node:crypto'
+
+const CLOUD_PROVIDER = 'quickforge-cloud'
+const CLOUD_SOURCE = 'cloud'
+
+export function toPublicCloudModel(model) {
+  const id = String(model?.id || '').trim()
+  if (!id) throw new Error('Cloud model is missing an id.')
+  const capabilities = model.capabilities || {}
+  return {
+    id,
+    name: String(model.name || id),
+    provider: CLOUD_PROVIDER,
+    api: 'openai-completions',
+    baseUrl: `quickforge://cloud/${encodeURIComponent(id)}`,
+    reasoning: Boolean(capabilities.reasoning),
+    input: capabilities.vision ? ['text', 'image'] : ['text'],
+    contextWindow: Number(model.contextWindow || 128_000),
+    maxTokens: Number(model.maxTokens || 8_192),
+    quickforgeModelSource: CLOUD_SOURCE,
+    quickforgeCatalogId: id,
+    quickforgeCapabilities: {
+      tools: Boolean(capabilities.tools),
+      vision: Boolean(capabilities.vision),
+      reasoning: Boolean(capabilities.reasoning),
+    },
+  }
+}
+
+export function isManagedCloudModel(model) {
+  return model?.provider === CLOUD_PROVIDER && model?.quickforgeModelSource === CLOUD_SOURCE && typeof model?.quickforgeCatalogId === 'string'
+}
+
+export class ManagedCloudModels {
+  constructor({ identity } = {}) {
+    if (!identity) throw new Error('ManagedCloudModels requires an identity manager.')
+    this.identity = identity
+  }
+
+  async list(signal, options) {
+    return (await this.identity.models(signal, options))
+      .filter((model) => model?.available !== false)
+      .map(toPublicCloudModel)
+  }
+
+  async resolve(model, signal) {
+    if (!isManagedCloudModel(model)) return undefined
+    const catalogId = model.quickforgeCatalogId
+    let available = await this.identity.models(signal)
+    let entry = available.find((item) => item?.id === catalogId && item?.available !== false)
+    if (!entry) {
+      available = await this.identity.models(signal, { refresh: true, allowStale: false })
+      entry = available.find((item) => item?.id === catalogId && item?.available !== false)
+    }
+    if (!entry) {
+      const error = new Error(`QuickForge Cloud model is unavailable: ${catalogId}`)
+      error.code = 'cloud_model_unavailable'
+      throw error
+    }
+    return {
+      publicModel: toPublicCloudModel(entry),
+      catalogId,
+    }
+  }
+
+  async chat(model, payload, signal) {
+    const resolved = await this.resolve(model, signal)
+    if (!resolved) throw new Error('Model is not managed by QuickForge Cloud.')
+    const request = {
+      ...payload,
+      model: resolved.catalogId,
+    }
+    delete request.baseUrl
+    delete request.headers
+    delete request.apiKey
+    return this.identity.chat(request, randomUUID(), signal)
+  }
+}
+
+export const QUICKFORGE_CLOUD_PROVIDER = CLOUD_PROVIDER

package/server/cloud/runtime.mjs

@@ -0,0 +1,129 @@
+import { CloudClient } from './client.mjs'
+import { readCloudConfig, cloudEndpoint } from './config.mjs'
+import { createCloudCredentialStore } from './credential-store.mjs'
+import { CloudIdentityManager } from './identity.mjs'
+import { ManagedCloudModels, isManagedCloudModel } from './models.mjs'
+import { readCloudServiceConfig } from './service-config.mjs'
+
+let singleton
+let singletonKey
+let singletonPromise
+let runtimeOverride = false
+let runtimeGeneration = 0
+let runtimeFactory = createCloudRuntime
+
+function runtimeKey(config, generation = runtimeGeneration) {
+  return `${generation}:${config?.baseUrl?.href || ''}:${config?.timeoutMs || ''}`
+}
+
+export function createCloudRuntime({ config = readCloudConfig(), store, client } = {}) {
+  if (!config?.enabled) return { enabled: false, config }
+  const credentialStore = store || createCloudCredentialStore({ clientVersion: process.env.npm_package_version || 'unknown' })
+  const cloudClient = client || new CloudClient(config)
+  const identity = new CloudIdentityManager({ client: cloudClient, store: credentialStore, serviceUrl: config.baseUrl.href })
+  const models = new ManagedCloudModels({ identity })
+  return { enabled: true, config, store: credentialStore, client: cloudClient, identity, models }
+}
+
+async function resolvedRuntimeConfig() {
+  const service = await readCloudServiceConfig()
+  const timeoutValue = Number(process.env.QUICKFORGE_CLOUD_TIMEOUT_MS || 10_000)
+  return {
+    enabled: Boolean(service.baseUrl),
+    baseUrl: service.baseUrl,
+    cloudUrl: service.cloudUrl,
+    source: service.source,
+    saved: service.saved,
+    timeoutMs: Number.isFinite(timeoutValue) ? Math.min(60_000, Math.max(1_000, timeoutValue)) : 10_000,
+  }
+}
+
+export async function getCloudRuntime() {
+  if (runtimeOverride) return singleton
+  const generation = runtimeGeneration
+  const config = await resolvedRuntimeConfig()
+  if (runtimeOverride) return singleton
+  if (generation !== runtimeGeneration) return getCloudRuntime()
+  const key = runtimeKey(config, generation)
+  if (singleton && singletonKey === key) return singleton
+  if (singletonPromise && singletonKey === key) return singletonPromise
+  singletonKey = key
+  const promise = Promise.resolve(runtimeFactory({ config })).then((runtime) => {
+    if (
+      !runtimeOverride
+      && generation === runtimeGeneration
+      && singletonKey === key
+      && singletonPromise === promise
+    ) {
+      singleton = runtime
+    }
+    return runtime
+  }).finally(() => {
+    if (singletonPromise === promise) singletonPromise = undefined
+  })
+  singletonPromise = promise
+  return promise
+}
+
+export function invalidateCloudRuntime() {
+  runtimeGeneration++
+  runtimeOverride = false
+  singleton = undefined
+  singletonKey = undefined
+  singletonPromise = undefined
+}
+
+export async function resolveManagedCloudProvider(model, signal) {
+  if (!isManagedCloudModel(model)) return undefined
+  const runtime = await getCloudRuntime()
+  if (!runtime.enabled) throw new Error('QuickForge Cloud is not configured.')
+  const resolved = await runtime.models.resolve(model, signal)
+  const accessToken = await runtime.identity.access({ signal })
+  return {
+    model: {
+      ...resolved.publicModel,
+      id: resolved.catalogId,
+      name: resolved.publicModel.name || resolved.catalogId,
+      provider: 'quickforge-cloud',
+      api: 'openai-completions',
+      baseUrl: cloudEndpoint(runtime.config.baseUrl, 'v1/').href.replace(/\/$/, ''),
+      headers: undefined,
+      // The Cloud gateway implements the conservative OpenAI-compatible request
+      // shape. Disable newer OpenAI-only fields that strict gateways may reject.
+      compat: {
+        supportsStore: false,
+        supportsDeveloperRole: false,
+        supportsReasoningEffort: false,
+        supportsUsageInStreaming: false,
+        supportsStrictMode: false,
+        maxTokensField: 'max_tokens',
+      },
+      // The cloud catalog does not carry per-model USD prices (billing is done
+      // server-side in credits). pi-ai's calculateCost() reads model.cost.*
+      // unconditionally, so provide a zero cost table to avoid throwing when
+      // parsing streamed usage chunks.
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    },
+    apiKey: accessToken,
+  }
+}
+
+export function resetCloudRuntimeForTests() {
+  runtimeGeneration = 0
+  runtimeOverride = false
+  runtimeFactory = createCloudRuntime
+  singleton = undefined
+  singletonKey = undefined
+  singletonPromise = undefined
+}
+
+export function setCloudRuntimeFactoryForTests(factory) {
+  runtimeFactory = factory
+}
+
+export function setCloudRuntimeForTests(runtime) {
+  runtimeOverride = true
+  singleton = runtime
+  singletonKey = runtimeKey(runtime?.config)
+  singletonPromise = undefined
+}

package/server/cloud/service-config.mjs

@@ -0,0 +1,77 @@
+import { atomicUpdate, readStore } from '../storage.mjs'
+import { parseCloudBaseUrl } from './config.mjs'
+
+export const CLOUD_SERVICE_SETTINGS_KEY = 'quickforge-cloud-service'
+export const CLOUD_SERVICE_SCHEMA_VERSION = 1
+export const CLOUD_SERVICE_TYPE = 'quickforge-cloud'
+export const DEFAULT_CLOUD_URL = 'http://127.0.0.1:8082/'
+
+function savedServiceRecord(settings) {
+  const value = settings?.[CLOUD_SERVICE_SETTINGS_KEY]
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined
+}
+
+function candidateFrom(settings, env) {
+  const saved = savedServiceRecord(settings)
+  if (saved && typeof saved.cloudUrl === 'string' && saved.cloudUrl.trim()) {
+    return { value: saved.cloudUrl, source: 'saved', saved: true }
+  }
+  if (typeof env?.QUICKFORGE_CLOUD_URL === 'string' && env.QUICKFORGE_CLOUD_URL.trim()) {
+    return { value: env.QUICKFORGE_CLOUD_URL, source: 'env', saved: false }
+  }
+  return { value: DEFAULT_CLOUD_URL, source: 'default', saved: false }
+}
+
+export async function readCloudServiceConfig({ readSettings = readStore, env = process.env, strict = true } = {}) {
+  const settings = await readSettings('settings')
+  const candidate = candidateFrom(settings, env)
+  try {
+    const baseUrl = parseCloudBaseUrl(candidate.value)
+    return {
+      schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+      serviceType: CLOUD_SERVICE_TYPE,
+      cloudUrl: baseUrl.href,
+      baseUrl,
+      source: candidate.source,
+      saved: candidate.saved,
+      valid: true,
+    }
+  } catch (error) {
+    if (strict) throw error
+    return {
+      schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+      serviceType: CLOUD_SERVICE_TYPE,
+      cloudUrl: String(candidate.value || '').trim(),
+      source: candidate.source,
+      saved: candidate.saved,
+      valid: false,
+      configurationError: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export async function saveCloudServiceConfig(cloudUrl, { updateSettings = atomicUpdate } = {}) {
+  const baseUrl = parseCloudBaseUrl(cloudUrl)
+  const record = {
+    schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+    serviceType: CLOUD_SERVICE_TYPE,
+    cloudUrl: baseUrl.href,
+  }
+  await updateSettings('settings', (settings) => ({
+    ...settings,
+    [CLOUD_SERVICE_SETTINGS_KEY]: record,
+  }))
+  return record
+}
+
+export function publicCloudServiceConfig(config) {
+  return {
+    schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+    serviceType: CLOUD_SERVICE_TYPE,
+    cloudUrl: config.cloudUrl,
+    source: config.source,
+    saved: config.saved,
+    valid: config.valid,
+    configurationError: config.configurationError,
+  }
+}