mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* feat(cli): surface outdated CLI and skills to agents; add hyperframes update Single commit of #7094 on top of main (no merge commits through the signed GraphQL path). Includes: 2h update/skills check interval and stale-cache recheck; `_meta.checkedAt`, `_meta.skillsOutdated`, `_meta.skillsMissing`; `_meta.updateNotice`, one sentence for the agent to relay to the person, at most once a day per project (brew/npx-aware command, omitted under CI, the update-check opt-out and agent plugins); `hyperframes update [--check] [--yes] [--json]` (CLI then skills at the installed CLI's tag; brew version read back); doctor names the running binary and its channel; the hyperframes-cli skill gets one line to pass the notice on, naming no command. Keeps main's install-target skills check (#7120) in updateSkills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): update notice names a command that moves this install - `_meta.updateNotice` (and `update --check`'s skills command) now name a command that moves the running install: a global npm/pnpm/bun/brew CLI runs its own `hyperframes update` (or just its manager's command when only the CLI is behind), since `npx hyperframes` would run a project's copy or a fresh npx one; a project-local CLI moves with its project's manager by lockfile (`npm install`/`pnpm add`/`bun add`/`yarn add hyperframes@<v>`), which `update --yes` now names too instead of `npx hyperframes@latest`. - `update`'s confirmation hint states a fact and names no step for the agent: "Updating is the person's call; `update --check` only reports." - `upgrade --json`, `upgrade --project --json` and every `skills` JSON output leave out `_meta.updateNotice` (NO_UPDATE_NOTICE), like `update`. - dailyNotice: a null/non-object file reads as empty and is repaired; a future timestamp is stale; writes go through a 0600 tmp file + rename; withMeta never throws from the notice. - Docs: --json without --yes exits 2; plugin `update` exits 1 (plugin_managed); full `_meta` sample; per-install notice commands. `update --check` says "npm registry not reached" instead of "latest". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
410 lines
16 KiB
TypeScript
410 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";
|
|
|
|
const NPM_REGISTRY_URL = "https://registry.npmjs.org/hyperframes/latest";
|
|
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(NPM_REGISTRY_URL).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(NPM_REGISTRY_URL, {
|
|
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)) {
|
|
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);
|
|
|
|
function cachedVersionForThisInstall(value: unknown): string | 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@latest 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@latest";
|
|
|
|
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`,
|
|
);
|
|
}
|