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>
286 lines
10 KiB
TypeScript
286 lines
10 KiB
TypeScript
/**
|
|
* Detect how the running `hyperframes` binary was installed so auto-update can
|
|
* re-use the same installer. Getting this wrong means either silently failing
|
|
* to update or clobbering a Homebrew install with npm, so the classifier is
|
|
* deliberately conservative — when unsure we return `skip` and leave the user
|
|
* in charge.
|
|
*/
|
|
|
|
import { existsSync, realpathSync } from "node:fs";
|
|
import { posix } from "node:path";
|
|
import { isSafeVersion } from "./safeVersion.js";
|
|
|
|
export type InstallerKind = "npm" | "bun" | "pnpm" | "brew" | "skip";
|
|
|
|
export interface InstallerInfo {
|
|
kind: InstallerKind;
|
|
/** Full command to install the given version, or null when `kind === "skip"`. */
|
|
installCommand: (version: string) => string | null;
|
|
/** Human-readable reason for debug logging / doctor output. */
|
|
reason: string;
|
|
}
|
|
|
|
/**
|
|
* `process.argv[1]` points at the CLI entry script but on global installs the
|
|
* entry is usually a shim in a `bin/` dir that symlinks to the real install
|
|
* under `lib/node_modules/`. Resolve through the symlink so the classifier
|
|
* sees the canonical install prefix.
|
|
*/
|
|
function resolveEntry(): string | null {
|
|
const entry = process.argv[1];
|
|
if (!entry) return null;
|
|
try {
|
|
return realpathSync(entry);
|
|
} catch {
|
|
return entry;
|
|
}
|
|
}
|
|
|
|
function normalizePath(path: string): string {
|
|
return path.replaceAll("\\", "/");
|
|
}
|
|
|
|
/** True when running from a monorepo workspace link (pnpm/bun/yarn `dev:link`). */
|
|
function isWorkspaceLink(realEntry: string): boolean {
|
|
const normalized = normalizePath(realEntry);
|
|
// Resolved path lands inside the repo, typically .../packages/cli/...
|
|
// A real global install never contains `/packages/` because npm publish
|
|
// collapses the package into a flat tarball.
|
|
return normalized.includes("/packages/cli/");
|
|
}
|
|
|
|
/**
|
|
* True when invoked via `npx hyperframes` / `bunx hyperframes`. These don't
|
|
* persist an install, so auto-update is a no-op — the user gets the latest
|
|
* version on the next invocation anyway.
|
|
*/
|
|
function isEphemeralExec(realEntry: string): boolean {
|
|
const normalized = normalizePath(realEntry);
|
|
// npm's npx caches into `<prefix>/_npx/<hash>/`; bun uses `bunx-<uid>-…`.
|
|
return (
|
|
normalized.includes("/_npx/") ||
|
|
normalized.includes("/.npm/_npx/") ||
|
|
posix.basename(posix.dirname(normalized)).startsWith("bunx-") ||
|
|
// bunx installs the package under its temp dir: `/tmp/bunx-<uid>-<spec>/node_modules/…`.
|
|
/\/bunx-[^/]+\/node_modules\//.test(normalized)
|
|
);
|
|
}
|
|
|
|
/**
|
|
* True when the binary was linked into Homebrew's install tree. Homebrew
|
|
* symlinks `/opt/homebrew/bin/hyperframes` into `…/Cellar/hyperframes/<v>/…`
|
|
* (or `/usr/local/Cellar/` on Intel). Either path wins the match.
|
|
*/
|
|
function isHomebrewInstall(realEntry: string): boolean {
|
|
return normalizePath(realEntry).includes("/Cellar/hyperframes/");
|
|
}
|
|
|
|
/**
|
|
* Classify the install by walking the resolved entry path against each
|
|
* package manager's well-known global prefix signature.
|
|
*/
|
|
export function detectInstaller(): InstallerInfo {
|
|
const realEntry = resolveEntry();
|
|
if (!realEntry) {
|
|
return {
|
|
kind: "skip",
|
|
installCommand: () => null,
|
|
reason: "Could not resolve process entry path",
|
|
};
|
|
}
|
|
|
|
const normalizedEntry = normalizePath(realEntry);
|
|
|
|
if (isWorkspaceLink(realEntry)) {
|
|
return {
|
|
kind: "skip",
|
|
installCommand: () => null,
|
|
reason: "Running from a workspace link (monorepo dev)",
|
|
};
|
|
}
|
|
|
|
if (isEphemeralExec(realEntry)) {
|
|
return {
|
|
kind: "skip",
|
|
installCommand: () => null,
|
|
reason: "Running via ephemeral exec (npx / bunx)",
|
|
};
|
|
}
|
|
|
|
if (isHomebrewInstall(realEntry)) {
|
|
return {
|
|
kind: "brew",
|
|
// Updating a brew formula isn't a straight `install`; the formula needs
|
|
// to have been published. Defer to `brew upgrade` which is a no-op if
|
|
// the tap hasn't caught up.
|
|
installCommand: () => "brew upgrade hyperframes",
|
|
reason: `Homebrew install detected at ${realEntry}`,
|
|
};
|
|
}
|
|
|
|
// bun's global install prefix is `~/.bun/install/global/node_modules/` and
|
|
// the bin shim lives at `~/.bun/bin/`. Both paths contain `.bun`.
|
|
if (normalizedEntry.includes("/.bun/")) {
|
|
return {
|
|
kind: "bun",
|
|
installCommand: (version) => `bun add -g hyperframes@${version}`,
|
|
reason: `bun global install detected at ${realEntry}`,
|
|
};
|
|
}
|
|
|
|
// pnpm's global prefix is typically `~/Library/pnpm/global/5/node_modules/`
|
|
// on macOS or `~/.local/share/pnpm/global/…` on Linux. `pnpm` wins when the
|
|
// path contains `/pnpm/global/` regardless of platform.
|
|
if (normalizedEntry.includes("/pnpm/global/")) {
|
|
return {
|
|
kind: "pnpm",
|
|
installCommand: (version) => `pnpm add -g hyperframes@${version}`,
|
|
reason: `pnpm global install detected at ${realEntry}`,
|
|
};
|
|
}
|
|
|
|
// npm's default global prefix is `<prefix>/lib/node_modules/hyperframes/…`
|
|
// where `<prefix>` is `/usr/local` (macOS Intel), `/opt/homebrew` (Apple
|
|
// Silicon, non-brew-formula npm), or a user-configured directory.
|
|
if (
|
|
normalizedEntry.includes("/lib/node_modules/hyperframes/") ||
|
|
normalizedEntry.includes("/npm/node_modules/hyperframes/")
|
|
) {
|
|
return {
|
|
kind: "npm",
|
|
installCommand: (version) => `npm install -g hyperframes@${version}`,
|
|
reason: `npm global install detected at ${realEntry}`,
|
|
};
|
|
}
|
|
|
|
return {
|
|
kind: "skip",
|
|
installCommand: () => null,
|
|
reason: `Unknown install layout at ${realEntry}`,
|
|
};
|
|
}
|
|
|
|
/** Argv-shaped install command for a no-shell `execFile`. */
|
|
export interface InstallInvocation {
|
|
bin: string;
|
|
args: string[];
|
|
}
|
|
|
|
/**
|
|
* The argv form of {@link InstallerInfo.installCommand}, kept next to the
|
|
* detector so the command we *run* (execFile, no shell) and the command we
|
|
* *display* (installCommand string) can never drift. Returns `null` for `skip`
|
|
* kinds (ephemeral npx/bunx, workspace links, project-local, unknown layouts):
|
|
* the caller must print a manual instruction rather than run a guessed command
|
|
* (running the wrong manager is worse than running nothing).
|
|
*/
|
|
export function installInvocation(kind: InstallerKind, version: string): InstallInvocation | null {
|
|
switch (kind) {
|
|
case "npm":
|
|
return { bin: "npm", args: ["install", "-g", `hyperframes@${version}`] };
|
|
case "bun":
|
|
return { bin: "bun", args: ["add", "-g", `hyperframes@${version}`] };
|
|
case "pnpm":
|
|
return { bin: "pnpm", args: ["add", "-g", `hyperframes@${version}`] };
|
|
case "brew":
|
|
// brew has no per-version install; `brew upgrade` moves to the tap's
|
|
// current formula (a no-op if the tap hasn't caught up).
|
|
return { bin: "brew", args: ["upgrade", "hyperframes"] };
|
|
case "skip":
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Where the running binary came from, as `doctor` and `update` report it. Unlike
|
|
* {@link detectInstaller}, which only answers "can a background install own this?",
|
|
* this names every layout, including the ones auto-update leaves alone.
|
|
*/
|
|
export type InstallChannel =
|
|
| "npm"
|
|
| "pnpm"
|
|
| "bun"
|
|
| "brew"
|
|
| "npx"
|
|
| "project"
|
|
| "workspace"
|
|
| "plugin"
|
|
| "unknown";
|
|
|
|
export interface RunningInstall {
|
|
channel: InstallChannel;
|
|
/** The resolved entry script that is running, or null when it cannot be resolved. */
|
|
path: string | null;
|
|
}
|
|
|
|
const CHANNEL_LABELS: Record<InstallChannel, string> = {
|
|
npm: "npm global install",
|
|
pnpm: "pnpm global install",
|
|
bun: "bun global install",
|
|
brew: "Homebrew install",
|
|
npx: "npx / bunx (temporary cache)",
|
|
project: "project-local install (node_modules)",
|
|
workspace: "workspace link (monorepo dev)",
|
|
plugin: "agent plugin (version pinned by the plugin)",
|
|
unknown: "unrecognized install layout",
|
|
};
|
|
|
|
/** Human label for a channel, e.g. "npm global install". */
|
|
export function installChannelLabel(channel: InstallChannel): string {
|
|
return CHANNEL_LABELS[channel];
|
|
}
|
|
|
|
/** Classify the running binary: global (per manager), project-local, npx, workspace link or plugin. */
|
|
export function runningInstall(): RunningInstall {
|
|
const path = resolveEntry();
|
|
// plugin-cli.mjs runs a pinned `npx hyperframes@<version>` and marks the child with this.
|
|
if (process.env["HYPERFRAMES_PLUGIN_VERSION"]) return { channel: "plugin", path };
|
|
const installer = detectInstaller();
|
|
if (installer.kind !== "skip") return { channel: installer.kind, path };
|
|
if (!path) return { channel: "unknown", path };
|
|
if (isWorkspaceLink(path)) return { channel: "workspace", path };
|
|
if (isEphemeralExec(path)) return { channel: "npx", path };
|
|
if (normalizePath(path).includes("/node_modules/hyperframes/")) {
|
|
return { channel: "project", path };
|
|
}
|
|
return { channel: "unknown", path };
|
|
}
|
|
|
|
const PROJECT_LOCKFILES: [string, (spec: string) => string][] = [
|
|
["bun.lock", (spec) => `bun add ${spec}`],
|
|
["bun.lockb", (spec) => `bun add ${spec}`],
|
|
["pnpm-lock.yaml", (spec) => `pnpm add ${spec}`],
|
|
["yarn.lock", (spec) => `yarn add ${spec}`],
|
|
];
|
|
|
|
/**
|
|
* What moves a project-local CLI: its project's manager (named by the lockfile beside the
|
|
* project's `node_modules`, npm without one) adding `hyperframes@<version>`. Each of the four
|
|
* keeps the dependency in the section it is in. `upgrade --project` only rewrites script pins.
|
|
*/
|
|
function projectInstallCommand(path: string, version: string): string {
|
|
const normalized = normalizePath(path);
|
|
const root = normalized.slice(0, normalized.indexOf("/node_modules/"));
|
|
const spec = `hyperframes@${version}`;
|
|
const lockfile = PROJECT_LOCKFILES.find(([name]) => existsSync(posix.join(root, name)));
|
|
return lockfile ? lockfile[1](spec) : `npm install ${spec}`;
|
|
}
|
|
|
|
/**
|
|
* The command that moves this install to `latest`: the owning manager's for a global or
|
|
* project-local install, `npx hyperframes@latest` everywhere a manager command would not apply.
|
|
*/
|
|
export function updateCommandFor(install: RunningInstall, latest: string): string {
|
|
if (install.channel === "plugin") return "update the HyperFrames plugin in your agent";
|
|
if (install.channel === "brew") return "brew upgrade hyperframes";
|
|
if (install.channel === "project" && install.path && isSafeVersion(latest)) {
|
|
return projectInstallCommand(install.path, latest);
|
|
}
|
|
const kind = install.channel;
|
|
if (kind === "npm" || kind === "pnpm" || kind === "bun") {
|
|
const invocation = installInvocation(kind, latest);
|
|
if (invocation) return `${invocation.bin} ${invocation.args.join(" ")}`;
|
|
}
|
|
return "npx hyperframes@latest";
|
|
}
|