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 --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 <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>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
76da5f6932
commit
7cb6018c6b
+96
-7
@@ -32,7 +32,7 @@ npm install -g hyperframes
|
||||
| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) |
|
||||
| Make a file | [`render`](#render), [`benchmark`](#benchmark) |
|
||||
| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) |
|
||||
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions), [`clean`](#clean) |
|
||||
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`update`](#update), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions), [`clean`](#clean) |
|
||||
| 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) |
|
||||
|
||||
`validate`, `inspect`, and `layout` still work but are
|
||||
@@ -59,15 +59,42 @@ second call:
|
||||
"_meta": {
|
||||
"version": "0.1.4",
|
||||
"latestVersion": "0.1.5",
|
||||
"updateAvailable": true
|
||||
"updateAvailable": true,
|
||||
"checkedAt": "2026-11-03T08:00:00.000Z",
|
||||
"skillsOutdated": 2,
|
||||
"skillsMissing": 0,
|
||||
"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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The version numbers come from a cache refreshed at most once a day, in a
|
||||
The version numbers come from a cache refreshed at most every two hours, in a
|
||||
background process, and never under CI or `HYPERFRAMES_NO_UPDATE_CHECK=1`.
|
||||
`--json` never makes a network request of its own. Deprecated commands add
|
||||
`_meta.deprecated: true`.
|
||||
`checkedAt` says when npm answered. A cached latest older than the running CLI
|
||||
is left out and rechecked on the next run. `skillsOutdated` counts the installed
|
||||
HyperFrames skills that are behind this CLI's release, and `skillsMissing` the
|
||||
core skills that are not installed, from the same background check; both are
|
||||
absent until that check has run for this version, once it is more than a day old
|
||||
(as when `HYPERFRAMES_NO_UPDATE_CHECK=1` stops the checks), and under
|
||||
`HYPERFRAMES_SKIP_SKILLS=1`. `--json` never makes a network request of its own.
|
||||
Deprecated commands add `_meta.deprecated: true`.
|
||||
|
||||
`updateNotice` is one sentence for the agent to pass on to the person when the
|
||||
CLI or the skills are behind: what is newer and the command that updates it.
|
||||
The person decides whether to run it. The command moves the install that is
|
||||
running:
|
||||
|
||||
| Install | CLI behind | Skills behind too, or only them |
|
||||
| --- | --- | --- |
|
||||
| npm, pnpm, bun or Homebrew global | the manager's command (`npm install -g hyperframes@0.9.8`, `brew upgrade hyperframes`, …) | `hyperframes update` (the global CLI's own; `npx hyperframes` would run a project's copy or a fresh one) |
|
||||
| project `node_modules` | the project's manager, by lockfile: `npm install`, `pnpm add`, `bun add` or `yarn add hyperframes@0.9.8` | that, then `npx hyperframes update`; skills only: `npx hyperframes update` |
|
||||
| `npx` | `npx hyperframes@latest update` (npx's cache may hold the old CLI) | the same; skills only: `npx hyperframes update` |
|
||||
|
||||
The skills half is left out when no skill is behind or under
|
||||
`HYPERFRAMES_SKIP_SKILLS=1`. The notice appears at most once a day per project,
|
||||
while the numeric fields stay on every result. It is never added under CI,
|
||||
`HYPERFRAMES_NO_UPDATE_CHECK=1`, or an agent plugin (`HYPERFRAMES_PLUGIN_VERSION`),
|
||||
and the output of `update`, `upgrade` and `skills` leaves it out.
|
||||
|
||||
A failure under `--json` always prints one JSON object on stdout, with a
|
||||
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.
|
||||
**Skills notice.** When installed HyperFrames skills are out of date or missing,
|
||||
a command ends with one line on stderr naming `npx hyperframes skills update`.
|
||||
It shows at most once a day per project. In an unattended run it shows only when
|
||||
a core skill is missing. `HYPERFRAMES_SKIP_SKILLS=1` turns it off. No notice
|
||||
a core skill is missing; outdated skills reach agents as `_meta.skillsOutdated`
|
||||
and `_meta.updateNotice` instead. `HYPERFRAMES_SKIP_SKILLS=1` turns it off. No notice
|
||||
follows a usage error.
|
||||
|
||||
## Create a project
|
||||
@@ -1976,6 +2004,7 @@ npx hyperframes doctor --json
|
||||
hyperframes doctor
|
||||
|
||||
✓ Version 0.1.4 (latest)
|
||||
✓ CLI binary npm global install · /usr/local/lib/node_modules/hyperframes/dist/cli.js
|
||||
✓ Node.js v22.x (linux x64)
|
||||
✓ FFmpeg 7.x
|
||||
✓ FFprobe 7.x
|
||||
@@ -1986,7 +2015,9 @@ hyperframes doctor
|
||||
◇ All checks passed
|
||||
```
|
||||
|
||||
It reports CLI version, Node.js, CPU, memory, disk, the extracted-frame cache,
|
||||
It reports CLI version, which binary is running and from where (a global npm,
|
||||
pnpm, bun or Homebrew install, a project's `node_modules`, `npx`, or an agent
|
||||
plugin) with its path, Node.js, CPU, memory, disk, the extracted-frame cache,
|
||||
the archive extractor, `/dev/shm` on Linux, environment, whisper-cpp, local TTS
|
||||
and BGM models, FFmpeg, FFprobe, Chrome, and Docker.
|
||||
|
||||
@@ -2037,6 +2068,64 @@ duration, element counts by type, track count, and total size.
|
||||
`npx hyperframes compositions` lists every composition in the project with its
|
||||
ID, duration, resolution, and element count. Both take `--json`.
|
||||
|
||||
### `update`
|
||||
|
||||
```bash
|
||||
npx hyperframes update --check # report the CLI and the skills, install nothing
|
||||
npx hyperframes update --check --json # the same, for agents
|
||||
npx hyperframes update --yes # update both without prompting
|
||||
```
|
||||
|
||||
`update` asks npm for the latest CLI (past the two-hour cache) and checks the
|
||||
installed skills against the manifest at this CLI's release tag, in one call.
|
||||
`--check` only reports. Without it, `update` upgrades the CLI the way
|
||||
`upgrade --yes` does (an `npx` run gets `npx hyperframes@latest` to run instead,
|
||||
and a project-local run the project manager's command, such as
|
||||
`npm install hyperframes@0.9.8`) and then runs `skills update` at the release
|
||||
tag of the CLI that is now installed. Homebrew installs whatever its formula
|
||||
has, which can trail npm, so `update` reads the installed version back and
|
||||
reports `unchanged` when the formula has not moved. Without `--yes` or
|
||||
`--check`, an unattended run and any `--json` run exit 2, with the hint
|
||||
"Updating is the person's call; `update --check` only reports." Under an agent
|
||||
plugin, `update --check` reports, and `update` itself exits 1 with
|
||||
`plugin_managed`: the plugin manager updates it. `HYPERFRAMES_SKIP_SKILLS=1`
|
||||
leaves the skills alone. When npm does not answer, the human report says
|
||||
"npm registry not reached" instead of calling the CLI the latest.
|
||||
`--check --json` returns:
|
||||
|
||||
```json
|
||||
{
|
||||
"cli": {
|
||||
"current": "0.9.5",
|
||||
"latest": "0.9.8",
|
||||
"updateAvailable": true,
|
||||
"checkedAt": "2026-11-03T08:00:00.000Z",
|
||||
"install": { "channel": "npm", "path": "/usr/local/lib/node_modules/hyperframes/dist/cli.js" },
|
||||
"command": "npm install -g hyperframes@0.9.8"
|
||||
},
|
||||
"skills": {
|
||||
"status": "checked",
|
||||
"ref": "v0.9.5",
|
||||
"location": "/Users/me/.claude/skills",
|
||||
"updateAvailable": true,
|
||||
"outdated": 2,
|
||||
"missing": 0,
|
||||
"command": "hyperframes update"
|
||||
},
|
||||
"_meta": {
|
||||
"version": "0.9.5",
|
||||
"latestVersion": "0.9.8",
|
||||
"updateAvailable": true,
|
||||
"checkedAt": "2026-11-03T08:00:00.000Z",
|
||||
"skillsOutdated": 2,
|
||||
"skillsMissing": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`cli.checkedAt` is `null` when npm did not answer. `install.channel` is one of
|
||||
`npm`, `pnpm`, `bun`, `brew`, `npx`, `project`, `workspace`, `plugin` or `unknown`.
|
||||
|
||||
### `upgrade`
|
||||
|
||||
```bash
|
||||
|
||||
@@ -194,6 +194,15 @@ npx hyperframes upgrade
|
||||
npx hyperframes upgrade --check --json # machine-readable for agents
|
||||
```
|
||||
|
||||
### `update`
|
||||
|
||||
Check the CLI and the installed skills for updates in one call, or install both:
|
||||
|
||||
```bash
|
||||
npx hyperframes update --check --json # report only, machine-readable for agents
|
||||
npx hyperframes update --yes # upgrade the CLI, then refresh the skills
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Full documentation: [hyperframes.heygen.com/packages/cli](https://hyperframes.heygen.com/packages/cli)
|
||||
|
||||
@@ -381,6 +381,16 @@ describe("agent-mode contract", () => {
|
||||
},
|
||||
);
|
||||
|
||||
// Updating is the person's decision: the hint states that and names no step for the agent.
|
||||
it("update without --yes refuses to prompt, exits 2, and leaves updating to the person", async () => {
|
||||
const run = await runAsAgent(["update"]);
|
||||
expectQuiet(run);
|
||||
expect(run.code, run.stderr).toBe(2);
|
||||
expect(run.stdout).toBe("");
|
||||
expect(run.stderr).toContain("Updating is the person's call; `update --check` only reports.");
|
||||
expect(run.stderr).not.toContain("--yes");
|
||||
});
|
||||
|
||||
it("only the prompt wrapper loads @clack/prompts, statically or dynamically", () => {
|
||||
const offenders = (readdirSync(srcDir, { recursive: true }) as string[]).filter(
|
||||
(file) =>
|
||||
|
||||
@@ -166,6 +166,7 @@ const commandLoaders = {
|
||||
doctor: () => import("./commands/doctor.js").then((m) => m.default),
|
||||
clean: () => import("./commands/clean.js").then((m) => m.default),
|
||||
upgrade: () => import("./commands/upgrade.js").then((m) => m.default),
|
||||
update: () => import("./commands/update.js").then((m) => m.default),
|
||||
skills: () => import("./commands/skills.js").then((m) => m.default),
|
||||
feedback: () => import("./commands/feedback.js").then((m) => m.default),
|
||||
telemetry: () => import("./commands/telemetry.js").then((m) => m.default),
|
||||
@@ -282,6 +283,7 @@ if (
|
||||
if (
|
||||
!isHelp &&
|
||||
command !== "upgrade" &&
|
||||
command !== "update" &&
|
||||
command !== "events" &&
|
||||
command !== "telemetry" &&
|
||||
command !== "skills" &&
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
// `doctor` names the binary that is running and where it lives, and its update hint is the
|
||||
// command for that install: the manager's for a global one, `npx hyperframes@latest` for npx.
|
||||
// The install detection is real; only the resolved entry path and the cached latest are stubbed.
|
||||
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const ENTRIES = {
|
||||
npm: "/usr/local/lib/node_modules/hyperframes/dist/cli.js",
|
||||
brew: "/opt/homebrew/Cellar/hyperframes/0.9.5/libexec/lib/node_modules/hyperframes/dist/cli.js",
|
||||
npx: "/home/me/.npm/_npx/4f1c2a/node_modules/hyperframes/dist/cli.js",
|
||||
project: "/home/me/video/node_modules/hyperframes/dist/cli.js",
|
||||
} as const;
|
||||
|
||||
const originalArgv1 = process.argv[1];
|
||||
|
||||
async function doctorAt(entry: string, latestVersion: string | undefined) {
|
||||
vi.resetModules();
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "");
|
||||
vi.doMock("node:fs", async () => ({
|
||||
...(await vi.importActual<typeof import("node:fs")>("node:fs")),
|
||||
realpathSync: () => entry,
|
||||
}));
|
||||
vi.doMock("../utils/updateCheck.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../utils/updateCheck.js")>()),
|
||||
getUpdateMeta: () => ({
|
||||
version: "0.9.5",
|
||||
latestVersion,
|
||||
updateAvailable: latestVersion !== undefined && latestVersion !== "0.9.5",
|
||||
}),
|
||||
}));
|
||||
vi.doMock("../version.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../version.js")>()),
|
||||
VERSION: "0.9.5",
|
||||
}));
|
||||
process.argv[1] = "/usr/local/bin/hyperframes";
|
||||
return import("./doctor.js");
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
process.argv[1] = originalArgv1 ?? "";
|
||||
vi.doUnmock("node:fs");
|
||||
vi.doUnmock("../utils/updateCheck.js");
|
||||
vi.doUnmock("../version.js");
|
||||
vi.unstubAllEnvs();
|
||||
vi.resetModules();
|
||||
});
|
||||
|
||||
describe("doctor: the running binary", () => {
|
||||
it.each([
|
||||
["npm", ENTRIES.npm, "npm global install"],
|
||||
["brew", ENTRIES.brew, "Homebrew install"],
|
||||
["npx", ENTRIES.npx, "npx"],
|
||||
["project", ENTRIES.project, "project-local install"],
|
||||
])("names a %s binary and its path", async (_channel, entry, label) => {
|
||||
const { checkInstall } = await doctorAt(entry, "0.9.5");
|
||||
const result = checkInstall();
|
||||
expect(result.ok).toBe(true);
|
||||
expect(result.detail).toContain(label);
|
||||
expect(result.detail).toContain(entry);
|
||||
});
|
||||
|
||||
it("names a plugin run as plugin-pinned", async () => {
|
||||
const { checkInstall } = await doctorAt(ENTRIES.npx, "0.9.5");
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "0.9.5");
|
||||
expect(checkInstall().detail).toContain("agent plugin");
|
||||
});
|
||||
});
|
||||
|
||||
describe("doctor: the update hint fits the install", () => {
|
||||
it.each([
|
||||
["npm", ENTRIES.npm, "Run: npm install -g hyperframes@0.9.8"],
|
||||
["brew", ENTRIES.brew, "Run: brew upgrade hyperframes"],
|
||||
["npx", ENTRIES.npx, "Run: npx hyperframes@latest"],
|
||||
["project", ENTRIES.project, "Run: npm install hyperframes@0.9.8"],
|
||||
])("%s", async (_channel, entry, hint) => {
|
||||
const { checkVersion } = await doctorAt(entry, "0.9.8");
|
||||
expect(checkVersion()).toEqual({ ok: false, detail: "0.9.5 → 0.9.8 available", hint });
|
||||
});
|
||||
|
||||
it("does not claim 'latest' before any check has answered", async () => {
|
||||
const { checkVersion } = await doctorAt(ENTRIES.npm, undefined);
|
||||
expect(checkVersion()).toEqual({ ok: true, detail: "0.9.5 (not checked yet)" });
|
||||
});
|
||||
});
|
||||
@@ -16,6 +16,11 @@ import { KOKORO_MODULES, KOKORO_PIP, MUSICGEN_MODULES, MUSICGEN_PIP } from "../a
|
||||
import { hasPythonModules, describeRejectedPythonOverride } from "../tts/python.js";
|
||||
import { VERSION } from "../version.js";
|
||||
import { getUpdateMeta, withMeta } from "../utils/updateCheck.js";
|
||||
import {
|
||||
installChannelLabel,
|
||||
runningInstall,
|
||||
updateCommandFor,
|
||||
} from "../utils/installerDetection.js";
|
||||
import {
|
||||
OPTIONAL_PACKAGES,
|
||||
installedOptionalPackageVersion,
|
||||
@@ -82,18 +87,26 @@ function checkDockerRunning(): CheckResult {
|
||||
}
|
||||
}
|
||||
|
||||
function checkVersion(): CheckResult {
|
||||
export function checkVersion(): CheckResult {
|
||||
const meta = getUpdateMeta();
|
||||
if (meta.updateAvailable && meta.latestVersion) {
|
||||
return {
|
||||
ok: false,
|
||||
detail: `${VERSION} \u2192 ${meta.latestVersion} available`,
|
||||
hint: "Run: hyperframes upgrade",
|
||||
hint: `Run: ${updateCommandFor(runningInstall(), meta.latestVersion)}`,
|
||||
};
|
||||
}
|
||||
if (!meta.latestVersion) return { ok: true, detail: `${VERSION} (not checked yet)` };
|
||||
return { ok: true, detail: `${VERSION} (latest)` };
|
||||
}
|
||||
|
||||
/** Which binary is running and from where: a global install per manager, project-local, npx or a plugin. */
|
||||
export function checkInstall(): CheckResult {
|
||||
const install = runningInstall();
|
||||
const where = install.path ?? "entry path unknown";
|
||||
return { ok: true, detail: `${installChannelLabel(install.channel)} \u00B7 ${where}` };
|
||||
}
|
||||
|
||||
function checkNode(): CheckResult {
|
||||
return { ok: true, detail: `${process.version} (${process.platform} ${process.arch})` };
|
||||
}
|
||||
@@ -380,6 +393,7 @@ export default defineCommand({
|
||||
const environment = await runEnvironmentChecks({ includeBrowser: true });
|
||||
const checks: Check[] = [
|
||||
{ name: "Version", run: checkVersion },
|
||||
{ name: "CLI binary", run: checkInstall },
|
||||
{ name: "Node.js", run: checkNode },
|
||||
{ name: "CPU", run: checkCPU },
|
||||
{ name: "Memory", run: checkMemory },
|
||||
|
||||
@@ -6,7 +6,7 @@ import { c } from "../ui/colors.js";
|
||||
import { diag } from "../ui/diagnostics.js";
|
||||
import { buildNpxCommand } from "../utils/npxCommand.js";
|
||||
import { VERSION } from "../version.js";
|
||||
import { withMeta } from "../utils/updateCheck.js";
|
||||
import { NO_UPDATE_NOTICE, withMeta } from "../utils/updateCheck.js";
|
||||
import {
|
||||
checkSkills,
|
||||
FALLBACK_CORE_SKILLS,
|
||||
@@ -328,12 +328,18 @@ export async function updateSkills(
|
||||
all?: boolean;
|
||||
strict?: boolean;
|
||||
cwd?: string;
|
||||
/**
|
||||
* The CLI version whose release tag to install from (default: this one). `hyperframes
|
||||
* update` passes the version it just upgraded to, so the skills match the CLI that runs next.
|
||||
*/
|
||||
cliVersion?: string;
|
||||
} = {},
|
||||
): Promise<UpdateSkillsResult> {
|
||||
const named = [...new Set(opts.requested ?? [])];
|
||||
const retired = named.filter((name) => RETIRED_SKILLS.includes(name));
|
||||
const requested = named.filter((name) => !retired.includes(name));
|
||||
const strict = opts.strict ?? false;
|
||||
const cliVersion = opts.cliVersion ?? VERSION;
|
||||
|
||||
let check: SkillsCheckResult | null = null;
|
||||
try {
|
||||
@@ -350,7 +356,7 @@ export async function updateSkills(
|
||||
check = await checkSkills({
|
||||
cwd: opts.cwd,
|
||||
canonical: true,
|
||||
cliVersion: VERSION,
|
||||
cliVersion,
|
||||
installTarget: true,
|
||||
});
|
||||
} catch (err) {
|
||||
@@ -378,7 +384,10 @@ export async function updateSkills(
|
||||
),
|
||||
);
|
||||
}
|
||||
return { ...(await updateSkillsOffline(requested, { strict, cwd: opts.cwd })), retired };
|
||||
return {
|
||||
...(await updateSkillsOffline(requested, { strict, cwd: opts.cwd, cliVersion })),
|
||||
retired,
|
||||
};
|
||||
}
|
||||
|
||||
const manifestSkills = check.skills;
|
||||
@@ -469,7 +478,7 @@ function verifyInstalled(names: readonly string[], opts: { strict: boolean; cwd?
|
||||
*/
|
||||
async function updateSkillsOffline(
|
||||
requested: readonly string[],
|
||||
opts: { strict: boolean; cwd?: string },
|
||||
opts: { strict: boolean; cwd?: string; cliVersion: string },
|
||||
): Promise<Omit<UpdateSkillsResult, "retired">> {
|
||||
if (requested.length === 0 && opts.strict) {
|
||||
throw new Error(
|
||||
@@ -502,7 +511,7 @@ async function updateSkillsOffline(
|
||||
await installSkills(absent, {
|
||||
cwd: opts.cwd,
|
||||
strict: opts.strict,
|
||||
ref: cliReleaseTag(VERSION) ?? "main",
|
||||
ref: cliReleaseTag(opts.cliVersion) ?? "main",
|
||||
});
|
||||
verifyInstalled(targets, opts);
|
||||
}
|
||||
@@ -599,7 +608,7 @@ const checkCommand = defineCommand({
|
||||
cliVersion: VERSION,
|
||||
});
|
||||
|
||||
if (args.json) console.log(JSON.stringify(withMeta(result), null, 2));
|
||||
if (args.json) console.log(JSON.stringify(withMeta(result, NO_UPDATE_NOTICE), null, 2));
|
||||
else renderCheck(result);
|
||||
|
||||
// This check just displayed a fresh verdict, superseding whatever the
|
||||
@@ -622,7 +631,7 @@ const checkCommand = defineCommand({
|
||||
* the router's trigger-time `skills update <workflow>` replaces a pinned install
|
||||
* with the latest upstream skills (GH #5695).
|
||||
*/
|
||||
function skillsManagedExternally(): boolean {
|
||||
export function skillsManagedExternally(): boolean {
|
||||
return process.env["HYPERFRAMES_SKIP_SKILLS"] === "1";
|
||||
}
|
||||
|
||||
@@ -634,7 +643,10 @@ function reportSkillsManagedExternally(requested: readonly string[], json: boole
|
||||
if (json) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
withMeta({ skipped: true, reason: SKILLS_MANAGED_EXTERNALLY_NOTICE, requested }),
|
||||
withMeta(
|
||||
{ skipped: true, reason: SKILLS_MANAGED_EXTERNALLY_NOTICE, requested },
|
||||
NO_UPDATE_NOTICE,
|
||||
),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
@@ -669,7 +681,7 @@ function reportUpdate(
|
||||
json: boolean,
|
||||
): void {
|
||||
if (json) {
|
||||
console.log(JSON.stringify(withMeta(result), null, 2));
|
||||
console.log(JSON.stringify(withMeta(result, NO_UPDATE_NOTICE), null, 2));
|
||||
return;
|
||||
}
|
||||
for (const name of result.retired) console.log(c.warn(retiredSkillNotice(name)));
|
||||
@@ -699,7 +711,9 @@ function reportUpdate(
|
||||
*/
|
||||
function reportUpdateFailure(message: string, json: boolean): void {
|
||||
if (json) {
|
||||
console.log(JSON.stringify(withMeta(jsonFailure("runtime_error", message)), null, 2));
|
||||
console.log(
|
||||
JSON.stringify(withMeta(jsonFailure("runtime_error", message), NO_UPDATE_NOTICE), null, 2),
|
||||
);
|
||||
return;
|
||||
}
|
||||
clack.log.error(c.error(message));
|
||||
|
||||
@@ -0,0 +1,346 @@
|
||||
// `hyperframes update`: one forced check of the CLI and the skills, then the
|
||||
// install the way `upgrade --yes` and `skills update` do it. Install detection,
|
||||
// the upgrade argv and the skills install run for real per install channel;
|
||||
// only spawn, the config file, the manifest fetch/disk and the registry are stubbed.
|
||||
|
||||
import { EventEmitter } from "node:events";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
// The package-manager binaries a CLI upgrade runs; npx (cmd.exe on Windows) and git are the skills tooling.
|
||||
const INSTALLERS = vi.hoisted(() => new Set(["npm", "pnpm", "bun", "brew"]));
|
||||
|
||||
const state = vi.hoisted(() => ({
|
||||
config: {} as Record<string, unknown>,
|
||||
execCalls: [] as { command: string; args: readonly string[]; opts: unknown }[],
|
||||
spawnCalls: [] as { command: string; args: readonly string[] }[],
|
||||
installFails: false,
|
||||
registryLatest: "0.9.8" as string | null,
|
||||
// What Homebrew's linked binary reports after `brew upgrade` (null: it cannot be read).
|
||||
brewInstalled: "0.9.8" as string | null,
|
||||
fetchedUrls: [] as string[],
|
||||
}));
|
||||
|
||||
vi.mock("../version.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../version.js")>()),
|
||||
VERSION: "0.9.5",
|
||||
}));
|
||||
|
||||
vi.mock("../telemetry/config.js", () => ({
|
||||
CONFIG_PATH: "/nonexistent/hf-update-test/config.json",
|
||||
readConfig: () => ({ ...state.config }),
|
||||
readConfigFresh: () => ({ ...state.config }),
|
||||
writeConfig: (next: Record<string, unknown>) => {
|
||||
state.config = { ...next };
|
||||
return true;
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("../telemetry/events.js", () => ({ trackSkillsInstallSkipped: vi.fn() }));
|
||||
|
||||
vi.mock("node:child_process", () => ({
|
||||
execFile: vi.fn(),
|
||||
execFileSync: vi.fn((command: string, args: readonly string[], opts: unknown) => {
|
||||
state.execCalls.push({ command, args, opts });
|
||||
if (command === "brew" && args[0] === "--prefix") return "/opt/homebrew/opt/hyperframes\n";
|
||||
if (command.replaceAll("\\", "/") === "/opt/homebrew/opt/hyperframes/bin/hyperframes") {
|
||||
if (state.brewInstalled === null) throw new Error("not linked");
|
||||
return `${state.brewInstalled}\n`;
|
||||
}
|
||||
if (state.installFails && INSTALLERS.has(command)) throw new Error("boom");
|
||||
return Buffer.from("11.0.0");
|
||||
}),
|
||||
spawn: vi.fn((command: string, args: readonly string[]) => {
|
||||
state.spawnCalls.push({ command, args });
|
||||
const child = new EventEmitter();
|
||||
setImmediate(() => child.emit("close", 0, null));
|
||||
return child;
|
||||
}),
|
||||
}));
|
||||
|
||||
const OUTDATED_CHECK = {
|
||||
location: "/home/user/.claude/skills",
|
||||
agent: "claude-code",
|
||||
scope: "global",
|
||||
updateAvailable: true,
|
||||
summary: { current: 1, outdated: 2, missing: 0, coreMissing: 0, removed: 0 },
|
||||
skills: [
|
||||
{ name: "hyperframes", status: "outdated" },
|
||||
{ name: "hyperframes-registry", status: "outdated" },
|
||||
{ name: "figma", status: "current" },
|
||||
],
|
||||
foreign: [],
|
||||
ref: "v0.9.5",
|
||||
};
|
||||
|
||||
vi.mock("../utils/skillsManifest.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../utils/skillsManifest.js")>()),
|
||||
// The manifest is read at the requested CLI version's release tag, as the real check does.
|
||||
checkSkills: vi.fn(async (opts: { cliVersion?: string }) => ({
|
||||
...OUTDATED_CHECK,
|
||||
ref: `v${opts.cliVersion}`,
|
||||
})),
|
||||
hyperframesSkillNames: vi.fn(() => ["hyperframes"]),
|
||||
presentSkills: vi.fn((names: readonly string[]) => [...names]),
|
||||
}));
|
||||
vi.mock("../utils/skillsMirror.js", () => ({
|
||||
mirrorGlobalSkills: vi.fn(() => ({ source: null, mirrored: [], skipped: [] })),
|
||||
}));
|
||||
|
||||
const ENTRIES = {
|
||||
npm: "/usr/local/lib/node_modules/hyperframes/dist/cli.js",
|
||||
pnpm: "/home/me/.local/share/pnpm/global/5/node_modules/hyperframes/dist/cli.js",
|
||||
bun: "/home/me/.bun/install/global/node_modules/hyperframes/dist/cli.js",
|
||||
brew: "/opt/homebrew/Cellar/hyperframes/0.9.5/libexec/lib/node_modules/hyperframes/dist/cli.js",
|
||||
npx: "/home/me/.npm/_npx/4f1c2a/node_modules/hyperframes/dist/cli.js",
|
||||
project: "/home/me/video/node_modules/hyperframes/dist/cli.js",
|
||||
} as const;
|
||||
|
||||
const originalArgv = [...process.argv];
|
||||
let stdout: string[];
|
||||
|
||||
async function runUpdate(entry: string, args: Record<string, unknown>) {
|
||||
process.argv = [process.argv[0] ?? "node", entry];
|
||||
const { default: cmd } = await import("./update.js");
|
||||
await cmd.run?.({ args: { _: [], ...args }, rawArgs: [], cmd } as never);
|
||||
const { consumeCommandResult } = await import("../utils/commandResult.js");
|
||||
return consumeCommandResult().exitCode;
|
||||
}
|
||||
|
||||
const json = () => JSON.parse(stdout.join("\n")) as Record<string, any>;
|
||||
const installs = () =>
|
||||
state.execCalls.filter((c) => INSTALLERS.has(c.command) && c.args[0] !== "--prefix");
|
||||
const skillsAdds = () => state.spawnCalls.filter((c) => c.args.includes("add"));
|
||||
|
||||
beforeEach(() => {
|
||||
vi.resetModules();
|
||||
state.config = {};
|
||||
state.execCalls = [];
|
||||
state.spawnCalls = [];
|
||||
state.installFails = false;
|
||||
state.registryLatest = "0.9.8";
|
||||
state.brewInstalled = "0.9.8";
|
||||
state.fetchedUrls = [];
|
||||
vi.stubGlobal(
|
||||
"fetch",
|
||||
vi.fn(async (url: string) => {
|
||||
state.fetchedUrls.push(String(url));
|
||||
return state.registryLatest
|
||||
? ({ ok: true, json: async () => ({ version: state.registryLatest }) } as Response)
|
||||
: ({ ok: false, status: 503 } as Response);
|
||||
}),
|
||||
);
|
||||
for (const name of [
|
||||
"HYPERFRAMES_PLUGIN_VERSION",
|
||||
"HYPERFRAMES_SKIP_SKILLS",
|
||||
"HYPERFRAMES_AGENT",
|
||||
]) {
|
||||
vi.stubEnv(name, "");
|
||||
}
|
||||
stdout = [];
|
||||
vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => void stdout.push(a.join(" ")));
|
||||
vi.spyOn(console, "error").mockImplementation(() => {});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
process.argv = [...originalArgv];
|
||||
vi.unstubAllGlobals();
|
||||
vi.unstubAllEnvs();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe("hyperframes update --check", () => {
|
||||
it("reports the CLI (fresh from npm, past the cache) and the skills in one JSON call, installing nothing", async () => {
|
||||
// A cache that says "current" and is only minutes old must not answer `update`.
|
||||
state.config = { latestVersion: "0.9.5", lastUpdateCheck: new Date().toISOString() };
|
||||
|
||||
expect(await runUpdate(ENTRIES.npm, { check: true, json: true })).toBe(0);
|
||||
|
||||
const out = json();
|
||||
expect(state.fetchedUrls).toEqual(["https://registry.npmjs.org/hyperframes/latest"]);
|
||||
expect(out.cli).toMatchObject({
|
||||
current: "0.9.5",
|
||||
latest: "0.9.8",
|
||||
updateAvailable: true,
|
||||
install: { channel: "npm", path: ENTRIES.npm },
|
||||
command: "npm install -g hyperframes@0.9.8",
|
||||
});
|
||||
expect(out.cli.checkedAt).toEqual(expect.any(String));
|
||||
expect(out.skills).toMatchObject({
|
||||
status: "checked",
|
||||
ref: "v0.9.5",
|
||||
outdated: 2,
|
||||
updateAvailable: true,
|
||||
// The global CLI runs its own update: `npx hyperframes` could run another copy.
|
||||
command: "hyperframes update",
|
||||
});
|
||||
expect(out._meta).toMatchObject({
|
||||
latestVersion: "0.9.8",
|
||||
updateAvailable: true,
|
||||
skillsOutdated: 2,
|
||||
});
|
||||
expect(installs()).toEqual([]);
|
||||
expect(skillsAdds()).toEqual([]);
|
||||
});
|
||||
|
||||
it("reads the skills manifest at this CLI's release tag", async () => {
|
||||
const { checkSkills } = await import("../utils/skillsManifest.js");
|
||||
await runUpdate(ENTRIES.npm, { check: true, json: true });
|
||||
expect(checkSkills).toHaveBeenCalledWith({ canonical: true, cliVersion: "0.9.5" });
|
||||
});
|
||||
|
||||
it("says when npm was not reached instead of passing the cache off as fresh", async () => {
|
||||
state.registryLatest = null;
|
||||
await runUpdate(ENTRIES.npm, { check: true, json: true });
|
||||
expect(json().cli).toMatchObject({ updateAvailable: false, checkedAt: null });
|
||||
});
|
||||
|
||||
it("does not call the CLI latest when npm was not reached", async () => {
|
||||
state.registryLatest = null;
|
||||
await runUpdate(ENTRIES.npm, { check: true });
|
||||
const text = stdout.join("\n");
|
||||
expect(text).toContain("(npm registry not reached)");
|
||||
expect(text).not.toContain("latest");
|
||||
});
|
||||
|
||||
it.each([
|
||||
["npm", ENTRIES.npm, "npm install -g hyperframes@0.9.8"],
|
||||
["pnpm", ENTRIES.pnpm, "pnpm add -g hyperframes@0.9.8"],
|
||||
["bun", ENTRIES.bun, "bun add -g hyperframes@0.9.8"],
|
||||
["brew", ENTRIES.brew, "brew upgrade hyperframes"],
|
||||
["npx", ENTRIES.npx, "npx hyperframes@latest"],
|
||||
["project", ENTRIES.project, "npm install hyperframes@0.9.8"],
|
||||
])("names the %s install and the command that updates it", async (channel, entry, command) => {
|
||||
await runUpdate(entry, { check: true, json: true });
|
||||
expect(json().cli.install).toEqual({ channel, path: entry });
|
||||
expect(json().cli.command).toBe(command);
|
||||
});
|
||||
|
||||
it("reports a plugin install as plugin-managed, and does not check its pinned skills", async () => {
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "0.9.5");
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
|
||||
const { checkSkills } = await import("../utils/skillsManifest.js");
|
||||
vi.mocked(checkSkills).mockClear();
|
||||
|
||||
expect(await runUpdate(ENTRIES.npx, { check: true, json: true })).toBe(0);
|
||||
|
||||
expect(json().cli.install.channel).toBe("plugin");
|
||||
expect(json().cli.command).toMatch(/plugin/);
|
||||
expect(json().skills.status).toBe("skipped");
|
||||
expect(checkSkills).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("hyperframes update (install)", () => {
|
||||
it("asks for --yes in an unattended run instead of installing", async () => {
|
||||
vi.stubEnv("HYPERFRAMES_AGENT", "1");
|
||||
await expect(runUpdate(ENTRIES.npm, { json: true })).rejects.toThrow(/confirmation/);
|
||||
expect(installs()).toEqual([]);
|
||||
expect(state.fetchedUrls).toEqual([]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["npm", ENTRIES.npm, "npm", ["install", "-g", "hyperframes@0.9.8"]],
|
||||
["pnpm", ENTRIES.pnpm, "pnpm", ["add", "-g", "hyperframes@0.9.8"]],
|
||||
["bun", ENTRIES.bun, "bun", ["add", "-g", "hyperframes@0.9.8"]],
|
||||
// Explicit: the user asked, so brew may move to the formula (unlike auto-update); here it reached npm.
|
||||
["brew", ENTRIES.brew, "brew", ["upgrade", "hyperframes"]],
|
||||
])(
|
||||
"%s: upgrades the CLI like upgrade --yes, then installs the skills at the new CLI's tag",
|
||||
async (_channel, entry, bin, args) => {
|
||||
expect(await runUpdate(entry, { yes: true, json: true })).toBe(0);
|
||||
|
||||
expect(installs()).toHaveLength(1);
|
||||
expect(installs()[0]).toMatchObject({ command: bin, args });
|
||||
// The child's stdout goes to stderr: a --json stdout stays one parseable object.
|
||||
expect(installs()[0]!.opts).toMatchObject({ shell: false, stdio: ["inherit", 2, 2] });
|
||||
expect(skillsAdds()).toHaveLength(1);
|
||||
expect(skillsAdds()[0]!.args).toContain("https://github.com/heygen-com/hyperframes#v0.9.8");
|
||||
expect(json().updated).toMatchObject({
|
||||
cli: { status: "upgraded", version: "0.9.8" },
|
||||
skills: { status: "updated" },
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
["npx", ENTRIES.npx, "npx hyperframes@latest"],
|
||||
// The project's manager moves its dependency, as `--check` names it.
|
||||
["project", ENTRIES.project, "npm install hyperframes@0.9.8"],
|
||||
])(
|
||||
"%s: installs no CLI, names %s, refreshes the skills at its own tag",
|
||||
async (_channel, entry, command) => {
|
||||
expect(await runUpdate(entry, { yes: true, json: true })).toBe(0);
|
||||
expect(installs()).toEqual([]);
|
||||
expect(json().updated.cli).toMatchObject({ status: "manual", command });
|
||||
expect(skillsAdds()[0]!.args).toContain("https://github.com/heygen-com/hyperframes#v0.9.5");
|
||||
},
|
||||
);
|
||||
|
||||
// `brew upgrade` installs the formula's version, which lags npm, and exits 0 on a no-op: the
|
||||
// skills must follow the CLI that is actually installed, never npm's latest.
|
||||
it("brew staying behind npm: reports the CLI unchanged and keeps the skills at its own tag", async () => {
|
||||
state.brewInstalled = "0.9.5";
|
||||
expect(await runUpdate(ENTRIES.brew, { yes: true, json: true })).toBe(0);
|
||||
|
||||
expect(json().updated.cli).toMatchObject({ status: "unchanged", version: "0.9.5" });
|
||||
expect(json().updated.cli.reason).toContain("0.9.8");
|
||||
const adds = skillsAdds().flatMap((c) => c.args);
|
||||
expect(adds).not.toContain("https://github.com/heygen-com/hyperframes#v0.9.8");
|
||||
expect(adds).toContain("https://github.com/heygen-com/hyperframes#v0.9.5");
|
||||
});
|
||||
|
||||
it("brew moving to a formula between the two: skills at the version brew installed", async () => {
|
||||
state.brewInstalled = "0.9.7";
|
||||
expect(await runUpdate(ENTRIES.brew, { yes: true, json: true })).toBe(0);
|
||||
expect(json().updated.cli).toMatchObject({ status: "upgraded", version: "0.9.7" });
|
||||
expect(skillsAdds()[0]!.args).toContain("https://github.com/heygen-com/hyperframes#v0.9.7");
|
||||
});
|
||||
|
||||
it("brew whose installed version cannot be read: says so and keeps the skills at this CLI's tag", async () => {
|
||||
state.brewInstalled = null;
|
||||
expect(await runUpdate(ENTRIES.brew, { yes: true, json: true })).toBe(0);
|
||||
expect(json().updated.cli).toMatchObject({ status: "unverified" });
|
||||
expect(skillsAdds()[0]!.args).toContain("https://github.com/heygen-com/hyperframes#v0.9.5");
|
||||
});
|
||||
|
||||
it("plugin: refuses, installing neither the CLI nor the skills", async () => {
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "0.9.5");
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
|
||||
expect(await runUpdate(ENTRIES.npx, { yes: true, json: true })).toBe(1);
|
||||
expect(json()).toMatchObject({ ok: false, error: { code: "plugin_managed" } });
|
||||
expect(installs()).toEqual([]);
|
||||
expect(skillsAdds()).toEqual([]);
|
||||
expect(state.fetchedUrls).toEqual([]);
|
||||
});
|
||||
|
||||
it("HYPERFRAMES_SKIP_SKILLS leaves the skills alone while the CLI still updates", async () => {
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
|
||||
expect(await runUpdate(ENTRIES.npm, { yes: true, json: true })).toBe(0);
|
||||
expect(installs()).toHaveLength(1);
|
||||
expect(skillsAdds()).toEqual([]);
|
||||
expect(json().updated.skills.status).toBe("skipped");
|
||||
});
|
||||
|
||||
it("a failed CLI install exits 1 and says what to run", async () => {
|
||||
state.installFails = true;
|
||||
expect(await runUpdate(ENTRIES.npm, { yes: true, json: true })).toBe(1);
|
||||
expect(json().updated.cli).toMatchObject({
|
||||
status: "failed",
|
||||
command: "npm install -g hyperframes@0.9.8",
|
||||
});
|
||||
});
|
||||
|
||||
it("installs nothing when the CLI and its skills are current", async () => {
|
||||
state.registryLatest = "0.9.5";
|
||||
const { checkSkills } = await import("../utils/skillsManifest.js");
|
||||
vi.mocked(checkSkills).mockResolvedValueOnce({
|
||||
...OUTDATED_CHECK,
|
||||
updateAvailable: false,
|
||||
summary: { ...OUTDATED_CHECK.summary, outdated: 0, current: 3 },
|
||||
} as never);
|
||||
expect(await runUpdate(ENTRIES.npm, { yes: true, json: true })).toBe(0);
|
||||
expect(installs()).toEqual([]);
|
||||
expect(skillsAdds()).toEqual([]);
|
||||
expect(json().updated).toEqual({ cli: { status: "current" }, skills: { status: "current" } });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,298 @@
|
||||
import { setCommandExitCode } from "../utils/commandResult.js";
|
||||
import { defineCommand } from "../utils/defineCommand.js";
|
||||
import type { Example } from "./_examples.js";
|
||||
import * as clack from "../ui/prompts.js";
|
||||
import { c } from "../ui/colors.js";
|
||||
import { readConfigFresh } from "../telemetry/config.js";
|
||||
import { isUnattended } from "../utils/attendedTerminal.js";
|
||||
import { failureMessage, jsonFailure } from "../utils/jsonError.js";
|
||||
import {
|
||||
installChannelLabel,
|
||||
runningInstall,
|
||||
updateCommandFor,
|
||||
type InstallChannel,
|
||||
} from "../utils/installerDetection.js";
|
||||
import { checkSkills } from "../utils/skillsManifest.js";
|
||||
import { recordSkillsCheck } from "../utils/skillsUpdateCheck.js";
|
||||
import {
|
||||
checkForUpdate,
|
||||
NO_UPDATE_NOTICE,
|
||||
updateCommandForThisInstall,
|
||||
withMeta,
|
||||
} from "../utils/updateCheck.js";
|
||||
import { VERSION } from "../version.js";
|
||||
import { skillsManagedExternally, updateSkills, type UpdateSkillsResult } from "./skills.js";
|
||||
import { upgradeRunningCli, type CliUpgradeOutcome } from "./upgrade.js";
|
||||
|
||||
export const examples: Example[] = [
|
||||
["Check the CLI and the skills for updates in one call", "hyperframes update --check"],
|
||||
["The same check, machine-readable (for agents)", "hyperframes update --check --json"],
|
||||
["Update the CLI and the skills without prompting", "hyperframes update --yes"],
|
||||
];
|
||||
|
||||
const PLUGIN_REASON =
|
||||
"This CLI runs from an agent plugin, which pins the CLI and its skills; update the plugin through your agent's plugin manager.";
|
||||
|
||||
interface CliReport {
|
||||
current: string;
|
||||
latest: string;
|
||||
updateAvailable: boolean;
|
||||
/** When the registry answered this run; null when it did not (latest is then the cached value). */
|
||||
checkedAt: string | null;
|
||||
install: { channel: InstallChannel; path: string | null };
|
||||
/** What moves this install to `latest`; null when already current. */
|
||||
command: string | null;
|
||||
}
|
||||
|
||||
type SkillsReport =
|
||||
| {
|
||||
status: "checked";
|
||||
/** Repo ref the manifest was read at: this CLI's release tag, or main for a dev build. */
|
||||
ref: string | null;
|
||||
location: string | null;
|
||||
updateAvailable: boolean;
|
||||
outdated: number;
|
||||
missing: number;
|
||||
command: string | null;
|
||||
}
|
||||
| { status: "skipped"; reason: string }
|
||||
| { status: "error"; error: string };
|
||||
|
||||
interface UpdateOutcome {
|
||||
cli: CliUpgradeOutcome | { status: "current" };
|
||||
skills:
|
||||
| { status: "updated"; result: UpdateSkillsResult }
|
||||
| { status: "current" }
|
||||
| { status: "skipped"; reason: string }
|
||||
| { status: "failed"; error: string };
|
||||
}
|
||||
|
||||
/** One forced registry check (no cache, no opt-out), reported with where this binary runs from. */
|
||||
async function checkCli(): Promise<CliReport> {
|
||||
const startedAt = Date.now();
|
||||
const result = await checkForUpdate(true);
|
||||
const stamp = readConfigFresh().lastUpdateCheck;
|
||||
const checkedAt = stamp && new Date(stamp).getTime() >= startedAt - 1000 ? stamp : null;
|
||||
const install = runningInstall();
|
||||
return {
|
||||
current: result.current,
|
||||
latest: result.latest,
|
||||
updateAvailable: result.updateAvailable,
|
||||
checkedAt,
|
||||
install,
|
||||
command: result.updateAvailable ? updateCommandFor(install, result.latest) : null,
|
||||
};
|
||||
}
|
||||
|
||||
function skillsSkipReason(channel: InstallChannel): string | null {
|
||||
if (channel === "plugin") return PLUGIN_REASON;
|
||||
if (skillsManagedExternally()) {
|
||||
return "HYPERFRAMES_SKIP_SKILLS=1: skills are managed externally.";
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/** The skills check `skills update` would act on (manifest at this CLI's release tag), cached for `_meta`. */
|
||||
async function checkInstalledSkills(cli: CliReport): Promise<SkillsReport> {
|
||||
const skip = skillsSkipReason(cli.install.channel);
|
||||
if (skip) return { status: "skipped", reason: skip };
|
||||
try {
|
||||
const result = await checkSkills({ canonical: true, cliVersion: VERSION });
|
||||
recordSkillsCheck(result);
|
||||
return {
|
||||
status: "checked",
|
||||
ref: result.ref,
|
||||
location: result.location,
|
||||
updateAvailable: result.updateAvailable,
|
||||
outdated: result.summary.outdated,
|
||||
missing: result.summary.coreMissing,
|
||||
// The command `_meta.updateNotice` names, for both halves: it moves this install.
|
||||
command: result.updateAvailable
|
||||
? updateCommandForThisInstall(cli.updateAvailable, true, cli.latest)
|
||||
: null,
|
||||
};
|
||||
} catch (err) {
|
||||
return { status: "error", error: failureMessage(err) };
|
||||
}
|
||||
}
|
||||
|
||||
/** The CLI half. A project-local CLI is moved by its project's manager: name that, as `--check` does. */
|
||||
function upgradeCli(cli: CliReport): UpdateOutcome["cli"] {
|
||||
if (!cli.updateAvailable) return { status: "current" };
|
||||
const upgrade = upgradeRunningCli(cli.latest);
|
||||
return upgrade.status === "manual" && cli.command
|
||||
? { ...upgrade, command: cli.command }
|
||||
: upgrade;
|
||||
}
|
||||
|
||||
/** Upgrade the CLI the way `upgrade --yes` does, then refresh the skills at the tag of the CLI that runs next. */
|
||||
async function applyUpdate(cli: CliReport, skills: SkillsReport): Promise<UpdateOutcome> {
|
||||
const cliOutcome = upgradeCli(cli);
|
||||
if (skills.status === "skipped") return { cli: cliOutcome, skills };
|
||||
// Still on this CLI and its skills already match its tag: nothing to install.
|
||||
if (cliOutcome.status !== "upgraded" && skills.status === "checked" && !skills.updateAvailable) {
|
||||
return { cli: cliOutcome, skills: { status: "current" } };
|
||||
}
|
||||
// The skills follow the CLI that is installed now, which a brew upgrade may leave short of npm's.
|
||||
const cliVersion = cliOutcome.status === "upgraded" ? cliOutcome.version : VERSION;
|
||||
try {
|
||||
const result = await updateSkills({ refreshInstalled: true, strict: true, cliVersion });
|
||||
return { cli: cliOutcome, skills: { status: "updated", result } };
|
||||
} catch (err) {
|
||||
return { cli: cliOutcome, skills: { status: "failed", error: failureMessage(err) } };
|
||||
}
|
||||
}
|
||||
|
||||
function printCheck(cli: CliReport, skills: SkillsReport): void {
|
||||
const where = `${installChannelLabel(cli.install.channel)}${cli.install.path ? ` · ${cli.install.path}` : ""}`;
|
||||
console.log();
|
||||
console.log(c.bold("hyperframes update"));
|
||||
console.log();
|
||||
const version = cli.updateAvailable
|
||||
? c.warn(`${cli.current} → ${cli.latest} available`)
|
||||
: c.success(`${cli.current} (${cli.checkedAt ? "latest" : "npm registry not reached"})`);
|
||||
console.log(` ${c.bold("CLI".padEnd(8))}${version}`);
|
||||
console.log(` ${" ".repeat(8)}${c.dim(where)}`);
|
||||
if (cli.command) console.log(` ${" ".repeat(8)}${c.accent(`Run: ${cli.command}`)}`);
|
||||
console.log(` ${c.bold("Skills".padEnd(8))}${skillsLine(skills)}`);
|
||||
if (skills.status === "checked" && skills.command) {
|
||||
console.log(` ${" ".repeat(8)}${c.accent(`Run: ${skills.command}`)}`);
|
||||
}
|
||||
console.log();
|
||||
}
|
||||
|
||||
function skillsLine(skills: SkillsReport): string {
|
||||
if (skills.status === "skipped") return c.dim(skills.reason);
|
||||
if (skills.status === "error") return c.warn(`Could not check: ${skills.error}`);
|
||||
if (!skills.location) return c.warn("No HyperFrames skills installed");
|
||||
const at = skills.ref ? ` at ${skills.ref}` : "";
|
||||
if (!skills.updateAvailable) return c.success(`Up to date${at} · ${skills.location}`);
|
||||
return c.warn(
|
||||
`${skills.outdated} outdated, ${skills.missing} core missing${at} · ${skills.location}`,
|
||||
);
|
||||
}
|
||||
|
||||
function cliOutcomeLine(cli: UpdateOutcome["cli"]): string {
|
||||
switch (cli.status) {
|
||||
case "upgraded":
|
||||
return c.success(`CLI upgraded to v${cli.version}.`);
|
||||
case "unchanged":
|
||||
return c.warn(`CLI stays at v${cli.version}: ${cli.reason}.`);
|
||||
case "unverified":
|
||||
return c.warn(`CLI: ran ${cli.command}, but ${cli.reason}.`);
|
||||
case "manual":
|
||||
return c.warn(`CLI: run ${cli.command} (${cli.reason}).`);
|
||||
case "failed":
|
||||
return c.error(`CLI upgrade failed. Run: ${cli.command}`);
|
||||
default:
|
||||
return c.success("CLI is up to date.");
|
||||
}
|
||||
}
|
||||
|
||||
function printOutcome(outcome: UpdateOutcome): void {
|
||||
const { skills } = outcome;
|
||||
console.log(cliOutcomeLine(outcome.cli));
|
||||
if (skills.status === "updated") {
|
||||
const n = skills.result.installed.length;
|
||||
console.log(
|
||||
c.success(
|
||||
n > 0
|
||||
? `Updated ${n} skill(s): ${skills.result.installed.join(", ")}`
|
||||
: "Skills are up to date.",
|
||||
),
|
||||
);
|
||||
} else if (skills.status === "current") {
|
||||
console.log(c.success("Skills are up to date."));
|
||||
} else if (skills.status === "failed") {
|
||||
console.log(c.error(`Skills update failed: ${skills.error}`));
|
||||
} else {
|
||||
console.log(c.dim(skills.reason));
|
||||
}
|
||||
}
|
||||
|
||||
interface Mode {
|
||||
json: boolean;
|
||||
yes: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether this run may install. A plugin install refuses (exit 1): the plugin pins the CLI and
|
||||
* its skills. A run that cannot prompt needs --yes, like `upgrade` (exit 2 otherwise).
|
||||
*/
|
||||
function installAllowed(channel: InstallChannel, mode: Mode): boolean {
|
||||
if (channel === "plugin") {
|
||||
if (mode.json) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
withMeta(jsonFailure("plugin_managed", PLUGIN_REASON), NO_UPDATE_NOTICE),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
} else {
|
||||
clack.log.error(c.error(PLUGIN_REASON));
|
||||
}
|
||||
setCommandExitCode(1);
|
||||
return false;
|
||||
}
|
||||
if (!mode.yes && (mode.json || isUnattended())) {
|
||||
clack.confirmationRequired(
|
||||
"hyperframes update",
|
||||
"Updating is the person's call; `update --check` only reports.",
|
||||
);
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/** An attended run without --yes confirms first, and only when there is something to install. */
|
||||
async function confirmed(cli: CliReport, skills: SkillsReport, mode: Mode): Promise<boolean> {
|
||||
const pending = cli.updateAvailable || (skills.status === "checked" && skills.updateAvailable);
|
||||
if (mode.yes || mode.json || !pending) return true;
|
||||
const go = await clack.confirm({ message: "Update now?" });
|
||||
if (clack.isCancel(go) || go !== true) {
|
||||
clack.outro(c.dim("Skipped."));
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
async function installUpdates(cli: CliReport, skills: SkillsReport, mode: Mode): Promise<void> {
|
||||
if (!mode.json) printCheck(cli, skills);
|
||||
if (!(await confirmed(cli, skills, mode))) return;
|
||||
const outcome = await applyUpdate(cli, skills);
|
||||
if (mode.json)
|
||||
console.log(
|
||||
JSON.stringify(withMeta({ cli, skills, updated: outcome }, NO_UPDATE_NOTICE), null, 2),
|
||||
);
|
||||
else printOutcome(outcome);
|
||||
if (outcome.cli.status === "failed" || outcome.skills.status === "failed") {
|
||||
setCommandExitCode(1);
|
||||
}
|
||||
}
|
||||
|
||||
export default defineCommand({
|
||||
meta: {
|
||||
name: "update",
|
||||
description: "Check the CLI and the skills for updates in one call, and install them",
|
||||
},
|
||||
args: {
|
||||
check: { type: "boolean", description: "Only report what is outdated; install nothing" },
|
||||
yes: { type: "boolean", alias: "y", description: "Update without prompting" },
|
||||
json: { type: "boolean", description: "Output as JSON", default: false },
|
||||
},
|
||||
async run({ args }) {
|
||||
const mode: Mode = { json: args.json === true, yes: args.yes === true };
|
||||
const install = runningInstall();
|
||||
if (args.check !== true && !installAllowed(install.channel, mode)) return;
|
||||
|
||||
const cli = await checkCli();
|
||||
const skills = await checkInstalledSkills(cli);
|
||||
if (args.check === true) {
|
||||
if (mode.json)
|
||||
console.log(JSON.stringify(withMeta({ cli, skills }, NO_UPDATE_NOTICE), null, 2));
|
||||
else printCheck(cli, skills);
|
||||
return;
|
||||
}
|
||||
await installUpdates(cli, skills, mode);
|
||||
},
|
||||
});
|
||||
@@ -0,0 +1,100 @@
|
||||
import { mkdtempSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
// The commands whose own output is about updating (`upgrade`, `skills`) never add
|
||||
// `_meta.updateNotice`, as `cli.ts` keeps the stderr notices away from them; a notice there
|
||||
// would contradict the result it sits on.
|
||||
const state = vi.hoisted(() => ({ dir: "" }));
|
||||
const config = () => ({
|
||||
lastUpdateCheck: new Date().toISOString(),
|
||||
latestVersion: "999.0.0",
|
||||
});
|
||||
|
||||
vi.mock("../utils/env.js", () => ({ isDevMode: () => false }));
|
||||
vi.mock("../telemetry/config.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../telemetry/config.js")>()),
|
||||
get CONFIG_PATH() {
|
||||
return join(state.dir, "config.json");
|
||||
},
|
||||
readConfig: () => config(),
|
||||
readConfigFresh: () => config(),
|
||||
writeConfig: () => true,
|
||||
}));
|
||||
vi.mock("../utils/skillsManifest.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("../utils/skillsManifest.js")>()),
|
||||
checkSkills: vi.fn(async () => ({
|
||||
location: "/home/me/.agents/skills",
|
||||
agent: null,
|
||||
scope: "global",
|
||||
foreign: [],
|
||||
ref: "v0.9.6",
|
||||
updateAvailable: false,
|
||||
skills: [],
|
||||
summary: { outdated: 0, missing: 0, coreMissing: 0, current: 0 },
|
||||
})),
|
||||
}));
|
||||
|
||||
let stdout: string[] = [];
|
||||
|
||||
beforeEach(() => {
|
||||
state.dir = mkdtempSync(join(tmpdir(), "hf-notice-commands-"));
|
||||
vi.stubEnv("CI", "");
|
||||
vi.stubEnv("HYPERFRAMES_NO_UPDATE_CHECK", "");
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "");
|
||||
vi.stubGlobal(
|
||||
"fetch",
|
||||
vi.fn(async () => new Response(JSON.stringify({ version: "999.0.0" }))),
|
||||
);
|
||||
stdout = [];
|
||||
vi.spyOn(console, "log").mockImplementation((line: unknown) => {
|
||||
stdout.push(String(line));
|
||||
});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
vi.unstubAllEnvs();
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
const meta = () => (JSON.parse(stdout.join("\n")) as { _meta: Record<string, unknown> })._meta;
|
||||
|
||||
/** citty's `Resolvable`: a value, a promise of it, or a function returning either. */
|
||||
async function resolve<T>(value: T | Promise<T> | (() => T | Promise<T>)): Promise<T> {
|
||||
return typeof value === "function" ? (value as () => T | Promise<T>)() : value;
|
||||
}
|
||||
|
||||
async function run(path: string, args: Record<string, unknown>) {
|
||||
const { default: cmd } = await import(path);
|
||||
await cmd.run({ args: { _: [], ...args }, rawArgs: [], cmd });
|
||||
}
|
||||
|
||||
describe("_meta.updateNotice on update-related commands", () => {
|
||||
it("is due here: a plain withMeta in the same state carries it", async () => {
|
||||
const { withMeta } = await import("../utils/updateCheck.js");
|
||||
expect(withMeta({ ok: true })._meta.updateNotice).toMatch(/999\.0\.0/);
|
||||
});
|
||||
|
||||
it("is absent from upgrade --json, which reports the same update", async () => {
|
||||
await run("./upgrade.js", { json: true });
|
||||
expect(meta()).toMatchObject({ updateAvailable: true, latestVersion: "999.0.0" });
|
||||
expect("updateNotice" in meta()).toBe(false);
|
||||
});
|
||||
|
||||
it("is absent from upgrade --project --json", async () => {
|
||||
await run("./upgrade.js", { json: true, project: state.dir, check: true });
|
||||
expect("updateNotice" in meta()).toBe(false);
|
||||
});
|
||||
|
||||
it("is absent from skills check --json, which reports the skills itself", async () => {
|
||||
const { default: skills } = await import("./skills.js");
|
||||
const subs = await resolve(skills.subCommands);
|
||||
const check = await resolve(subs?.["check"]);
|
||||
if (!check) throw new Error("skills check not found");
|
||||
await check.run?.({ args: { _: [], json: true }, rawArgs: [], cmd: check } as never);
|
||||
expect(meta().updateAvailable).toBe(true);
|
||||
expect("updateNotice" in meta()).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -4,7 +4,7 @@ import type { Example } from "./_examples.js";
|
||||
import * as clack from "../ui/prompts.js";
|
||||
import { execFileSync } from "node:child_process";
|
||||
import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync } from "node:fs";
|
||||
import { resolve } from "node:path";
|
||||
import { join, resolve } from "node:path";
|
||||
import { c } from "../ui/colors.js";
|
||||
import { isUnattended } from "../utils/attendedTerminal.js";
|
||||
import { rewritePinnedHyperframesText, rewriteProjectPinnedScripts } from "../utils/projectPin.js";
|
||||
@@ -18,11 +18,16 @@ export const examples: Example[] = [
|
||||
import { VERSION } from "../version.js";
|
||||
import {
|
||||
checkForUpdate,
|
||||
NO_UPDATE_NOTICE,
|
||||
withMeta,
|
||||
isSafeVersion,
|
||||
type UpdateCheckResult,
|
||||
} from "../utils/updateCheck.js";
|
||||
import { detectInstaller, installInvocation } from "../utils/installerDetection.js";
|
||||
import {
|
||||
detectInstaller,
|
||||
installInvocation,
|
||||
type InstallInvocation,
|
||||
} from "../utils/installerDetection.js";
|
||||
|
||||
export default defineCommand({
|
||||
meta: { name: "upgrade", description: "Check for updates and show upgrade instructions" },
|
||||
@@ -45,7 +50,7 @@ export default defineCommand({
|
||||
const p = resolveProjectArgs(args.project, { check: checkOnly, json: useJson });
|
||||
const res = await upgradeProjectPins(resolve(p.dir), { json: p.json, check: p.check });
|
||||
if (p.json) {
|
||||
console.log(JSON.stringify(withMeta(res), null, 2));
|
||||
console.log(JSON.stringify(withMeta(res, NO_UPDATE_NOTICE), null, 2));
|
||||
return;
|
||||
}
|
||||
printProjectPinResult(res, p.check);
|
||||
@@ -55,7 +60,7 @@ export default defineCommand({
|
||||
// JSON mode: always force-check and output structured data
|
||||
if (useJson) {
|
||||
const result = await checkForUpdate(true);
|
||||
console.log(JSON.stringify(withMeta(result), null, 2));
|
||||
console.log(JSON.stringify(withMeta(result, NO_UPDATE_NOTICE), null, 2));
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -124,24 +129,93 @@ function applyUpgrade(result: UpdateCheckResult, autoYes: boolean): void {
|
||||
return;
|
||||
}
|
||||
|
||||
const installer = detectInstaller();
|
||||
const invocation = installInvocation(installer.kind, result.latest);
|
||||
const displayCmd = installer.installCommand(result.latest);
|
||||
const npxFallback = `npx hyperframes@${result.latest}`;
|
||||
|
||||
// Undetectable / ephemeral (npx, bunx) / project-local / workspace: don't
|
||||
// guess a manager command; point at the universal npx fallback instead.
|
||||
if (!invocation || !displayCmd) {
|
||||
printNpxFallback(installer.reason, npxFallback, autoYes);
|
||||
const plan = upgradePlan(result.latest);
|
||||
if ("manual" in plan) {
|
||||
printNpxFallback(plan.reason, plan.manual, autoYes);
|
||||
return;
|
||||
}
|
||||
|
||||
if (!autoYes) {
|
||||
printManualCommands(displayCmd, npxFallback);
|
||||
printManualCommands(plan.displayCmd, `npx hyperframes@${result.latest}`);
|
||||
return;
|
||||
}
|
||||
|
||||
runDetectedInstall(invocation, displayCmd, result.latest);
|
||||
runDetectedInstall(plan.invocation, plan.displayCmd, result.latest);
|
||||
}
|
||||
|
||||
const NPX_LATEST = "npx hyperframes@latest";
|
||||
|
||||
/**
|
||||
* How `upgrade --yes` moves this install to `latest`: the detected manager's argv, or, for an
|
||||
* install no manager owns (npx/bunx, project-local, workspace, unknown), the npx line to run
|
||||
* instead of a guessed manager command.
|
||||
*/
|
||||
function upgradePlan(
|
||||
latest: string,
|
||||
):
|
||||
| { invocation: InstallInvocation; displayCmd: string; pinsVersion: boolean }
|
||||
| { manual: string; reason: string } {
|
||||
const installer = detectInstaller();
|
||||
const invocation = installInvocation(installer.kind, latest);
|
||||
const displayCmd = installer.installCommand(latest);
|
||||
if (!invocation || !displayCmd) return { manual: NPX_LATEST, reason: installer.reason };
|
||||
return { invocation, displayCmd, pinsVersion: installer.kind !== "brew" };
|
||||
}
|
||||
|
||||
export type CliUpgradeOutcome =
|
||||
| { status: "upgraded"; version: string; command: string }
|
||||
| { status: "unchanged"; version: string; command: string; reason: string }
|
||||
| { status: "unverified"; command: string; reason: string }
|
||||
| { status: "manual"; command: string; reason: string }
|
||||
| { status: "failed"; command: string };
|
||||
|
||||
/** The version Homebrew's linked `hyperframes` reports, or null when it cannot be read. */
|
||||
function brewInstalledVersion(): string | null {
|
||||
try {
|
||||
const prefix = execFileSync("brew", ["--prefix", "hyperframes"], {
|
||||
encoding: "utf8",
|
||||
stdio: ["ignore", "pipe", "ignore"],
|
||||
shell: false,
|
||||
}).trim();
|
||||
const version = execFileSync(join(prefix, "bin", "hyperframes"), ["--version"], {
|
||||
encoding: "utf8",
|
||||
stdio: ["ignore", "pipe", "ignore"],
|
||||
shell: false,
|
||||
env: { ...process.env, HYPERFRAMES_NO_UPDATE_CHECK: "1", HYPERFRAMES_NO_TELEMETRY: "1" },
|
||||
}).trim();
|
||||
return isSafeVersion(version) ? version : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* `upgrade --yes` without its prose, for `hyperframes update`: the same plan and argv, and the
|
||||
* installer's output goes to stderr so a --json stdout stays one parseable object.
|
||||
*/
|
||||
export function upgradeRunningCli(latest: string): CliUpgradeOutcome {
|
||||
if (!isSafeVersion(latest)) return { status: "failed", command: NPX_LATEST };
|
||||
const plan = upgradePlan(latest);
|
||||
if ("manual" in plan) return { status: "manual", command: plan.manual, reason: plan.reason };
|
||||
try {
|
||||
execFileSync(plan.invocation.bin, plan.invocation.args, {
|
||||
stdio: ["inherit", 2, 2],
|
||||
shell: false,
|
||||
});
|
||||
} catch {
|
||||
return { status: "failed", command: plan.displayCmd };
|
||||
}
|
||||
// `brew upgrade` installs whatever the formula pins, which can lag npm, and exits 0 on a no-op.
|
||||
const installed = plan.pinsVersion ? latest : brewInstalledVersion();
|
||||
const command = plan.displayCmd;
|
||||
if (installed === null) {
|
||||
return { status: "unverified", command, reason: "the installed version could not be read" };
|
||||
}
|
||||
if (installed === VERSION) {
|
||||
const reason = `${command} left ${installed} in place; npm has ${latest}`;
|
||||
return { status: "unchanged", version: installed, command, reason };
|
||||
}
|
||||
return { status: "upgraded", version: installed, command };
|
||||
}
|
||||
|
||||
function printNpxFallback(reason: string, npxFallback: string, autoYes: boolean): void {
|
||||
|
||||
@@ -85,6 +85,7 @@ const GROUPS: Group[] = [
|
||||
["doctor", "Check system dependencies and environment"],
|
||||
["clean", "Find and remove what HyperFrames left on disk"],
|
||||
["upgrade", "Check for updates and show upgrade instructions"],
|
||||
["update", "Check the CLI and the skills for updates in one call, and install them"],
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -503,8 +503,10 @@ export interface HyperframesConfig {
|
||||
/** True after the result has been surfaced once to the user. */
|
||||
reported?: boolean;
|
||||
};
|
||||
/** ISO timestamp of the last `skills check` freshness check (24h cache). */
|
||||
/** ISO timestamp of the last `skills check` freshness check (2h cache). */
|
||||
lastSkillsCheck?: string;
|
||||
/** The CLI version that check ran under: it compared against that version's release tag. */
|
||||
skillsCheckedVersion?: string;
|
||||
/** Whether installed skills were stale at the last check. */
|
||||
skillsUpdateAvailable?: boolean;
|
||||
/** How many installed skills were outdated at the last check. */
|
||||
@@ -739,6 +741,7 @@ function passthroughFields(parsed: Partial<HyperframesConfig>): Partial<Hyperfra
|
||||
pendingUpdate: parsed.pendingUpdate,
|
||||
completedUpdate: parsed.completedUpdate,
|
||||
lastSkillsCheck: parsed.lastSkillsCheck,
|
||||
skillsCheckedVersion: parsed.skillsCheckedVersion,
|
||||
skillsUpdateAvailable: parsed.skillsUpdateAvailable,
|
||||
skillsOutdatedCount: parsed.skillsOutdatedCount,
|
||||
skillsMissingCount: parsed.skillsMissingCount,
|
||||
|
||||
@@ -94,6 +94,23 @@ describe("launchBackgroundChecks", () => {
|
||||
expect(spawnedChecks()).toEqual(["update", "skills"]);
|
||||
});
|
||||
|
||||
it("refreshes both caches once they are 3 hours old, and leaves 1-hour-old ones alone", () => {
|
||||
const at = (hours: number) => new Date(Date.now() - hours * 60 * 60 * 1000).toISOString();
|
||||
const caches = (hours: number) => ({
|
||||
lastUpdateCheck: at(hours),
|
||||
latestVersion: "1.0.0",
|
||||
lastSkillsCheck: at(hours),
|
||||
skillsCheckedVersion: "0.0.0-dev",
|
||||
});
|
||||
disk.config = caches(1);
|
||||
launchBackgroundChecks();
|
||||
expect(spawn).not.toHaveBeenCalled();
|
||||
|
||||
disk.config = caches(3);
|
||||
launchBackgroundChecks();
|
||||
expect(spawnedChecks()).toEqual(["update", "skills"]);
|
||||
});
|
||||
|
||||
it("ignores an attempt stamp dated in the future, as after a clock correction", () => {
|
||||
const later = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
|
||||
disk.config = { lastUpdateAttemptAt: later, lastSkillsAttemptAt: later };
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
import { chmodSync, mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const state = vi.hoisted(() => ({ dir: "" }));
|
||||
vi.mock("../telemetry/config.js", () => ({
|
||||
get CONFIG_PATH() {
|
||||
return join(state.dir, "config.json");
|
||||
},
|
||||
}));
|
||||
|
||||
import { claimDailyNotice } from "./dailyNotice.js";
|
||||
|
||||
const NOW = Date.parse("2026-11-04T08:00:00Z");
|
||||
const HOUR = 3_600_000;
|
||||
const noticeFile = () => join(state.dir, "update-notice.json");
|
||||
const recorded = () => JSON.parse(readFileSync(noticeFile(), "utf-8")) as Record<string, number>;
|
||||
|
||||
beforeEach(() => {
|
||||
state.dir = mkdtempSync(join(tmpdir(), "hf-daily-notice-"));
|
||||
});
|
||||
|
||||
describe("claimDailyNotice", () => {
|
||||
it("claims once a day per project, and each project has its own day", () => {
|
||||
expect(claimDailyNotice("update", "/work/a", NOW)).toBe(true);
|
||||
expect(claimDailyNotice("update", "/work/a", NOW + HOUR)).toBe(false);
|
||||
expect(claimDailyNotice("update", "/work/b", NOW + HOUR)).toBe(true);
|
||||
expect(claimDailyNotice("update", "/work/a", NOW + 25 * HOUR)).toBe(true);
|
||||
});
|
||||
|
||||
it("keeps each kind of notice apart", () => {
|
||||
expect(claimDailyNotice("skills", "/work/a", NOW)).toBe(true);
|
||||
expect(claimDailyNotice("update", "/work/a", NOW)).toBe(true);
|
||||
});
|
||||
|
||||
it.each([["null"], ["[1, 2]"], ['"text"'], ["42"], ["{not json"]])(
|
||||
"reads a %s file as no showings, and repairs it on write",
|
||||
(content) => {
|
||||
writeFileSync(noticeFile(), content);
|
||||
expect(claimDailyNotice("update", "/work/a", NOW)).toBe(true);
|
||||
expect(recorded()).toEqual({ "/work/a": NOW });
|
||||
},
|
||||
);
|
||||
|
||||
it("drops entries that are not times", () => {
|
||||
writeFileSync(noticeFile(), JSON.stringify({ "/work/b": "soon", "/work/c": NOW - HOUR }));
|
||||
expect(claimDailyNotice("update", "/work/a", NOW)).toBe(true);
|
||||
expect(recorded()).toEqual({ "/work/c": NOW - HOUR, "/work/a": NOW });
|
||||
});
|
||||
|
||||
// A clock that moved back (or a hand-edited file) must not silence the notice for good.
|
||||
it("treats a showing in the future as stale, and does not keep it", () => {
|
||||
writeFileSync(
|
||||
noticeFile(),
|
||||
JSON.stringify({ "/work/a": NOW + 48 * HOUR, "/work/b": NOW + HOUR }),
|
||||
);
|
||||
expect(claimDailyNotice("update", "/work/a", NOW)).toBe(true);
|
||||
expect(recorded()).toEqual({ "/work/a": NOW });
|
||||
});
|
||||
|
||||
it.skipIf(process.platform === "win32")("writes the file private to the user", () => {
|
||||
claimDailyNotice("update", "/work/a", NOW);
|
||||
expect(statSync(noticeFile()).mode & 0o777).toBe(0o600);
|
||||
});
|
||||
|
||||
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
|
||||
"returns false, without throwing, when the directory cannot be written",
|
||||
() => {
|
||||
chmodSync(state.dir, 0o500);
|
||||
try {
|
||||
expect(claimDailyNotice("update", "/work/a", NOW)).toBe(false);
|
||||
} finally {
|
||||
chmodSync(state.dir, 0o700);
|
||||
}
|
||||
},
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,42 @@
|
||||
import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { dirname, join } from "node:path";
|
||||
import { CONFIG_PATH } from "../telemetry/config.js";
|
||||
|
||||
const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
|
||||
|
||||
/** The recorded showings; anything that is not an object of numbers reads as none. */
|
||||
function readShown(noticeFile: string): Record<string, number> {
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(readFileSync(noticeFile, "utf-8"));
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
|
||||
return Object.fromEntries(
|
||||
Object.entries(parsed).filter((entry): entry is [string, number] => Number.isFinite(entry[1])),
|
||||
);
|
||||
}
|
||||
|
||||
/** Shown within the last day. A time ahead of the clock is not trusted, so it reads as stale. */
|
||||
const recent = (at: number, now: number) => at <= now && now - at < NOTICE_INTERVAL_MS;
|
||||
|
||||
/** True at most once a day per project for this kind of notice, recorded in `<kind>-notice.json`. */
|
||||
export function claimDailyNotice(kind: string, project: string, now = Date.now()): boolean {
|
||||
const noticeFile = join(dirname(CONFIG_PATH), `${kind}-notice.json`);
|
||||
const shown = readShown(noticeFile);
|
||||
if (recent(shown[project] ?? 0, now)) return false;
|
||||
const kept = Object.entries(shown).filter(([, at]) => recent(at, now));
|
||||
const tmp = `${noticeFile}.${process.pid}.tmp`;
|
||||
try {
|
||||
mkdirSync(dirname(noticeFile), { recursive: true, mode: 0o700 });
|
||||
writeFileSync(tmp, JSON.stringify(Object.fromEntries([...kept, [project, now]])), {
|
||||
mode: 0o600,
|
||||
});
|
||||
renameSync(tmp, noticeFile);
|
||||
} catch {
|
||||
rmSync(tmp, { force: true });
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
@@ -1,3 +1,6 @@
|
||||
import { mkdtempSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
// The module inspects `process.argv[1]` + `realpathSync`. We stub both so
|
||||
@@ -156,3 +159,107 @@ describe("installInvocation", () => {
|
||||
expect(installInvocation("skip", "1.2.3")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("runningInstall: which binary runs, and the command that updates it", () => {
|
||||
afterEach(() => {
|
||||
vi.doUnmock("node:fs");
|
||||
vi.resetModules();
|
||||
vi.unstubAllEnvs();
|
||||
});
|
||||
|
||||
async function runningAt(realPath: string) {
|
||||
vi.resetModules();
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "");
|
||||
vi.doMock("node:fs", async () => ({
|
||||
...(await vi.importActual<typeof import("node:fs")>("node:fs")),
|
||||
realpathSync: () => realPath,
|
||||
}));
|
||||
const origArgv1 = process.argv[1];
|
||||
process.argv[1] = "/usr/local/bin/hyperframes";
|
||||
try {
|
||||
const mod = await import("./installerDetection.js");
|
||||
const install = mod.runningInstall();
|
||||
return {
|
||||
install,
|
||||
command: mod.updateCommandFor(install, "0.9.8"),
|
||||
label: mod.installChannelLabel(install.channel),
|
||||
mod,
|
||||
};
|
||||
} finally {
|
||||
process.argv[1] = origArgv1 ?? "";
|
||||
}
|
||||
}
|
||||
|
||||
it.each([
|
||||
[
|
||||
"npm",
|
||||
"/usr/local/lib/node_modules/hyperframes/dist/cli.js",
|
||||
"npm install -g hyperframes@0.9.8",
|
||||
],
|
||||
[
|
||||
"pnpm",
|
||||
"/home/me/.local/share/pnpm/global/5/node_modules/hyperframes/dist/cli.js",
|
||||
"pnpm add -g hyperframes@0.9.8",
|
||||
],
|
||||
[
|
||||
"bun",
|
||||
"/home/me/.bun/install/global/node_modules/hyperframes/dist/cli.js",
|
||||
"bun add -g hyperframes@0.9.8",
|
||||
],
|
||||
[
|
||||
"brew",
|
||||
"/opt/homebrew/Cellar/hyperframes/0.9.5/libexec/lib/node_modules/hyperframes/dist/cli.js",
|
||||
"brew upgrade hyperframes",
|
||||
],
|
||||
[
|
||||
"npx",
|
||||
"/home/me/.npm/_npx/4f1c2a/node_modules/hyperframes/dist/cli.js",
|
||||
"npx hyperframes@latest",
|
||||
],
|
||||
[
|
||||
"npx",
|
||||
"/tmp/bunx-1000-hyperframes@latest/node_modules/hyperframes/dist/cli.js",
|
||||
"npx hyperframes@latest",
|
||||
],
|
||||
[
|
||||
"project",
|
||||
"/home/me/video/node_modules/hyperframes/dist/cli.js",
|
||||
"npm install hyperframes@0.9.8",
|
||||
],
|
||||
[
|
||||
"project",
|
||||
"/home/me/video/node_modules/.pnpm/hyperframes@0.9.5/node_modules/hyperframes/dist/cli.js",
|
||||
"npm install hyperframes@0.9.8",
|
||||
],
|
||||
["workspace", "/home/me/hyperframes/packages/cli/dist/cli.js", "npx hyperframes@latest"],
|
||||
["unknown", "/opt/tools/hyperframes/cli.js", "npx hyperframes@latest"],
|
||||
])("classifies a %s install at %s; update with: %s", async (channel, path, command) => {
|
||||
const run = await runningAt(path);
|
||||
expect(run.install).toEqual({ channel, path });
|
||||
expect(run.command).toBe(command);
|
||||
expect(run.label).toBeTruthy();
|
||||
});
|
||||
|
||||
// `upgrade --project` only rewrites script pins; the dependency moves with the project's manager.
|
||||
it.each([
|
||||
["bun.lock", "bun add hyperframes@0.9.8"],
|
||||
["bun.lockb", "bun add hyperframes@0.9.8"],
|
||||
["pnpm-lock.yaml", "pnpm add hyperframes@0.9.8"],
|
||||
["yarn.lock", "yarn add hyperframes@0.9.8"],
|
||||
["package-lock.json", "npm install hyperframes@0.9.8"],
|
||||
])("moves a project-local CLI with the manager its %s names", async (lockfile, command) => {
|
||||
const project = mkdtempSync(join(tmpdir(), "hf-project-"));
|
||||
writeFileSync(join(project, lockfile), "");
|
||||
const run = await runningAt(join(project, "node_modules", "hyperframes", "dist", "cli.js"));
|
||||
expect(run.install.channel).toBe("project");
|
||||
expect(run.command).toBe(command);
|
||||
});
|
||||
|
||||
it("names a plugin install (plugin-cli.mjs marks its pinned npx child) and never an npx command for it", async () => {
|
||||
const run = await runningAt("/home/me/.npm/_npx/4f1c2a/node_modules/hyperframes/dist/cli.js");
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "0.9.5");
|
||||
const install = run.mod.runningInstall();
|
||||
expect(install.channel).toBe("plugin");
|
||||
expect(run.mod.updateCommandFor(install, "0.9.8")).toMatch(/plugin/);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -6,8 +6,9 @@
|
||||
* in charge.
|
||||
*/
|
||||
|
||||
import { realpathSync } from "node:fs";
|
||||
import { existsSync, realpathSync } from "node:fs";
|
||||
import { posix } from "node:path";
|
||||
import { isSafeVersion } from "./safeVersion.js";
|
||||
|
||||
export type InstallerKind = "npm" | "bun" | "pnpm" | "brew" | "skip";
|
||||
|
||||
@@ -59,7 +60,9 @@ function isEphemeralExec(realEntry: string): boolean {
|
||||
return (
|
||||
normalized.includes("/_npx/") ||
|
||||
normalized.includes("/.npm/_npx/") ||
|
||||
posix.basename(posix.dirname(normalized)).startsWith("bunx-")
|
||||
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)
|
||||
);
|
||||
}
|
||||
|
||||
@@ -187,3 +190,96 @@ export function installInvocation(kind: InstallerKind, version: string): Install
|
||||
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";
|
||||
}
|
||||
|
||||
@@ -69,6 +69,44 @@ describe("skillsUpdateCheck", () => {
|
||||
expect(skillsCheckDue()).toBe(false);
|
||||
});
|
||||
|
||||
describe("cache freshness: 2 hours, and only for this CLI's release tag", () => {
|
||||
const hoursAgo = (h: number) => new Date(Date.now() - h * 3_600_000).toISOString();
|
||||
|
||||
it.each([
|
||||
[
|
||||
"an hour-old check by this CLI",
|
||||
{ lastSkillsCheck: hoursAgo(1), skillsCheckedVersion: "0.0.0-dev" },
|
||||
false,
|
||||
],
|
||||
[
|
||||
"a 3-hour-old check",
|
||||
{ lastSkillsCheck: hoursAgo(3), skillsCheckedVersion: "0.0.0-dev" },
|
||||
true,
|
||||
],
|
||||
[
|
||||
"a fresh check taken by another CLI version",
|
||||
{ lastSkillsCheck: hoursAgo(1), skillsCheckedVersion: "0.9.4" },
|
||||
true,
|
||||
],
|
||||
["a fresh check that predates version stamping", { lastSkillsCheck: hoursAgo(1) }, true],
|
||||
])("with %s, a background check is due: %s", async (_, cache, due) => {
|
||||
config = cache;
|
||||
const { skillsCheckDue } = await import("./skillsUpdateCheck.js");
|
||||
expect(skillsCheckDue()).toBe(due);
|
||||
});
|
||||
|
||||
it("refreshSkillsCache stamps the CLI version whose tag it compared against", async () => {
|
||||
mockCheckSkills.mockResolvedValue({
|
||||
location: "/home/user/.claude/skills",
|
||||
updateAvailable: true,
|
||||
summary: { current: 1, outdated: 2, missing: 0, coreMissing: 0 },
|
||||
});
|
||||
const { refreshSkillsCache } = await import("./skillsUpdateCheck.js");
|
||||
await refreshSkillsCache();
|
||||
expect(config).toMatchObject({ skillsCheckedVersion: "0.0.0-dev", skillsOutdatedCount: 2 });
|
||||
});
|
||||
});
|
||||
|
||||
it("a run without a TTY (an agent) still has its background check due", async () => {
|
||||
gate.noTty = true;
|
||||
const { skillsCheckDue } = await import("./skillsUpdateCheck.js");
|
||||
@@ -162,6 +200,21 @@ describe("skillsUpdateCheck", () => {
|
||||
expect(await noticeTextFor(stale, "/projects/b")).toContain("2 HyperFrames skills");
|
||||
});
|
||||
|
||||
// The cache now refreshes every 2 h; the printed nudge must not follow it.
|
||||
it("still prints at most once a day per project when the cache refreshes 3 hours later", async () => {
|
||||
vi.useFakeTimers({ now: new Date("2026-11-03T08:00:00Z"), toFake: ["Date"] });
|
||||
try {
|
||||
const stale = { skillsOutdatedCount: 2, skillsMissingCount: 0 };
|
||||
expect(await noticeTextFor(stale, "/projects/a")).toContain("2 HyperFrames skills");
|
||||
vi.setSystemTime(new Date("2026-11-03T11:00:00Z"));
|
||||
expect(await noticeTextFor(stale, "/projects/a")).toBeNull();
|
||||
vi.setSystemTime(new Date("2026-11-04T08:00:01Z"));
|
||||
expect(await noticeTextFor(stale, "/projects/a")).toContain("2 HyperFrames skills");
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
|
||||
it("unattended, says nothing about skills that are only outdated", async () => {
|
||||
gate.unattended = true;
|
||||
expect(await noticeTextFor({ skillsOutdatedCount: 3, skillsMissingCount: 0 })).toBeNull();
|
||||
@@ -194,7 +247,8 @@ describe("skillsUpdateCheck", () => {
|
||||
// verdict so the next command re-checks for real.
|
||||
describe("invalidateSkillsCache", () => {
|
||||
const PRE_INSTALL_CACHE = {
|
||||
lastSkillsCheck: new Date().toISOString(), // fresh — inside the 24h TTL
|
||||
lastSkillsCheck: new Date().toISOString(), // fresh — inside the 2h TTL
|
||||
skillsCheckedVersion: "0.0.0-dev", // taken by this CLI (the version under test)
|
||||
skillsUpdateAvailable: true,
|
||||
skillsOutdatedCount: 12,
|
||||
skillsMissingCount: 8,
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
// Passive "your skills are stale" nudge. Mirrors updateCheck.ts: a background
|
||||
// check populates a 24h cache; printSkillsUpdateNotice() reads the cache
|
||||
// synchronously and prints one line on exit.
|
||||
// check populates a 2h cache; printSkillsUpdateNotice() reads the cache
|
||||
// synchronously and prints one line on exit, at most once a day per project.
|
||||
//
|
||||
// Why a passive nudge (not just `skills check`): agents don't reliably run a
|
||||
// check on their own, but they DO run render/lint/validate — so we piggyback
|
||||
// the reminder on the commands they already run.
|
||||
|
||||
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { dirname, join, resolve } from "node:path";
|
||||
import { CONFIG_PATH, readConfig, readConfigFresh, writeConfig } from "../telemetry/config.js";
|
||||
import { resolve } from "node:path";
|
||||
import { readConfig, readConfigFresh, writeConfig } from "../telemetry/config.js";
|
||||
import { isUnattended } from "./attendedTerminal.js";
|
||||
import { claimDailyNotice } from "./dailyNotice.js";
|
||||
import { hostAnswers } from "./hostAnswers.js";
|
||||
import { checkSkills } from "./skillsManifest.js";
|
||||
import { checkSkills, type SkillsCheckResult } from "./skillsManifest.js";
|
||||
import { updateCheckDisabled } from "./updateCheck.js";
|
||||
import { VERSION } from "../version.js";
|
||||
|
||||
const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
|
||||
const CHECK_INTERVAL_MS = 2 * 60 * 60 * 1000;
|
||||
|
||||
interface SkillsUpdateMeta {
|
||||
updateAvailable: boolean;
|
||||
@@ -33,9 +33,9 @@ function getSkillsUpdateMeta(): SkillsUpdateMeta {
|
||||
};
|
||||
}
|
||||
|
||||
function cacheFresh(lastSkillsCheck: string | undefined, now: number): boolean {
|
||||
if (!lastSkillsCheck) return false;
|
||||
return now - new Date(lastSkillsCheck).getTime() < CHECK_INTERVAL_MS;
|
||||
function cacheFresh(config: ReturnType<typeof readConfig>, now: number): boolean {
|
||||
if (!config.lastSkillsCheck || config.skillsCheckedVersion !== VERSION) return false;
|
||||
return now - new Date(config.lastSkillsCheck).getTime() < CHECK_INTERVAL_MS;
|
||||
}
|
||||
|
||||
/** Run the real check and persist the result to the cache. Skipped when DNS does not answer. */
|
||||
@@ -44,19 +44,23 @@ export async function refreshSkillsCache(): Promise<void> {
|
||||
// `canonical: true` so this nudge's counts agree with `updateSkills`'s
|
||||
// source of truth — otherwise a stale in-repo skills-manifest.json (e.g.
|
||||
// inside a hyperframes checkout) can produce a false-positive count here.
|
||||
const result = await checkSkills({ canonical: true, cliVersion: VERSION });
|
||||
recordSkillsCheck(await checkSkills({ canonical: true, cliVersion: VERSION }));
|
||||
}
|
||||
|
||||
/** Cache a canonical skills check (at this CLI's tag) for the nudge and `_meta.skillsOutdated`. */
|
||||
export function recordSkillsCheck(result: SkillsCheckResult): void {
|
||||
// Only record a meaningful check when skills were actually found.
|
||||
if (result.location) {
|
||||
// Fresh read: this runs in a background child, beside the command's own config writes.
|
||||
const config = readConfigFresh();
|
||||
config.lastSkillsCheck = new Date().toISOString();
|
||||
config.skillsUpdateAvailable = result.updateAvailable;
|
||||
config.skillsOutdatedCount = result.summary.outdated;
|
||||
// Core-missing only: skills that install on demand (workflows not yet
|
||||
// triggered on this machine) are not "missing" worth nagging about.
|
||||
config.skillsMissingCount = result.summary.coreMissing;
|
||||
writeConfig(config);
|
||||
}
|
||||
if (!result.location) return;
|
||||
// Fresh read: this runs in a background child, beside the command's own config writes.
|
||||
const config = readConfigFresh();
|
||||
config.lastSkillsCheck = new Date().toISOString();
|
||||
config.skillsCheckedVersion = VERSION;
|
||||
config.skillsUpdateAvailable = result.updateAvailable;
|
||||
config.skillsOutdatedCount = result.summary.outdated;
|
||||
// Core-missing only: skills that install on demand (workflows not yet
|
||||
// triggered on this machine) are not "missing" worth nagging about.
|
||||
config.skillsMissingCount = result.summary.coreMissing;
|
||||
writeConfig(config);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -67,7 +71,7 @@ export async function refreshSkillsCache(): Promise<void> {
|
||||
* the install. Those commands are excluded from the nudge pipeline entirely
|
||||
* (see cli.ts), so nothing else refreshes the cache when they run — without
|
||||
* this, the last background verdict (taken BEFORE the install) keeps printing
|
||||
* "N skills out of date or missing" on every other command for up to 24h
|
||||
* "N skills out of date or missing" on every other command for up to 2h
|
||||
* after a successful install/update.
|
||||
*
|
||||
* Counts are cleared along with the timestamp — not left behind — so an
|
||||
@@ -83,6 +87,7 @@ export function invalidateSkillsCache(): void {
|
||||
// running CLI process that wrote other config fields in the meantime.
|
||||
const config = readConfigFresh();
|
||||
delete config.lastSkillsCheck;
|
||||
delete config.skillsCheckedVersion;
|
||||
delete config.skillsUpdateAvailable;
|
||||
delete config.skillsOutdatedCount;
|
||||
delete config.skillsMissingCount;
|
||||
@@ -97,30 +102,10 @@ function skillsNoticeOff(): boolean {
|
||||
return process.env["HYPERFRAMES_SKIP_SKILLS"] === "1" || updateCheckDisabled();
|
||||
}
|
||||
|
||||
/** Whether a background skills check is due: this run shows notices and the 24 h cache is stale. */
|
||||
/** Whether a background skills check is due: this run shows notices and the 2 h cache is stale. */
|
||||
export function skillsCheckDue(): boolean {
|
||||
if (skillsNoticeOff()) return false;
|
||||
return !cacheFresh(readConfig().lastSkillsCheck, Date.now());
|
||||
}
|
||||
|
||||
/** True at most once a day per project; records the showing. Unreadable state counts as never shown. */
|
||||
function claimDailyNotice(project: string, now = Date.now()): boolean {
|
||||
const noticeFile = join(dirname(CONFIG_PATH), "skills-notice.json");
|
||||
let shown: Record<string, number> = {};
|
||||
try {
|
||||
shown = JSON.parse(readFileSync(noticeFile, "utf-8")) as Record<string, number>;
|
||||
} catch {
|
||||
// first notice, or a damaged file that the write below replaces
|
||||
}
|
||||
if (now - (shown[project] ?? 0) < CHECK_INTERVAL_MS) return false;
|
||||
const kept = Object.entries(shown).filter(([, at]) => now - at < CHECK_INTERVAL_MS);
|
||||
try {
|
||||
mkdirSync(dirname(noticeFile), { recursive: true, mode: 0o700 });
|
||||
writeFileSync(noticeFile, JSON.stringify(Object.fromEntries([...kept, [project, now]])));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
return !cacheFresh(readConfig(), Date.now());
|
||||
}
|
||||
|
||||
/** The stale-skills nudge text, or null when nothing is outdated or missing. */
|
||||
@@ -140,5 +125,5 @@ export function printSkillsUpdateNotice(cwd: string = process.cwd()): void {
|
||||
if (skillsNoticeOff()) return;
|
||||
const meta = getSkillsUpdateMeta();
|
||||
const text = skillsNoticeText(isUnattended() ? { ...meta, outdated: 0 } : meta);
|
||||
if (text && claimDailyNotice(resolve(cwd))) process.stderr.write(text);
|
||||
if (text && claimDailyNotice("skills", resolve(cwd))) process.stderr.write(text);
|
||||
}
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
import { mkdtempSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join, resolve } from "node:path";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { isSafeVersion, printDeprecationNotice, withMeta } from "./updateCheck.js";
|
||||
|
||||
@@ -400,20 +403,29 @@ describe("checkForUpdate — registry boundary guard", () => {
|
||||
});
|
||||
|
||||
describe("updateCheckDue / cachedUpdateCheck — what the parent reads without fetching", () => {
|
||||
// The directory that holds the daily notice claims: a fresh one per load().
|
||||
let stateDir = "";
|
||||
|
||||
afterEach(() => {
|
||||
vi.doUnmock("../telemetry/config.js");
|
||||
vi.doUnmock("./env.js");
|
||||
vi.doUnmock("../version.js");
|
||||
vi.doUnmock("./installerDetection.js");
|
||||
vi.resetModules();
|
||||
vi.unstubAllEnvs();
|
||||
vi.useRealTimers();
|
||||
});
|
||||
|
||||
async function load(config: Record<string, unknown>) {
|
||||
vi.resetModules();
|
||||
vi.stubEnv("CI", "");
|
||||
vi.stubEnv("HYPERFRAMES_NO_UPDATE_CHECK", "");
|
||||
vi.stubEnv("HYPERFRAMES_PLUGIN_VERSION", "");
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "");
|
||||
stateDir = mkdtempSync(join(tmpdir(), "hf-update-notice-"));
|
||||
vi.doMock("./env.js", () => ({ isDevMode: () => false }));
|
||||
vi.doMock("../telemetry/config.js", () => ({
|
||||
CONFIG_PATH: join(stateDir, "config.json"),
|
||||
readConfig: () => ({ ...config }),
|
||||
readConfigFresh: () => ({ ...config }),
|
||||
writeConfig: () => {},
|
||||
@@ -438,6 +450,280 @@ describe("updateCheckDue / cachedUpdateCheck — what the parent reads without f
|
||||
expect(mod.updateCheckDue()).toBe(due);
|
||||
});
|
||||
|
||||
// A release reaches agents within hours: the cache answers for 2 h, not a day.
|
||||
it("re-asks the registry once the cache is 3 hours old", async () => {
|
||||
const mod = await load({ lastUpdateCheck: hoursAgo(3), latestVersion: "9.9.9" });
|
||||
expect(mod.updateCheckDue()).toBe(true);
|
||||
});
|
||||
|
||||
it("says in _meta when the cached latest was checked", async () => {
|
||||
const checkedAt = hoursAgo(1);
|
||||
const mod = await load({ lastUpdateCheck: checkedAt, latestVersion: "999.0.0" });
|
||||
expect(mod.getUpdateMeta()).toMatchObject({ latestVersion: "999.0.0", checkedAt });
|
||||
});
|
||||
|
||||
describe("_meta.skillsOutdated, from the cached background skills check", () => {
|
||||
const skillsCache = (over: Record<string, unknown> = {}) => ({
|
||||
lastSkillsCheck: hoursAgo(1),
|
||||
skillsCheckedVersion: "0.9.6",
|
||||
skillsOutdatedCount: 3,
|
||||
skillsMissingCount: 0,
|
||||
...over,
|
||||
});
|
||||
const loadAt096 = (config: Record<string, unknown>) => {
|
||||
vi.doMock("../version.js", () => ({ VERSION: "0.9.6", PRODUCER_VERSION: "0.9.6" }));
|
||||
return load(config);
|
||||
};
|
||||
|
||||
it("reports the count without a network call", async () => {
|
||||
const fetchSpy = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchSpy);
|
||||
try {
|
||||
const mod = await loadAt096(skillsCache());
|
||||
expect(mod.withMeta({ ok: true })._meta.skillsOutdated).toBe(3);
|
||||
expect(fetchSpy).not.toHaveBeenCalled();
|
||||
} finally {
|
||||
vi.unstubAllGlobals();
|
||||
}
|
||||
});
|
||||
|
||||
it("still reports a count taken 23 hours ago", async () => {
|
||||
const mod = await loadAt096(skillsCache({ lastSkillsCheck: hoursAgo(23) }));
|
||||
expect(mod.getUpdateMeta().skillsOutdated).toBe(3);
|
||||
});
|
||||
|
||||
it("reports zero when the check found everything current", async () => {
|
||||
const mod = await loadAt096(skillsCache({ skillsOutdatedCount: 0 }));
|
||||
expect(mod.getUpdateMeta().skillsOutdated).toBe(0);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["no skills check is cached", {}],
|
||||
[
|
||||
"the check ran under another CLI version (another release tag)",
|
||||
skillsCache({ skillsCheckedVersion: "0.9.5" }),
|
||||
],
|
||||
["the cached count is not a count", skillsCache({ skillsOutdatedCount: "3" })],
|
||||
// Nothing refreshes the count once HYPERFRAMES_NO_UPDATE_CHECK (or CI/dev) stops the checks.
|
||||
["the check is over a day old", skillsCache({ lastSkillsCheck: hoursAgo(25) })],
|
||||
])("is absent when %s", async (_, config) => {
|
||||
const mod = await loadAt096(config);
|
||||
expect("skillsOutdated" in mod.getUpdateMeta()).toBe(false);
|
||||
});
|
||||
|
||||
it("is absent when HYPERFRAMES_SKIP_SKILLS hands the skills to something else", async () => {
|
||||
const mod = await loadAt096(skillsCache());
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
|
||||
expect("skillsOutdated" in mod.getUpdateMeta()).toBe(false);
|
||||
});
|
||||
|
||||
it("reports missing core skills as skillsMissing, beside skillsOutdated", async () => {
|
||||
const mod = await loadAt096(skillsCache({ skillsMissingCount: 2 }));
|
||||
expect(mod.getUpdateMeta()).toMatchObject({ skillsOutdated: 3, skillsMissing: 2 });
|
||||
});
|
||||
|
||||
it.each([
|
||||
[
|
||||
"the check is over a day old",
|
||||
skillsCache({ skillsMissingCount: 2, lastSkillsCheck: hoursAgo(25) }),
|
||||
],
|
||||
[
|
||||
"the check ran under another CLI version",
|
||||
skillsCache({ skillsMissingCount: 2, skillsCheckedVersion: "0.9.5" }),
|
||||
],
|
||||
["the cached count is not a count", skillsCache({ skillsMissingCount: -1 })],
|
||||
])("leaves skillsMissing out when %s", async (_, config) => {
|
||||
const mod = await loadAt096(config);
|
||||
expect("skillsMissing" in mod.getUpdateMeta()).toBe(false);
|
||||
});
|
||||
|
||||
it("leaves skillsMissing out under HYPERFRAMES_SKIP_SKILLS", async () => {
|
||||
const mod = await loadAt096(skillsCache({ skillsMissingCount: 2 }));
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
|
||||
expect("skillsMissing" in mod.getUpdateMeta()).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
// The agent relays this sentence to the person, who decides whether to update; no skill text
|
||||
// tells the agent to run an update itself.
|
||||
describe("_meta.updateNotice, for the agent to pass on to the person", () => {
|
||||
const behind = (over: Record<string, unknown> = {}) => ({
|
||||
lastUpdateCheck: hoursAgo(1),
|
||||
latestVersion: "0.9.8",
|
||||
lastSkillsCheck: hoursAgo(1),
|
||||
skillsCheckedVersion: "0.9.6",
|
||||
skillsOutdatedCount: 3,
|
||||
skillsMissingCount: 0,
|
||||
...over,
|
||||
});
|
||||
const loadNotice = (
|
||||
config: Record<string, unknown>,
|
||||
channel = "npm",
|
||||
path = "/test/lib/node_modules/hyperframes/dist/cli.js",
|
||||
) => {
|
||||
vi.doMock("../version.js", () => ({ VERSION: "0.9.6", PRODUCER_VERSION: "0.9.6" }));
|
||||
vi.doMock("./installerDetection.js", async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import("./installerDetection.js")>()),
|
||||
runningInstall: () => ({ channel, path }),
|
||||
}));
|
||||
return load(config);
|
||||
};
|
||||
|
||||
it("names the newer CLI, the skills behind, and the one command that updates both", async () => {
|
||||
const mod = await loadNotice(behind());
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toBe(
|
||||
"For the user: HyperFrames CLI 0.9.8 is available (this run is 0.9.6), and 3 installed HyperFrames skills are out of date. To update both, run: hyperframes update",
|
||||
);
|
||||
});
|
||||
|
||||
it("counts missing core skills in the skills half", async () => {
|
||||
const mod = await loadNotice(behind({ skillsOutdatedCount: 1, skillsMissingCount: 2 }));
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toContain(
|
||||
"1 installed HyperFrames skill is out of date and 2 core skills are missing.",
|
||||
);
|
||||
});
|
||||
|
||||
it("speaks of the skills alone when the CLI is current", async () => {
|
||||
const mod = await loadNotice(behind({ latestVersion: "0.9.6" }));
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toBe(
|
||||
"For the user: 3 installed HyperFrames skills are out of date (this run is HyperFrames CLI 0.9.6). To update them, run: hyperframes update",
|
||||
);
|
||||
});
|
||||
|
||||
it("leaves out the skills half when no skill is behind", async () => {
|
||||
const mod = await loadNotice(behind({ skillsOutdatedCount: 0 }));
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toBe(
|
||||
"For the user: HyperFrames CLI 0.9.8 is available (this run is 0.9.6). To update, run: npm install -g hyperframes@0.9.8",
|
||||
);
|
||||
});
|
||||
|
||||
it("leaves out the skills half under HYPERFRAMES_SKIP_SKILLS", async () => {
|
||||
const mod = await loadNotice(behind());
|
||||
vi.stubEnv("HYPERFRAMES_SKIP_SKILLS", "1");
|
||||
const notice = mod.withMeta({ ok: true })._meta.updateNotice;
|
||||
expect(notice).toBe(
|
||||
"For the user: HyperFrames CLI 0.9.8 is available (this run is 0.9.6). To update, run: npm install -g hyperframes@0.9.8",
|
||||
);
|
||||
});
|
||||
|
||||
// Each command moves the install that is running: a global CLI's own `update` (npx would run a
|
||||
// project's copy or a fresh one), a project's manager for a project-local CLI.
|
||||
const PROJECT = "/test/video/node_modules/hyperframes/dist/cli.js";
|
||||
it.each([
|
||||
[
|
||||
"npm",
|
||||
undefined,
|
||||
"hyperframes update",
|
||||
"npm install -g hyperframes@0.9.8",
|
||||
"hyperframes update",
|
||||
],
|
||||
[
|
||||
"pnpm",
|
||||
undefined,
|
||||
"hyperframes update",
|
||||
"pnpm add -g hyperframes@0.9.8",
|
||||
"hyperframes update",
|
||||
],
|
||||
[
|
||||
"bun",
|
||||
undefined,
|
||||
"hyperframes update",
|
||||
"bun add -g hyperframes@0.9.8",
|
||||
"hyperframes update",
|
||||
],
|
||||
["brew", undefined, "hyperframes update", "brew upgrade hyperframes", "hyperframes update"],
|
||||
[
|
||||
"project",
|
||||
PROJECT,
|
||||
"npm install hyperframes@0.9.8, then npx hyperframes update",
|
||||
"npm install hyperframes@0.9.8",
|
||||
"npx hyperframes update",
|
||||
],
|
||||
[
|
||||
"npx",
|
||||
undefined,
|
||||
"npx hyperframes@latest update",
|
||||
"npx hyperframes@latest update",
|
||||
"npx hyperframes update",
|
||||
],
|
||||
[
|
||||
"unknown",
|
||||
undefined,
|
||||
"npx hyperframes update",
|
||||
"npx hyperframes update",
|
||||
"npx hyperframes update",
|
||||
],
|
||||
])(
|
||||
"%s: names a command that moves this install",
|
||||
async (channel, path, both, cliOnly, skillsOnly) => {
|
||||
const cases: [Record<string, unknown>, string][] = [
|
||||
[behind(), both],
|
||||
[behind({ skillsOutdatedCount: 0 }), cliOnly],
|
||||
[behind({ latestVersion: "0.9.6" }), skillsOnly],
|
||||
];
|
||||
for (const [config, command] of cases) {
|
||||
const mod = await loadNotice(config, channel, path);
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toMatch(
|
||||
new RegExp(`run: ${command.replaceAll(".", "\\.")}$`),
|
||||
);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it.each([
|
||||
["the update check is off", { HYPERFRAMES_NO_UPDATE_CHECK: "1" }],
|
||||
["CI runs it", { CI: "1" }],
|
||||
["an agent plugin pins the CLI", { HYPERFRAMES_PLUGIN_VERSION: "0.9.6" }],
|
||||
])("is absent when %s", async (_, env) => {
|
||||
const mod = await loadNotice(behind());
|
||||
for (const [k, v] of Object.entries(env)) vi.stubEnv(k, v);
|
||||
expect("updateNotice" in mod.withMeta({ ok: true })._meta).toBe(false);
|
||||
});
|
||||
|
||||
it("is absent when nothing is behind", async () => {
|
||||
const mod = await loadNotice(behind({ latestVersion: "0.9.6", skillsOutdatedCount: 0 }));
|
||||
expect("updateNotice" in mod.withMeta({ ok: true })._meta).toBe(false);
|
||||
});
|
||||
|
||||
it("is absent when the caller opts out (`update` names its own command)", async () => {
|
||||
const mod = await loadNotice(behind());
|
||||
expect("updateNotice" in mod.withMeta({ ok: true }, { updateNotice: false })._meta).toBe(
|
||||
false,
|
||||
);
|
||||
});
|
||||
|
||||
it("shows once a day per project; the numeric fields stay on every result", async () => {
|
||||
vi.useFakeTimers({ toFake: ["Date"] });
|
||||
vi.setSystemTime(new Date("2026-11-03T08:00:00Z"));
|
||||
const at = (h: number) =>
|
||||
new Date(Date.parse("2026-11-03T08:00:00Z") - h * 3_600_000).toISOString();
|
||||
const mod = await loadNotice(behind({ lastUpdateCheck: at(1), lastSkillsCheck: at(1) }));
|
||||
|
||||
const first = mod.withMeta({ ok: true })._meta;
|
||||
expect(first.updateNotice).toEqual(expect.any(String));
|
||||
const again = mod.withMeta({ ok: true })._meta;
|
||||
expect("updateNotice" in again).toBe(false);
|
||||
expect(again).toMatchObject({
|
||||
updateAvailable: true,
|
||||
latestVersion: "0.9.8",
|
||||
skillsOutdated: 3,
|
||||
});
|
||||
expect(again.checkedAt).toEqual(expect.any(String));
|
||||
|
||||
vi.setSystemTime(new Date("2026-11-04T08:30:00Z"));
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toEqual(expect.any(String));
|
||||
});
|
||||
|
||||
it("keeps its own daily claim, apart from the stderr skills nudge", async () => {
|
||||
const mod = await loadNotice(behind());
|
||||
writeFileSync(
|
||||
join(stateDir, "skills-notice.json"),
|
||||
JSON.stringify({ [resolve(process.cwd())]: Date.now() }),
|
||||
);
|
||||
expect(mod.withMeta({ ok: true })._meta.updateNotice).toEqual(expect.any(String));
|
||||
});
|
||||
});
|
||||
|
||||
it("is never due under CI", async () => {
|
||||
const mod = await load({});
|
||||
vi.stubEnv("CI", "1");
|
||||
@@ -471,10 +757,13 @@ describe("updateCheckDue / cachedUpdateCheck — what the parent reads without f
|
||||
},
|
||||
);
|
||||
|
||||
it("treats a cached latest older than the running CLI as unknown, without re-checking sooner than the daily cadence", async () => {
|
||||
// The cache predates this install (an upgrade happened since), so however recent, it is
|
||||
// stale: the next background check asks the registry (launchBackgroundChecks' 1 h
|
||||
// failure backoff still bounds how often).
|
||||
it("treats a cached latest older than the running CLI as unknown, and as due for a recheck now", async () => {
|
||||
vi.doMock("../version.js", () => ({ VERSION: "0.9.6", PRODUCER_VERSION: "0.9.6" }));
|
||||
const mod = await load({ lastUpdateCheck: hoursAgo(1), latestVersion: "0.9.5" });
|
||||
expect(mod.updateCheckDue()).toBe(false);
|
||||
expect(mod.updateCheckDue()).toBe(true);
|
||||
expect(mod.getUpdateMeta()).toEqual({
|
||||
version: "0.9.6",
|
||||
latestVersion: undefined,
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { join, resolve } from "node:path";
|
||||
import { compareVersions } from "compare-versions";
|
||||
import { readConfig, readConfigFresh, writeConfig } from "../telemetry/config.js";
|
||||
import { VERSION } from "../version.js";
|
||||
@@ -7,14 +7,22 @@ import { isCI, isUnattended } from "./attendedTerminal.js";
|
||||
import { isDevMode } from "./env.js";
|
||||
import { asNotice } from "./jsonError.js";
|
||||
import { hostAnswers } from "./hostAnswers.js";
|
||||
import { detectInstaller } from "./installerDetection.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 = 24 * 60 * 60 * 1000; // 24 hours
|
||||
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). */
|
||||
@@ -36,12 +44,23 @@ 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 24h cache to avoid
|
||||
* 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
|
||||
@@ -93,10 +112,14 @@ export async function checkForUpdate(force?: boolean): Promise<UpdateCheckResult
|
||||
}
|
||||
}
|
||||
|
||||
/** Whether the background check should ask the registry: not opted out, and no fresh safe cache. */
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
@@ -128,14 +151,129 @@ function cachedVersionForThisInstall(value: unknown): string | undefined {
|
||||
* Never fetches. Returns what the last background check found.
|
||||
*/
|
||||
export function getUpdateMeta(): UpdateMeta {
|
||||
const latestVersion = cachedVersionForThisInstall(readConfig().latestVersion);
|
||||
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.
|
||||
@@ -143,12 +281,20 @@ export function getUpdateMeta(): UpdateMeta {
|
||||
* 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 },
|
||||
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 };
|
||||
}
|
||||
|
||||
@@ -13,7 +13,8 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
export const DESCRIPTION_MAX = 320;
|
||||
export const CORE_SKILLS = {
|
||||
hyperframes: 7168,
|
||||
"hyperframes-cli": 7168,
|
||||
// +256 B for the `_meta.updateNotice` line: the agent relays it, the person updates.
|
||||
"hyperframes-cli": 7424,
|
||||
"hyperframes-registry": 5120,
|
||||
"media-use": 5120,
|
||||
figma: 7168,
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
"files": 77
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "aeb9494dee6777a7",
|
||||
"hash": "ce9f4c1ff4fcb4ee",
|
||||
"files": 13
|
||||
},
|
||||
"hyperframes-registry": {
|
||||
|
||||
@@ -9,6 +9,8 @@ description: The HyperFrames CLI by job - scaffold, check, look at frames, edit
|
||||
|
||||
Run `npx hyperframes <command>` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero.
|
||||
|
||||
A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide.
|
||||
|
||||
## Commands by job
|
||||
|
||||
| Job | Commands |
|
||||
|
||||
Reference in New Issue
Block a user