const match = STABLE_VERSION_PATTERN.exec(version)

if (!match) return null

const parsed = [Number(match[1]), Number(match[2]), Number(match[3])] as const

return parsed.every(Number.isSafeInteger) ? parsed : null

if (candidate[0] !== current[0]) return candidate[0] > current[0]

if (candidate[1] !== current[1]) return candidate[1] > current[1]

return candidate[2] > current[2]

/** Unknown cache versions are treated as absent. */

version: 1

checkedAt: string

/** Current working directory. Injected so project-local installation detection is testable. */

cwd?: string

currentVersion?: string

env?: NodeJS.ProcessEnv

/** Whether stderr is a terminal. Injected so the suppression rule is testable. */

isTty?: boolean

/** Location of the running module, used to recognise npx and local builds. */

modulePath?: string

now?: Date

/** Registry transport. Injectable so network behavior can be tested without global state. */

registryRequest?: RegistryRequest

write?: (message: string) => void

headers: Record<string, string>

maxResponseBytes: number

timeoutMs: number

const normalizedModulePath = normalizeModulePath(modulePath)

const nodeModulesIndex = normalizedModulePath.indexOf('/node_modules/')

if (nodeModulesIndex < 0) return false

const installRoot = normalizedModulePath.slice(0, nodeModulesIndex)

const workingDirectory = normalizeModulePath(cwd).replace(/\/+$/, '')

return workingDirectory === installRoot || workingDirectory.startsWith(`${installRoot}/`)

const normalized = normalizeModulePath(modulePath)

return (

env.npm_command === 'exec' ||

normalized.includes('/_npx/') ||

normalized.includes('/packages/sim-cli/') ||

isProjectLocalInstall(modulePath, cwd)

)

const fallback = new URL(DIST_TAGS_PATH, DEFAULT_REGISTRY)

const configured = env.npm_config_registry?.trim()

if (!configured) return fallback

try {

const base = new URL(configured)

if (base.protocol !== 'http:' && base.protocol !== 'https:') return null

if (base.username || base.password) return null

base.pathname = `${base.pathname.replace(/\/$/, '')}/${DIST_TAGS_PATH}`

return base

} catch {

return null

}

url: URL,

{ headers, maxResponseBytes, timeoutMs }: RegistryRequestOptions

): Promise<string | null> {

return new Promise((resolve, reject) => {

const child = spawn(

process.execPath,

[...proxyExecArgv(), '--input-type=module', '--eval', REGISTRY_REQUEST_SCRIPT],

{

env: childProcessEnv(['npm_config_registry', 'sim_api_key']),

killSignal: 'SIGKILL',

stdio: ['pipe', 'pipe', 'ignore'],

timeout: timeoutMs,

windowsHide: true,

}

)

const chunks: Buffer[] = []

let failed = false

let seen = 0

child.stdout.on('data', (chunk: Buffer) => {

seen += chunk.byteLength

if (seen > maxResponseBytes) {

failed = true

child.kill('SIGKILL')

return

}

chunks.push(chunk)

})

child.stdout.on('error', () => {

failed = true

child.kill('SIGKILL')

})

child.stdin.on('error', () => {})

child.once('error', reject)

child.once('close', (code) => {

resolve(code === 0 && !failed ? Buffer.concat(chunks).toString('utf8') : null)

})

child.stdin.end(JSON.stringify({ headers, maxResponseBytes, timeoutMs, url: url.href }))

})

env: NodeJS.ProcessEnv,

request: RegistryRequest

): Promise<Record<string, string> | null> {

try {

const url = registryUrl(env)

if (!url) return null

const text = await request(url, {

headers: { accept: 'application/json', 'user-agent': `${PACKAGE_NAME}-cli/${cliVersion()}` },

maxResponseBytes: MAX_RESPONSE_BYTES,

timeoutMs: REGISTRY_TIMEOUT_MS,

})

if (text === null || Buffer.byteLength(text) > MAX_RESPONSE_BYTES) return null

const body: unknown = JSON.parse(text)

if (typeof body !== 'object' || body === null || Array.isArray(body)) return null

const tags: Record<string, string> = {}

for (const [tag, version] of Object.entries(body)) {

if (typeof version === 'string') tags[tag] = version

}

return tags

} catch {

return null

}

const parsed = readJsonFile(path, MAX_CACHE_BYTES)

if (typeof parsed !== 'object' || parsed === null) return null

const entry = parsed as Partial<UpdateCacheEntry>

if (entry.version !== CACHE_VERSION) return null

if (typeof entry.checkedAt !== 'string' || Number.isNaN(Date.parse(entry.checkedAt))) return null

return { version: CACHE_VERSION, checkedAt: entry.checkedAt }

modulePath: string = fileURLToPath(import.meta.url),

env: NodeJS.ProcessEnv = process.env

): string {

const target = `${PACKAGE_NAME}@latest`

const normalized = normalizeModulePath(modulePath)

if (normalized.includes('.bun/install/global')) return `bun add -g ${target}`

if (normalized.includes('/pnpm/') || normalized.includes('/.pnpm/')) {

return `pnpm add -g ${target}`

}

if (normalized.includes('/.yarn/') || normalized.includes('/yarn/')) {

return `yarn global add ${target}`

}

const agent = env.npm_config_user_agent ?? ''

if (agent.startsWith('pnpm/')) return `pnpm add -g ${target}`

if (agent.startsWith('yarn/')) return `yarn global add ${target}`

if (agent.startsWith('bun/')) return `bun add -g ${target}`

return `npm install -g ${target}`

try {

const env = options.env ?? process.env

const isTty = options.isTty ?? process.stderr.isTTY === true

const modulePath = options.modulePath ?? fileURLToPath(import.meta.url)

const cwd = options.cwd ?? process.cwd()

const now = options.now ?? new Date()

if (isEnabled(env.SIM_NO_UPDATE_CHECK)) return

if (!isTty) return

if (isCi(env)) return

if (isUnadvisableInstall(modulePath, env, cwd)) return

const currentVersion = options.currentVersion ?? cliVersion()

const current = parseStableVersion(currentVersion)

if (!current) return

const cachePath = updateCachePath()

const cached = readCache(cachePath)

if (cached && isFresh(cached, now)) return

const tags = await fetchDistTags(env, options.registryRequest ?? requestRegistry)

const latest = tags?.latest ?? null

const available = latest ? parseStableVersion(latest) : null

writeCache(cachePath, {

version: CACHE_VERSION,

checkedAt: now.toISOString(),

})

if (!latest || !available) return

if (!isNewerVersion(available, current)) return

const write = options.write ?? ((message: string) => void process.stderr.write(message))

write(`Update available: sim ${currentVersion} → ${latest}. Run: sim update\n`)

} catch {}