Skip to content

Commit 216395e

Browse files
fix(cli): every settings file follows HYPERFRAMES_CONFIG_DIR (#7229)
* fix(cli): every settings file follows HYPERFRAMES_CONFIG_DIR * fix(cli): the media-use skill copy reads its config from HYPERFRAMES_CONFIG_DIR too * test(cli): expect the config folder as a normalized path on every platform * chore(skills): refresh the media-use manifest hash * fix(cli): a moved settings folder starts from ~/.hyperframes, keeping an opt-out * fix(cli): drop the updater's unused path import * style(cli): keep the settings-seed comment under 120 characters
1 parent b7a8cfa commit 216395e

19 files changed

Lines changed: 235 additions & 63 deletions

‎docs/guides/authentication.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ to a shared space with `--space`.
147147
| `HEYGEN_ACCESS_TOKEN` | OAuth token a host app injects; never refreshed or saved. |
148148
| `HEYGEN_API_BASE` | A host app's gateway for media workflows; never read from a project `.env`. |
149149
| `HEYGEN_API_URL` | API base URL for `hyperframes` CLI commands (default `https://api.heygen.com`). |
150-
| `HYPERFRAMES_CONFIG_DIR` | HyperFrames credentials root (default `~/.hyperframes`). |
150+
| `HYPERFRAMES_CONFIG_DIR` | HyperFrames settings root: credentials, telemetry and update settings, project links (default `~/.hyperframes`). |
151151
| `HYPERFRAMES_ENV` | `prod` (default) or `dev`; `dev` keeps credentials in a separate `dev/` directory under the root. Hosts and the OAuth client id come from `HEYGEN_API_URL`, `HYPERFRAMES_OAUTH_*` and `HYPERFRAMES_PUBLISHED_PROJECTS_API_URL`. |
152152
| `HYPERFRAMES_OAUTH_CLIENT_ID` | Override the public client ID for a controlled OAuth environment. |
153153
| `ELEVENLABS_API_KEY` | ElevenLabs TTS, used when no HeyGen credential is present. |

‎docs/packages/cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2516,7 +2516,7 @@ hyperframes auth logout --yes # no prompt
25162516
| `HYPERFRAMES_API_KEY` | Alias for `HEYGEN_API_KEY`. |
25172517
| `HEYGEN_ACCESS_TOKEN` | OAuth token from a host app; used first, never refreshed. |
25182518
| `HEYGEN_API_URL` | API base URL (default `https://api.heygen.com`). |
2519-
| `HYPERFRAMES_CONFIG_DIR` | Credentials root (default `~/.hyperframes`). |
2519+
| `HYPERFRAMES_CONFIG_DIR` | Settings root: credentials, telemetry and update settings, project links (default `~/.hyperframes`). |
25202520
| `HYPERFRAMES_ENV` | `prod` (default) or `dev`; `dev` uses a separate credential directory. Hosts and the OAuth client id come from `HEYGEN_API_URL` and `HYPERFRAMES_OAUTH_*`. |
25212521
| `HYPERFRAMES_OAUTH_CLIENT_ID` | Override the selected public OAuth client. |
25222522

‎packages/cli/src/auth/paths.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ describe("auth/paths", () => {
2222

2323
it("honors HYPERFRAMES_CONFIG_DIR override", () => {
2424
process.env["HYPERFRAMES_CONFIG_DIR"] = "/tmp/some-test-dir";
25-
expect(configDir()).toBe("/tmp/some-test-dir");
25+
expect(configDir()).toBe(join("/tmp/some-test-dir"));
2626
expect(credentialPath()).toBe(join("/tmp/some-test-dir", CREDENTIAL_FILENAME));
2727
});
2828

‎packages/cli/src/auth/paths.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
* HyperFrames credentials are isolated from the HeyGen CLI and between environments.
33
*/
44

5-
import { homedir } from "node:os";
65
import { join } from "node:path";
6+
import { hyperframesConfigDir } from "../utils/configDir.js";
77
import { oauthEnvironment } from "./config.js";
88

99
/**
@@ -12,7 +12,7 @@ import { oauthEnvironment } from "./config.js";
1212
export const CREDENTIAL_FILENAME = "credentials";
1313

1414
export function configDir(): string {
15-
const root = process.env["HYPERFRAMES_CONFIG_DIR"] || join(homedir(), ".hyperframes");
15+
const root = hyperframesConfigDir();
1616
return oauthEnvironment() === "dev" ? join(root, "dev") : root;
1717
}
1818

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ import { CliUsageError, failCommand, failUsage } from "../utils/commandResult.js
1616

1717
import { spawnSync } from "node:child_process";
1818
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
19-
import { homedir } from "node:os";
2019
import { join, resolve } from "node:path";
2120
import { defineCommand } from "../utils/defineCommand.js";
2221
import { type CanvasResolution } from "@hyperframes/core";
@@ -32,6 +31,7 @@ import { normalizeErrorMessage } from "../utils/errorMessage.js";
3231
import { defaultCloudFps } from "../utils/compositionFps.js";
3332
import { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "@hyperframes/core";
3433
import { isMissingPackageError, missingPackageMessage } from "../utils/missingPackage.js";
34+
import { hyperframesConfigDir, seededConfigFile } from "../utils/configDir.js";
3535

3636
export const examples: Example[] = [
3737
["Deploy the Cloud Run render stack", "hyperframes cloudrun deploy --project my-gcp-project"],
@@ -267,10 +267,10 @@ export default defineCommand({
267267
// ── State helpers ─────────────────────────────────────────────────────────
268268

269269
function stateDir(): string {
270-
return join(homedir(), ".hyperframes");
270+
return hyperframesConfigDir();
271271
}
272272
function statePath(): string {
273-
return join(stateDir(), "cloudrun-state.json");
273+
return seededConfigFile("cloudrun-state.json");
274274
}
275275
function writeState(state: StackState): void {
276276
mkdirSync(stateDir(), { recursive: true });

‎packages/cli/src/media-use/lib/telemetry.mjs‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,13 @@ export function optedOut() {
5050
}
5151

5252
// Read and write the shared config so media-use keeps one identity per install.
53+
// Until the CLI seeds HYPERFRAMES_CONFIG_DIR's copy, ~/.hyperframes' own still holds the opt-out.
5354
function sharedConfigPath() {
54-
return join(homedir(), ".hyperframes", "config.json");
55+
const home = join(homedir(), ".hyperframes", "config.json");
56+
const dir = process.env.HYPERFRAMES_CONFIG_DIR;
57+
if (!dir) return home;
58+
const file = join(dir, "config.json");
59+
return existsSync(file) || !existsSync(home) ? file : home;
5560
}
5661

5762
function readSharedConfig() {

‎packages/cli/src/media-use/lib/telemetry.test.mjs‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,40 @@ test("optedOut honors telemetryEnabled: false from the shared config", () => {
7979
}
8080
});
8181

82+
test("the shared config is read from HYPERFRAMES_CONFIG_DIR when it is set", () => {
83+
const savedEnv = { ...process.env };
84+
const { root } = sandbox();
85+
try {
86+
withoutTelemetryOptOut();
87+
const configDir = join(root, "config");
88+
mkdirSync(configDir, { recursive: true });
89+
writeFileSync(join(configDir, "config.json"), JSON.stringify({ telemetryEnabled: false }));
90+
process.env.HYPERFRAMES_CONFIG_DIR = configDir;
91+
assert.equal(optedOut(), true);
92+
} finally {
93+
restoreEnv(savedEnv);
94+
rmSync(root, { recursive: true, force: true });
95+
}
96+
});
97+
98+
test("an opt-out in ~/.hyperframes holds until HYPERFRAMES_CONFIG_DIR has its own config", () => {
99+
const savedEnv = { ...process.env };
100+
const { root, home } = sandbox();
101+
try {
102+
withoutTelemetryOptOut();
103+
mkdirSync(join(home, ".hyperframes"), { recursive: true });
104+
writeFileSync(
105+
join(home, ".hyperframes", "config.json"),
106+
JSON.stringify({ telemetryEnabled: false }),
107+
);
108+
process.env.HYPERFRAMES_CONFIG_DIR = join(root, "moved");
109+
assert.equal(optedOut(), true);
110+
} finally {
111+
restoreEnv(savedEnv);
112+
rmSync(root, { recursive: true, force: true });
113+
}
114+
});
115+
82116
test("track is a no-op (no network, resolves) when opted out", async () => {
83117
const savedEnv = { ...process.env };
84118
const originalFetch = globalThis.fetch;

‎packages/cli/src/telemetry/config.ts‎

Lines changed: 24 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,22 @@ import { normalizeErrorMessage } from "../utils/errorMessage.js";
77
import { telemetryRuntimeOverride } from "./policy.js";
88
import { isAttendedTerminal } from "../utils/attendedTerminal.js";
99
import { withFileLock } from "../media-use/lib/config-lock.mjs";
10+
import { hyperframesConfigDir, seededConfigFile } from "../utils/configDir.js";
1011

1112
// ---------------------------------------------------------------------------
1213
// Config directory: ~/.hyperframes/
1314
// ---------------------------------------------------------------------------
1415

15-
const CONFIG_DIR = join(homedir(), ".hyperframes");
16-
const CONFIG_FILE = join(CONFIG_DIR, "config.json");
16+
const configDir = () => hyperframesConfigDir();
17+
const configFile = () => seededConfigFile("config.json");
1718

1819
// ---------------------------------------------------------------------------
1920
// Install-state file: ~/.hyperframes/install-state.json
2021
//
2122
// A separate FILE, but deliberately the same DIRECTORY as config.json, so
22-
// `rm -rf ~/.hyperframes` really is a full reset. It previously lived in
23-
// ~/.local/state/hyperframes/ specifically to survive that delete; review
24-
// rejected that ("if someone is deleting their hyperframes config it should
25-
// wipe all hyperframes state — I'm not sure we should try and persist state
26-
// elsewhere to get around this"), and the measurement agreed: the churn this
27-
// actually defends against is not users running `rm -rf`.
23+
// `rm -rf ~/.hyperframes` really is a full reset.
2824
//
29-
// The threat it does defend against is config.json itself. That file is hot
25+
// What it defends against is config.json itself. That file is hot
3026
// and wide — ~20 fields rewritten on every command and every render — and
3127
// readConfig recovers from ANY parse/permission/IO failure by minting a fresh
3228
// identity. Splitting these two facts into their own file decouples them from
@@ -37,26 +33,26 @@ const CONFIG_FILE = join(CONFIG_DIR, "config.json");
3733
// no counters, nothing emitted that links the old install to the new one:
3834
//
3935
// 1. `markerAt` — "a hyperframes install existed on this machine". Now that
40-
// it shares CONFIG_DIR, `predecessorFound` measures the churn we care
36+
// it shares configDir(), `predecessorFound` measures the churn we care
4137
// about (config.json lost, install-state survived => corruption/re-mint)
4238
// rather than deliberate directory deletion, which takes both.
4339
// 2. `deParallelRouterTrialFired` — the DE parallel-router circuit
4440
// breaker's tripped state, so a config re-mint does not re-enrol an
4541
// install into an experimental path that already FAILED on this machine.
4642
// 3. `bucketSeed` — the canary bucketing unit, so a re-mint does not
4743
// reshuffle cohorts mid-rollout. Never transmitted; only the resulting
48-
// true/false assignments are. Sharing CONFIG_DIR is what keeps it from
44+
// true/false assignments are. Sharing configDir() is what keeps it from
4945
// being a persistent identifier that outlives the user's reset.
5046
//
5147
// Removal path: delete ~/.hyperframes (or just this file). `hyperframes
5248
// telemetry status` prints its exact location.
5349
// ---------------------------------------------------------------------------
5450

55-
const STATE_FILE = join(CONFIG_DIR, "install-state.json");
51+
const stateFile = () => seededConfigFile("install-state.json");
5652

5753
// Pre-move location. Read once, migrated, then deleted — an install that
5854
// wrote state under the old scheme keeps its tripped breaker instead of
59-
// silently re-enrolling, and no file is left behind outside CONFIG_DIR.
55+
// silently re-enrolling, and no file is left behind outside configDir().
6056
const LEGACY_STATE_FILE = join(homedir(), ".local", "state", "hyperframes", "install-state.json");
6157

6258
interface InstallState {
@@ -231,7 +227,7 @@ function isInstallState(value: InstallState | InstallStateMiss): value is Instal
231227
* re-read harmlessly next time.
232228
*/
233229
function readInstallState(): InstallState | InstallStateMiss {
234-
const current = parseInstallState(STATE_FILE);
230+
const current = parseInstallState(stateFile());
235231
if (isInstallState(current)) {
236232
removeLegacyStateFile();
237233
return current;
@@ -281,10 +277,10 @@ export function __resetInstallStateSyncForTests(): void {
281277
* since a corrupted state file silently reads as absent.
282278
*/
283279
function writeInstallState(next: InstallState): void {
284-
mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
285-
const tmpFile = `${STATE_FILE}.${process.pid}.tmp`;
280+
mkdirSync(configDir(), { recursive: true, mode: 0o700 });
281+
const tmpFile = `${stateFile()}.${process.pid}.tmp`;
286282
writeFileSync(tmpFile, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
287-
renameSync(tmpFile, STATE_FILE);
283+
renameSync(tmpFile, stateFile());
288284
}
289285

290286
/**
@@ -344,7 +340,7 @@ function syncInstallState(config: HyperframesConfig): boolean {
344340
// the freshly minted seed lived in config.json alone, and the NEXT
345341
// config-only re-mint rolled a third seed instead of inheriting the second.
346342
// One existsSync on a path we are about to write anyway.
347-
if (stateMarkerSynced && !existsSync(STATE_FILE)) {
343+
if (stateMarkerSynced && !existsSync(stateFile())) {
348344
stateMarkerSynced = false;
349345
stateFiredSynced = false;
350346
}
@@ -799,10 +795,10 @@ function materializeConfig(parsed: Partial<HyperframesConfig>): HyperframesConfi
799795
export function readConfig(): HyperframesConfig {
800796
if (cachedConfig) return { ...cachedConfig };
801797

802-
if (!existsSync(CONFIG_FILE)) return mintAndCacheConfig();
798+
if (!existsSync(configFile())) return mintAndCacheConfig();
803799

804800
try {
805-
const raw = readFileSync(CONFIG_FILE, "utf-8");
801+
const raw = readFileSync(configFile(), "utf-8");
806802
const parsed = JSON.parse(raw) as Partial<HyperframesConfig>;
807803

808804
const config = materializeConfig(parsed);
@@ -958,7 +954,7 @@ function consentFrom(value: unknown): boolean | undefined {
958954

959955
function localModelConsentOnDisk(): boolean | undefined {
960956
try {
961-
return consentFrom(JSON.parse(readFileSync(CONFIG_FILE, "utf-8")).localEmbeddingEnabled);
957+
return consentFrom(JSON.parse(readFileSync(configFile(), "utf-8")).localEmbeddingEnabled);
962958
} catch (error) {
963959
// A settings file that exists but cannot be read may hold a no; only a missing one was never asked.
964960
return (error as NodeJS.ErrnoException).code === "ENOENT" ? undefined : false;
@@ -970,8 +966,8 @@ let holdingConfigLock = false;
970966
/** One process at a time between reading config.json and replacing it; re-entrant within this one. */
971967
function withConfigLock<T>(task: () => T): T {
972968
if (holdingConfigLock) return task();
973-
mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
974-
return withFileLock(`${CONFIG_FILE}.lock`, fs, () => {
969+
mkdirSync(configDir(), { recursive: true, mode: 0o700 });
970+
return withFileLock(`${configFile()}.lock`, fs, () => {
975971
holdingConfigLock = true;
976972
try {
977973
return task();
@@ -983,10 +979,10 @@ function withConfigLock<T>(task: () => T): T {
983979

984980
function persistConfig(config: HyperframesConfig): ConfigWriteResult {
985981
try {
986-
mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
987-
const tmpFile = `${CONFIG_FILE}.${process.pid}.tmp`;
982+
mkdirSync(configDir(), { recursive: true, mode: 0o700 });
983+
const tmpFile = `${configFile()}.${process.pid}.tmp`;
988984
writeFileSync(tmpFile, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
989-
renameSync(tmpFile, CONFIG_FILE);
985+
renameSync(tmpFile, configFile());
990986
cachedConfig = { ...config };
991987
// Mirror into the install-state file (marker + tripped breaker) so no
992988
// breaker write site has to remember to do it. A failed mirror does NOT
@@ -1013,7 +1009,7 @@ export function incrementCommandCount(): number {
10131009
}
10141010

10151011
/** Expose the config directory path for the telemetry command output */
1016-
export const CONFIG_PATH = CONFIG_FILE;
1012+
export const CONFIG_PATH = configFile();
10171013

10181014
/** Expose the install-state path for the telemetry command output. */
1019-
export const STATE_PATH = STATE_FILE;
1015+
export const STATE_PATH = stateFile();

‎packages/cli/src/utils/autoUpdate.invocation.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ async function patchAvailableAt(entry: string) {
4343
VERSION: "0.8.231",
4444
}));
4545
vi.doMock("./env.js", () => ({ isDevMode: () => false }));
46+
vi.doMock("./runningCli.js", async (importOriginal) => ({
47+
...(await importOriginal<typeof import("./runningCli.js")>()),
48+
registeredAsRunning: () => true,
49+
}));
4650
vi.doMock("./attendedTerminal.js", async (importOriginal) => ({
4751
...(await importOriginal<typeof import("./attendedTerminal.js")>()),
4852
isUnattended: () => false,

‎packages/cli/src/utils/autoUpdate.test.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ function setupMocks(opts: {
2727
env?: Record<string, string | undefined>;
2828
writeFails?: boolean;
2929
unattended?: boolean;
30+
registered?: boolean;
3031
}): {
3132
writeSpy: ReturnType<typeof vi.fn>;
3233
spawnSpy: ReturnType<typeof vi.fn>;
@@ -51,6 +52,10 @@ function setupMocks(opts: {
5152
writeConfig: writeSpy,
5253
}));
5354
vi.doMock("./env.js", () => ({ isDevMode: () => !!opts.devMode }));
55+
vi.doMock("./runningCli.js", async (importOriginal) => ({
56+
...(await importOriginal<typeof import("./runningCli.js")>()),
57+
registeredAsRunning: () => opts.registered ?? true,
58+
}));
5459
vi.doMock("./attendedTerminal.js", async (importOriginal) => ({
5560
...(await importOriginal<typeof import("./attendedTerminal.js")>()),
5661
isUnattended: () => opts.unattended ?? false,
@@ -108,6 +113,7 @@ describe("scheduleBackgroundInstall", () => {
108113
process.env = { ...ORIGINAL_ENV };
109114
vi.doUnmock("../telemetry/config.js");
110115
vi.doUnmock("./env.js");
116+
vi.doUnmock("./runningCli.js");
111117
vi.doUnmock("./installerDetection.js");
112118
vi.doUnmock("node:child_process");
113119
vi.doUnmock("node:fs");
@@ -129,6 +135,18 @@ describe("scheduleBackgroundInstall", () => {
129135
expect(config.pendingUpdate?.command).toBe("npm install -g [email protected]");
130136
});
131137

138+
it("schedules nothing from a CLI that could not put itself on record as running", async () => {
139+
const { spawnSpy, writeSpy } = setupMocks({
140+
installer: { kind: "npm", command: "npm install -g [email protected]" },
141+
registered: false,
142+
});
143+
const { scheduleBackgroundInstall } = await import("./autoUpdate.js");
144+
145+
expect(scheduleBackgroundInstall("0.4.4", "0.4.3")).toBe(false);
146+
expect(spawnSpy).not.toHaveBeenCalled();
147+
expect(writeSpy).not.toHaveBeenCalled();
148+
});
149+
132150
it("launches nothing when the pending install cannot be recorded", async () => {
133151
const { spawnSpy } = setupMocks({
134152
installer: { kind: "npm", command: "npm install -g [email protected]" },

0 commit comments

Comments
 (0)