Skip to content

Commit 7cb6018

Browse files
Vitozhu04claude
andauthored
feat(cli): surface outdated CLI and skills to agents; add hyperframes update --check (#7094)
* 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 <[email protected]> * 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 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 76da5f6 commit 7cb6018

25 files changed

Lines changed: 1956 additions & 95 deletions

‎docs/packages/cli.mdx‎

Lines changed: 96 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ npm install -g hyperframes
3232
| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) |
3333
| Make a file | [`render`](#render), [`benchmark`](#benchmark) |
3434
| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) |
35-
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions), [`clean`](#clean) |
35+
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`update`](#update), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions), [`clean`](#clean) |
3636
| Connect other tools | [`auth`](#hyperframes-auth), [`billing`](#billing), [`templates`](#templates), [`skills`](#skills), [`usage`](#usage), [`figma`](#figma-and-events), [`events`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) |
3737

3838
`validate`, `inspect`, and `layout` still work but are
@@ -59,15 +59,42 @@ second call:
5959
"_meta": {
6060
"version": "0.1.4",
6161
"latestVersion": "0.1.5",
62-
"updateAvailable": true
62+
"updateAvailable": true,
63+
"checkedAt": "2026-11-03T08:00:00.000Z",
64+
"skillsOutdated": 2,
65+
"skillsMissing": 0,
66+
"updateNotice": "For the user: HyperFrames CLI 0.1.5 is available (this run is 0.1.4), and 2 installed HyperFrames skills are out of date. To update both, run: hyperframes update"
6367
}
6468
}
6569
```
6670

67-
The version numbers come from a cache refreshed at most once a day, in a
71+
The version numbers come from a cache refreshed at most every two hours, in a
6872
background process, and never under CI or `HYPERFRAMES_NO_UPDATE_CHECK=1`.
69-
`--json` never makes a network request of its own. Deprecated commands add
70-
`_meta.deprecated: true`.
73+
`checkedAt` says when npm answered. A cached latest older than the running CLI
74+
is left out and rechecked on the next run. `skillsOutdated` counts the installed
75+
HyperFrames skills that are behind this CLI's release, and `skillsMissing` the
76+
core skills that are not installed, from the same background check; both are
77+
absent until that check has run for this version, once it is more than a day old
78+
(as when `HYPERFRAMES_NO_UPDATE_CHECK=1` stops the checks), and under
79+
`HYPERFRAMES_SKIP_SKILLS=1`. `--json` never makes a network request of its own.
80+
Deprecated commands add `_meta.deprecated: true`.
81+
82+
`updateNotice` is one sentence for the agent to pass on to the person when the
83+
CLI or the skills are behind: what is newer and the command that updates it.
84+
The person decides whether to run it. The command moves the install that is
85+
running:
86+
87+
| Install | CLI behind | Skills behind too, or only them |
88+
| --- | --- | --- |
89+
| npm, pnpm, bun or Homebrew global | the manager's command (`npm install -g [email protected]`, `brew upgrade hyperframes`, …) | `hyperframes update` (the global CLI's own; `npx hyperframes` would run a project's copy or a fresh one) |
90+
| project `node_modules` | the project's manager, by lockfile: `npm install`, `pnpm add`, `bun add` or `yarn add [email protected]` | that, then `npx hyperframes update`; skills only: `npx hyperframes update` |
91+
| `npx` | `npx hyperframes@latest update` (npx's cache may hold the old CLI) | the same; skills only: `npx hyperframes update` |
92+
93+
The skills half is left out when no skill is behind or under
94+
`HYPERFRAMES_SKIP_SKILLS=1`. The notice appears at most once a day per project,
95+
while the numeric fields stay on every result. It is never added under CI,
96+
`HYPERFRAMES_NO_UPDATE_CHECK=1`, or an agent plugin (`HYPERFRAMES_PLUGIN_VERSION`),
97+
and the output of `update`, `upgrade` and `skills` leaves it out.
7198

7299
A failure under `--json` always prints one JSON object on stdout, with a
73100
machine-readable `code` and, when there is a next step, a `hint`:
@@ -127,7 +154,8 @@ notice; `HYPERFRAMES_NO_AUTO_INSTALL=1` turns off only the install.
127154
**Skills notice.** When installed HyperFrames skills are out of date or missing,
128155
a command ends with one line on stderr naming `npx hyperframes skills update`.
129156
It shows at most once a day per project. In an unattended run it shows only when
130-
a core skill is missing. `HYPERFRAMES_SKIP_SKILLS=1` turns it off. No notice
157+
a core skill is missing; outdated skills reach agents as `_meta.skillsOutdated`
158+
and `_meta.updateNotice` instead. `HYPERFRAMES_SKIP_SKILLS=1` turns it off. No notice
131159
follows a usage error.
132160

133161
## Create a project
@@ -1976,6 +2004,7 @@ npx hyperframes doctor --json
19762004
hyperframes doctor
19772005
19782006
✓ Version 0.1.4 (latest)
2007+
✓ CLI binary npm global install · /usr/local/lib/node_modules/hyperframes/dist/cli.js
19792008
✓ Node.js v22.x (linux x64)
19802009
✓ FFmpeg 7.x
19812010
✓ FFprobe 7.x
@@ -1986,7 +2015,9 @@ hyperframes doctor
19862015
◇ All checks passed
19872016
```
19882017

1989-
It reports CLI version, Node.js, CPU, memory, disk, the extracted-frame cache,
2018+
It reports CLI version, which binary is running and from where (a global npm,
2019+
pnpm, bun or Homebrew install, a project's `node_modules`, `npx`, or an agent
2020+
plugin) with its path, Node.js, CPU, memory, disk, the extracted-frame cache,
19902021
the archive extractor, `/dev/shm` on Linux, environment, whisper-cpp, local TTS
19912022
and BGM models, FFmpeg, FFprobe, Chrome, and Docker.
19922023

@@ -2037,6 +2068,64 @@ duration, element counts by type, track count, and total size.
20372068
`npx hyperframes compositions` lists every composition in the project with its
20382069
ID, duration, resolution, and element count. Both take `--json`.
20392070

2071+
### `update`
2072+
2073+
```bash
2074+
npx hyperframes update --check # report the CLI and the skills, install nothing
2075+
npx hyperframes update --check --json # the same, for agents
2076+
npx hyperframes update --yes # update both without prompting
2077+
```
2078+
2079+
`update` asks npm for the latest CLI (past the two-hour cache) and checks the
2080+
installed skills against the manifest at this CLI's release tag, in one call.
2081+
`--check` only reports. Without it, `update` upgrades the CLI the way
2082+
`upgrade --yes` does (an `npx` run gets `npx hyperframes@latest` to run instead,
2083+
and a project-local run the project manager's command, such as
2084+
`npm install [email protected]`) and then runs `skills update` at the release
2085+
tag of the CLI that is now installed. Homebrew installs whatever its formula
2086+
has, which can trail npm, so `update` reads the installed version back and
2087+
reports `unchanged` when the formula has not moved. Without `--yes` or
2088+
`--check`, an unattended run and any `--json` run exit 2, with the hint
2089+
"Updating is the person's call; `update --check` only reports." Under an agent
2090+
plugin, `update --check` reports, and `update` itself exits 1 with
2091+
`plugin_managed`: the plugin manager updates it. `HYPERFRAMES_SKIP_SKILLS=1`
2092+
leaves the skills alone. When npm does not answer, the human report says
2093+
"npm registry not reached" instead of calling the CLI the latest.
2094+
`--check --json` returns:
2095+
2096+
```json
2097+
{
2098+
"cli": {
2099+
"current": "0.9.5",
2100+
"latest": "0.9.8",
2101+
"updateAvailable": true,
2102+
"checkedAt": "2026-11-03T08:00:00.000Z",
2103+
"install": { "channel": "npm", "path": "/usr/local/lib/node_modules/hyperframes/dist/cli.js" },
2104+
"command": "npm install -g [email protected]"
2105+
},
2106+
"skills": {
2107+
"status": "checked",
2108+
"ref": "v0.9.5",
2109+
"location": "/Users/me/.claude/skills",
2110+
"updateAvailable": true,
2111+
"outdated": 2,
2112+
"missing": 0,
2113+
"command": "hyperframes update"
2114+
},
2115+
"_meta": {
2116+
"version": "0.9.5",
2117+
"latestVersion": "0.9.8",
2118+
"updateAvailable": true,
2119+
"checkedAt": "2026-11-03T08:00:00.000Z",
2120+
"skillsOutdated": 2,
2121+
"skillsMissing": 0
2122+
}
2123+
}
2124+
```
2125+
2126+
`cli.checkedAt` is `null` when npm did not answer. `install.channel` is one of
2127+
`npm`, `pnpm`, `bun`, `brew`, `npx`, `project`, `workspace`, `plugin` or `unknown`.
2128+
20402129
### `upgrade`
20412130

20422131
```bash

‎packages/cli/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,15 @@ npx hyperframes upgrade
194194
npx hyperframes upgrade --check --json # machine-readable for agents
195195
```
196196

197+
### `update`
198+
199+
Check the CLI and the installed skills for updates in one call, or install both:
200+
201+
```bash
202+
npx hyperframes update --check --json # report only, machine-readable for agents
203+
npx hyperframes update --yes # upgrade the CLI, then refresh the skills
204+
```
205+
197206
## Documentation
198207

199208
Full documentation: [hyperframes.heygen.com/packages/cli](https://hyperframes.heygen.com/packages/cli)

‎packages/cli/src/cli.agentMode.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -381,6 +381,16 @@ describe("agent-mode contract", () => {
381381
},
382382
);
383383

384+
// Updating is the person's decision: the hint states that and names no step for the agent.
385+
it("update without --yes refuses to prompt, exits 2, and leaves updating to the person", async () => {
386+
const run = await runAsAgent(["update"]);
387+
expectQuiet(run);
388+
expect(run.code, run.stderr).toBe(2);
389+
expect(run.stdout).toBe("");
390+
expect(run.stderr).toContain("Updating is the person's call; `update --check` only reports.");
391+
expect(run.stderr).not.toContain("--yes");
392+
});
393+
384394
it("only the prompt wrapper loads @clack/prompts, statically or dynamically", () => {
385395
const offenders = (readdirSync(srcDir, { recursive: true }) as string[]).filter(
386396
(file) =>

‎packages/cli/src/cli.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,7 @@ const commandLoaders = {
166166
doctor: () => import("./commands/doctor.js").then((m) => m.default),
167167
clean: () => import("./commands/clean.js").then((m) => m.default),
168168
upgrade: () => import("./commands/upgrade.js").then((m) => m.default),
169+
update: () => import("./commands/update.js").then((m) => m.default),
169170
skills: () => import("./commands/skills.js").then((m) => m.default),
170171
feedback: () => import("./commands/feedback.js").then((m) => m.default),
171172
telemetry: () => import("./commands/telemetry.js").then((m) => m.default),
@@ -282,6 +283,7 @@ if (
282283
if (
283284
!isHelp &&
284285
command !== "upgrade" &&
286+
command !== "update" &&
285287
command !== "events" &&
286288
command !== "telemetry" &&
287289
command !== "skills" &&
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// `doctor` names the binary that is running and where it lives, and its update hint is the
2+
// command for that install: the manager's for a global one, `npx hyperframes@latest` for npx.
3+
// The install detection is real; only the resolved entry path and the cached latest are stubbed.
4+
5+
import { afterEach, describe, expect, it, vi } from "vitest";
6+
7+
const ENTRIES = {
8+
npm: "/usr/local/lib/node_modules/hyperframes/dist/cli.js",
9+
brew: "/opt/homebrew/Cellar/hyperframes/0.9.5/libexec/lib/node_modules/hyperframes/dist/cli.js",
10+
npx: "/home/me/.npm/_npx/4f1c2a/node_modules/hyperframes/dist/cli.js",
11+
project: "/home/me/video/node_modules/hyperframes/dist/cli.js",
12+
} as const;
13+
14+
const originalArgv1 = process.argv[1];
15+
16+
async function doctorAt(entry: string, latestVersion: string | undefined) {
17+
vi.resetModules();
18+
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "");
19+
vi.doMock("node:fs", async () => ({
20+
...(await vi.importActual<typeof import("node:fs")>("node:fs")),
21+
realpathSync: () => entry,
22+
}));
23+
vi.doMock("../utils/updateCheck.js", async (importOriginal) => ({
24+
...(await importOriginal<typeof import("../utils/updateCheck.js")>()),
25+
getUpdateMeta: () => ({
26+
version: "0.9.5",
27+
latestVersion,
28+
updateAvailable: latestVersion !== undefined && latestVersion !== "0.9.5",
29+
}),
30+
}));
31+
vi.doMock("../version.js", async (importOriginal) => ({
32+
...(await importOriginal<typeof import("../version.js")>()),
33+
VERSION: "0.9.5",
34+
}));
35+
process.argv[1] = "/usr/local/bin/hyperframes";
36+
return import("./doctor.js");
37+
}
38+
39+
afterEach(() => {
40+
process.argv[1] = originalArgv1 ?? "";
41+
vi.doUnmock("node:fs");
42+
vi.doUnmock("../utils/updateCheck.js");
43+
vi.doUnmock("../version.js");
44+
vi.unstubAllEnvs();
45+
vi.resetModules();
46+
});
47+
48+
describe("doctor: the running binary", () => {
49+
it.each([
50+
["npm", ENTRIES.npm, "npm global install"],
51+
["brew", ENTRIES.brew, "Homebrew install"],
52+
["npx", ENTRIES.npx, "npx"],
53+
["project", ENTRIES.project, "project-local install"],
54+
])("names a %s binary and its path", async (_channel, entry, label) => {
55+
const { checkInstall } = await doctorAt(entry, "0.9.5");
56+
const result = checkInstall();
57+
expect(result.ok).toBe(true);
58+
expect(result.detail).toContain(label);
59+
expect(result.detail).toContain(entry);
60+
});
61+
62+
it("names a plugin run as plugin-pinned", async () => {
63+
const { checkInstall } = await doctorAt(ENTRIES.npx, "0.9.5");
64+
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "0.9.5");
65+
expect(checkInstall().detail).toContain("agent plugin");
66+
});
67+
});
68+
69+
describe("doctor: the update hint fits the install", () => {
70+
it.each([
71+
["npm", ENTRIES.npm, "Run: npm install -g [email protected]"],
72+
["brew", ENTRIES.brew, "Run: brew upgrade hyperframes"],
73+
["npx", ENTRIES.npx, "Run: npx hyperframes@latest"],
74+
["project", ENTRIES.project, "Run: npm install [email protected]"],
75+
])("%s", async (_channel, entry, hint) => {
76+
const { checkVersion } = await doctorAt(entry, "0.9.8");
77+
expect(checkVersion()).toEqual({ ok: false, detail: "0.9.5 → 0.9.8 available", hint });
78+
});
79+
80+
it("does not claim 'latest' before any check has answered", async () => {
81+
const { checkVersion } = await doctorAt(ENTRIES.npm, undefined);
82+
expect(checkVersion()).toEqual({ ok: true, detail: "0.9.5 (not checked yet)" });
83+
});
84+
});

‎packages/cli/src/commands/doctor.ts‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@ import { KOKORO_MODULES, KOKORO_PIP, MUSICGEN_MODULES, MUSICGEN_PIP } from "../a
1616
import { hasPythonModules, describeRejectedPythonOverride } from "../tts/python.js";
1717
import { VERSION } from "../version.js";
1818
import { getUpdateMeta, withMeta } from "../utils/updateCheck.js";
19+
import {
20+
installChannelLabel,
21+
runningInstall,
22+
updateCommandFor,
23+
} from "../utils/installerDetection.js";
1924
import {
2025
OPTIONAL_PACKAGES,
2126
installedOptionalPackageVersion,
@@ -82,18 +87,26 @@ function checkDockerRunning(): CheckResult {
8287
}
8388
}
8489

85-
function checkVersion(): CheckResult {
90+
export function checkVersion(): CheckResult {
8691
const meta = getUpdateMeta();
8792
if (meta.updateAvailable && meta.latestVersion) {
8893
return {
8994
ok: false,
9095
detail: `${VERSION} \u2192 ${meta.latestVersion} available`,
91-
hint: "Run: hyperframes upgrade",
96+
hint: `Run: ${updateCommandFor(runningInstall(), meta.latestVersion)}`,
9297
};
9398
}
99+
if (!meta.latestVersion) return { ok: true, detail: `${VERSION} (not checked yet)` };
94100
return { ok: true, detail: `${VERSION} (latest)` };
95101
}
96102

103+
/** Which binary is running and from where: a global install per manager, project-local, npx or a plugin. */
104+
export function checkInstall(): CheckResult {
105+
const install = runningInstall();
106+
const where = install.path ?? "entry path unknown";
107+
return { ok: true, detail: `${installChannelLabel(install.channel)} \u00B7 ${where}` };
108+
}
109+
97110
function checkNode(): CheckResult {
98111
return { ok: true, detail: `${process.version} (${process.platform} ${process.arch})` };
99112
}
@@ -380,6 +393,7 @@ export default defineCommand({
380393
const environment = await runEnvironmentChecks({ includeBrowser: true });
381394
const checks: Check[] = [
382395
{ name: "Version", run: checkVersion },
396+
{ name: "CLI binary", run: checkInstall },
383397
{ name: "Node.js", run: checkNode },
384398
{ name: "CPU", run: checkCPU },
385399
{ name: "Memory", run: checkMemory },

0 commit comments

Comments
 (0)