import { existsSync, readFileSync } from "node:fs"; import { join, resolve } from "node:path"; import { compareVersions } from "compare-versions"; import { readConfig, readConfigFresh, writeConfig } from "../telemetry/config.js"; import { VERSION } from "../version.js"; import { isCI, isUnattended } from "./attendedTerminal.js"; import { isDevMode } from "./env.js"; import { asNotice } from "./jsonError.js"; import { hostAnswers } from "./hostAnswers.js"; import { claimDailyNotice } from "./dailyNotice.js"; import { detectInstaller, runningInstall, updateCommandFor, type InstallChannel, type RunningInstall, } from "./installerDetection.js"; import { readPinnedHyperframesVersions } from "./projectPin.js"; import { isSafeVersion } from "./safeVersion.js"; export { isSafeVersion } from "./safeVersion.js"; export function updateChannel(version = VERSION): string { if (version === "0.0.0-dev") return "latest"; return version.match(/^\d+\.\d+\.\d+-([a-z][a-z0-9-]*)(?:\.|$)/i)?.[1] ?? "latest"; } const npmRegistryUrl = () => `https://registry.npmjs.org/hyperframes/${updateChannel()}`; const CHECK_INTERVAL_MS = 2 * 60 * 60 * 1000; const SKILLS_COUNT_MAX_AGE_MS = 24 * 60 * 60 * 1000; const FETCH_TIMEOUT_MS = 3000; /** Returns true if `a` is newer than `b` per semver (handles alpha, beta, rc). */ function isNewerSemver(a: string, b: string): boolean { try { return compareVersions(a, b) > 0; } catch { return a !== b; } } export interface UpdateCheckResult { current: string; latest: string; updateAvailable: boolean; } export interface UpdateMeta { version: string; latestVersion?: string; updateAvailable: boolean; /** When the registry gave `latestVersion` (ISO). Absent when no usable answer is cached. */ checkedAt?: string; /** Installed skills behind this CLI's release tag, per the cached background check. */ skillsOutdated?: number; /** Core skills not installed, from the same cached check and under the same rules as `skillsOutdated`. */ skillsMissing?: number; /** * One sentence for the agent to pass on to the person: a newer CLI or skills, and the command * that updates them. Added by `withMeta` at most once a day per project; absent otherwise. */ updateNotice?: string; /** Present (and true) only for commands superseded by `check`; absent otherwise. */ deprecated?: boolean; } /** * Check npm registry for the latest version. Uses a 2h cache to avoid * hitting the registry on every invocation. * * @param force - Skip the cache, opt-outs and DNS probe: the caller waits for the registry */ export async function checkForUpdate(force?: boolean): Promise { const config = readConfig(); if (!force && !updateCheckDue(config)) return fallbackResult(config.latestVersion); try { if (!force && !(await hostAnswers(new URL(npmRegistryUrl()).hostname))) { return fallbackResult(config.latestVersion); } const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS); let data: { version?: unknown }; try { const res = await fetch(npmRegistryUrl(), { signal: controller.signal, headers: { Connection: "close" }, }); if (!res.ok) return fallbackResult(config.latestVersion); data = (await res.json()) as { version?: unknown }; } finally { clearTimeout(timeout); } // Registry boundary guard: only a strict-semver STRING is trusted. This // value is cached and later flows into an install command that the // background auto-updater executes, so a poisoned or non-string // data.version (e.g. "1.2.3; rm -rf /") must never be persisted. Reject it // and fall back to the last known-good version. Closes the injection class // for every consumer at one point. if ( typeof data.version !== "string" || !isSafeVersion(data.version) || updateChannel(data.version) !== updateChannel() ) { return fallbackResult(config.latestVersion); } const latest = data.version; // The registry request can take seconds. Merge its two metadata fields // into a fresh snapshot rather than writing the object captured before // the network call: the stale object previously reverted a concurrent // `telemetry disable` back to the default `true`. const freshConfig = readConfigFresh(); freshConfig.lastUpdateCheck = new Date().toISOString(); freshConfig.latestVersion = latest; writeConfig(freshConfig); return { current: VERSION, latest, updateAvailable: isNewerSemver(latest, VERSION) }; } catch { return fallbackResult(config.latestVersion); } } /** * Whether the background check should ask the registry: not opted out, and no fresh safe cache. * A cached latest older than the running CLI predates this install, so it is stale however recent. */ export function updateCheckDue(config = readConfig()): boolean { if (updateCheckDisabled()) return false; if (!config.lastUpdateCheck || !isSafeCache(config.latestVersion)) return true; if (isNewerSemver(VERSION, config.latestVersion)) return true; const fresh = Date.now() - new Date(config.lastUpdateCheck).getTime() < CHECK_INTERVAL_MS; return !fresh; } export function cachedUpdateCheck(): UpdateCheckResult { return fallbackResult(readConfig().latestVersion); } function fallbackResult(cachedLatest?: string): UpdateCheckResult { // Only surface a cached version we can prove is safe — a pre-existing // poisoned cache must not leak through the fallback path either. const safeCached = cachedVersionForThisInstall(cachedLatest); return { current: VERSION, latest: safeCached ?? VERSION, updateAvailable: safeCached ? isNewerSemver(safeCached, VERSION) : false, }; } const isSafeCache = (value: unknown): value is string => typeof value === "string" && isSafeVersion(value) && updateChannel(value) === updateChannel(); function cachedVersionForThisInstall(value: unknown): string | undefined { const checkedAt = readConfig().lastUpdateCheck; if (checkedAt && Date.now() - Date.parse(checkedAt) >= CHECK_INTERVAL_MS) return undefined; return isSafeCache(value) && !isNewerSemver(VERSION, value) ? value : undefined; } /** * Synchronous read from cache — for _meta envelope on --json commands. * Never fetches. Returns what the last background check found. */ export function getUpdateMeta(): UpdateMeta { const config = readConfig(); const latestVersion = cachedVersionForThisInstall(config.latestVersion); const checkedAt = latestVersion ? config.lastUpdateCheck : undefined; const skillsOutdated = cachedSkillsCount(config, config.skillsOutdatedCount); const skillsMissing = cachedSkillsCount(config, config.skillsMissingCount); return { version: VERSION, latestVersion, updateAvailable: latestVersion ? isNewerSemver(latestVersion, VERSION) : false, ...(checkedAt ? { checkedAt } : {}), ...(skillsOutdated === undefined ? {} : { skillsOutdated }), ...(skillsMissing === undefined ? {} : { skillsMissing }), }; } /** A cached skills count, only when taken for this CLI version's tag in the last 24 h. */ function cachedSkillsCount( config: ReturnType, count: unknown, ): number | undefined { if (process.env["HYPERFRAMES_SKIP_SKILLS"] === "1") return undefined; if (!config.lastSkillsCheck || config.skillsCheckedVersion !== VERSION) return undefined; const age = Date.now() - new Date(config.lastSkillsCheck).getTime(); if (!(age >= 0 && age < SKILLS_COUNT_MAX_AGE_MS)) return undefined; return typeof count === "number" && Number.isInteger(count) && count >= 0 ? count : undefined; } /** "3 installed HyperFrames skills are out of date and 1 core skill is missing", or null. */ function skillsBehindPhrase(meta: UpdateMeta): string | null { const outdated = meta.skillsOutdated ?? 0; const missing = meta.skillsMissing ?? 0; const parts: string[] = []; if (outdated > 0) { parts.push( `${outdated} installed HyperFrames ${outdated === 1 ? "skill is" : "skills are"} out of date`, ); } if (missing > 0) { const which = outdated > 0 ? "core" : "core HyperFrames"; parts.push(`${missing} ${which} ${missing === 1 ? "skill is" : "skills are"} missing`); } return parts.length > 0 ? parts.join(" and ") : null; } const GLOBAL_CHANNELS: ReadonlySet = new Set(["npm", "pnpm", "bun", "brew"]); /** A project-local CLI moves with its project's manager; `update` there then only does the skills. */ function projectNoticeCommand( install: RunningInstall, cliBehind: boolean, skillsBehind: boolean, latest: string, ): string { if (!cliBehind) return "npx hyperframes update"; const bump = updateCommandFor(install, latest); return skillsBehind ? `${bump}, then npx hyperframes update` : bump; } /** * A command that moves THIS install. A global CLI runs its own `hyperframes update` (or just its * manager's command when only the CLI is behind): `npx hyperframes` would run a project's copy or * a fresh npx one instead. An npx run pins `@latest`, since npx's cache can hold the old CLI. */ export function updateCommandForThisInstall( cliBehind: boolean, skillsBehind: boolean, latest: string, ): string { const install = runningInstall(); if (GLOBAL_CHANNELS.has(install.channel)) { return skillsBehind ? "hyperframes update" : updateCommandFor(install, latest); } if (install.channel === "project") { return projectNoticeCommand(install, cliBehind, skillsBehind, latest); } return install.channel === "npx" && cliBehind ? `npx hyperframes@${updateChannel()} update` : "npx hyperframes update"; } /** The sentence itself: the newer CLI, the skills behind, or both, and the command. */ function noticeSentence( version: string, latest: string | null, skills: string | null, command: string, ): string { const cli = latest ? `HyperFrames CLI ${latest} is available (this run is ${version})` : null; if (cli && skills) return `For the user: ${cli}, and ${skills}. To update both, run: ${command}`; if (cli) return `For the user: ${cli}. To update, run: ${command}`; return `For the user: ${skills} (this run is HyperFrames CLI ${version}). To update them, run: ${command}`; } /** The update notice for this run's `_meta`, before the once-a-day gate; null when there is nothing to say. */ function updateNoticeText(meta: UpdateMeta): string | null { if (updateCheckDisabled() || process.env["HYPERFRAMES_PLUGIN_VERSION"]) return null; const latest = meta.updateAvailable ? (meta.latestVersion ?? null) : null; const skills = skillsBehindPhrase(meta); if (!latest && !skills) return null; const command = updateCommandForThisInstall( latest !== null, skills !== null, latest ?? meta.version, ); return noticeSentence(meta.version, latest, skills, command); } /** The notice when it is due for this project today; a failure here never fails the command. */ function noticeOrNull(meta: UpdateMeta): string | null { try { const notice = updateNoticeText(meta); return notice && claimDailyNotice("update", resolve(process.cwd())) ? notice : null; } catch { return null; } } /** * For `withMeta` in commands whose own output is about updating (`update`, `upgrade`, `skills`): * the same commands `cli.ts` keeps the stderr notices away from. */ export const NO_UPDATE_NOTICE = { updateNotice: false }; /** * Wrap a JSON payload with the _meta version envelope. * Use this in all --json command outputs for consistent agent-friendly metadata. * * Pass `{ deprecated: true }` from a command superseded by `check` (validate, * inspect, layout) to add `_meta.deprecated: true`; every other call site is * unaffected — the key is only ever added, never set to `false`. * * `_meta.updateNotice` is added when the CLI or the skills are behind, at most once a day per * project (the numeric fields stay on every result). `{ updateNotice: false }` leaves it out, * for `update`, whose own result already says what to run. */ export function withMeta( data: T, options?: { deprecated?: boolean; updateNotice?: boolean }, ): T & { _meta: UpdateMeta } { const meta = getUpdateMeta(); if (options?.updateNotice !== false) { const notice = noticeOrNull(meta); if (notice) meta.updateNotice = notice; } if (options?.deprecated) meta.deprecated = true; return { ...data, _meta: meta }; } /** * One-line deprecation notice for a command superseded by `check`. Always * writes to stderr (never stdout), so a --json invocation's stdout stays * pure, parseable JSON. Call once per invocation, before the command's own * output. */ export function printDeprecationNotice(command: string): void { asNotice(() => process.stderr.write( `'hyperframes ${command}' is deprecated and will be removed in a future release. Use 'hyperframes check' instead.\n`, ), ); } /** True when the update check is off: dev mode, CI, or the HYPERFRAMES_NO_UPDATE_CHECK opt-out. */ export function updateCheckDisabled(): boolean { if (isDevMode()) return true; if (isCI()) return true; return process.env["HYPERFRAMES_NO_UPDATE_CHECK"] === "1"; } /** * True when update / freshness notices should stay silent: the check is off or stderr is not a * terminal. Shared with the skills freshness notice so both honour the same gating. */ export function updateNoticesSuppressed(): boolean { return updateCheckDisabled() || !process.stderr.isTTY || isUnattended(); } /** * Print update notice to stderr if a newer version is available. * Skipped in CI, non-TTY, dev mode, or when HYPERFRAMES_NO_UPDATE_CHECK is set. */ export function printUpdateNotice(): void { if (updateNoticesSuppressed()) return; const meta = getUpdateMeta(); if (!meta.updateAvailable || !meta.latestVersion) return; if (readConfig().pendingUpdate?.version === meta.latestVersion) return; // Show the command that updates *this* install: the detected package // manager's upgrade for owned global installs (npm/bun/pnpm/brew), and the // universal `npx hyperframes@latest` for ephemeral/unknown installs (where a // manager command wouldn't apply). detectInstaller() only runs here, after // the suppression + update-available gates, so it adds no cost to normal runs. const safeLatest = isSafeVersion(meta.latestVersion); const managerCommand = safeLatest ? detectInstaller().installCommand(meta.latestVersion) : null; const command = managerCommand ?? `npx hyperframes@${updateChannel()}`; process.stderr.write( `\n Update available: ${meta.version} \u2192 ${meta.latestVersion}\n` + ` Run: ${command}\n\n`, ); } const STALE_PIN_THROTTLE_MS = 24 * 60 * 60 * 1000; /** * Actionable notice when the running CLI is older than the project's pin (every * run), or when the pin is older than the latest release (once/24h per install). * Unlike printUpdateNotice this DOES fire on non-TTY (agents render with piped * stderr), but never under --json/CI/dev/opt-out: the whole cli.ts update block * is skipped for --json, so a JSON stdout stays clean regardless. */ export function printStalePinNotice(cwd: string = process.cwd()): void { if (updateCheckDisabled()) return; let scripts: Record = {}; try { const pkgPath = join(cwd, "package.json"); if (!existsSync(pkgPath)) return; scripts = (JSON.parse(readFileSync(pkgPath, "utf-8")).scripts ?? {}) as Record; } catch { return; } const pins = readPinnedHyperframesVersions(scripts); // A CLI older than the pin (e.g. a stale npx cache) misjudges every run, so this is never throttled. const newerPins = pins.filter((v) => isNewerSemver(v, VERSION)).sort(compareVersions); if (newerPins.length > 0) { process.stderr.write( `\n This is hyperframes ${VERSION}, but this project pins hyperframes@${newerPins.join(", ")}.\n` + ` Run it through the project's npm scripts, or npx hyperframes@${newerPins.at(-1)}.\n\n`, ); return; } const latest = getUpdateMeta().latestVersion; if (!latest || !isSafeVersion(latest)) return; const stale = pins.filter((v) => { try { return compareVersions(latest, v) > 0; } catch { return false; } }); if (stale.length === 0) return; const last = readConfig().lastStalePinNoticeAt ?? 0; if (Date.now() - last < STALE_PIN_THROTTLE_MS) return; const config = readConfigFresh(); config.lastStalePinNoticeAt = Date.now(); writeConfig(config); process.stderr.write( `\n This project pins hyperframes@${stale.join(", ")} (latest ${latest}).\n` + ` Bump it: npx hyperframes@latest upgrade --project\n\n`, ); }