Files
hyperframes/packages/cli/src/utils/updateCheck.ts
T
terencecho 04947d99f7 feat(cli): share rendered videos through unified reviews (#7135)
* feat(cli): share rendered videos through unified reviews (#7135)

* feat(share): attach editable project sources to reviews (#7137)

* feat(share): measure local sharing outcomes (#7138)

* feat(cli): stage the sixty-day publish transition (#7136)

* feat(studio): share review pages from local preview (#7140)

Advertise the CLI sharing bridge before bootstrapping it so standalone Studio does not
request unsupported routes. Preserve origin and session checks.

Budget the intended sharing artifact: clean main packs at 8,060,519 bytes versus
8,162,979 with sharing (8,169,168 in CI). Required policy and Unicode tables, bundled
sharing code, and Studio controls account for the growth. Set the packed-only budget
to 8,577,627, following the 5% headroom convention; retain the unpacked cap and all
package checks.

* fix(share): persist refusals and improve CLI retry feedback

* fix(ci): restore render diagnostics and include sharing workspace

* fix(cli): keep sharing owner error codes stable

* fix(share): clarify update feedback and align audience changes

* fix(share): clarify updates and avoid scratch-file rerenders

* fix(cli): report active shares and preserve update channels

* fix(cli): resolve update channel when checking registry

* fix(ci): refresh sharing package budgets after rebase

* fix(share): require consent before uploading project files
2026-11-11 06:26:24 +00:00

420 lines
16 KiB
TypeScript

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<UpdateCheckResult> {
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<typeof readConfig>,
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<InstallChannel> = 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<T extends object>(
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<string, string> = {};
try {
const pkgPath = join(cwd, "package.json");
if (!existsSync(pkgPath)) return;
scripts = (JSON.parse(readFileSync(pkgPath, "utf-8")).scripts ?? {}) as Record<string, string>;
} 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`,
);
}