feat(cli): stage the sixty-day publish transition (#7136)

This commit is contained in:
terencecho
2026-11-09 16:10:32 -08:00
committed by Terence Cho
parent 8d86e2cdcd
commit 4a4f0d65e7
9 changed files with 276 additions and 8 deletions
+9 -1
View File
@@ -110,7 +110,7 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and
| Skill | Use when |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/hyperframes` | **Read first** for any request to make, edit, animate or render a video, motion graphic, captions or overlays with HyperFrames (HTML rendered to video). Holds the render contract and the work loop, and points to the references for format, motion, look, captions, whole films and storyboards. |
| `/hyperframes-cli` | The HyperFrames CLI by job — scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history — plus reading its JSON and recovering from build or render failures. |
| `/hyperframes-cli` | The HyperFrames CLI by job — scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, share, project history — plus reading its JSON and recovering from build or render failures. |
| `/hyperframes-registry` | About 450 ready-made blocks and components installed as editable source — transitions, overlays, titles, kinetic type, captions, charts, maps, 3D, camera moves. Use before hand-building any named visual; also for `hyperframes add` and `catalog`. |
| `/media-use` | Get or make any media for a video — music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks — with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull. |
| `/reverse-any-video` | Rebuilding any video file as an editable HyperFrames project (motion graphics, talking heads, live action, AI-generated footage), checked frame by frame against the original. HyperFrames Pro. |
@@ -362,3 +362,11 @@ GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes.git
## License
[Apache 2.0](LICENSE)
### Share a video for review
Sign in with `npx hyperframes auth login`, then run `npx hyperframes share` to
choose who can open the rendered review. Use `share --update` when edits should
become a new version and `share --manage` for web settings. CLI and Desktop use
the same sharing system and five free projects per workspace. Existing legacy
published links remain reachable.
+9
View File
@@ -1104,6 +1104,15 @@ editor, just playback. Same flags, `--port` defaults to 3003, plus `--proxy` /
### `publish`
For new video reviews, use [`share`](#share). Legacy source publishing stays
available with a notice for 60 days from an announced notice release. That
release date has not been scheduled. After the window, new `publish` runs guide
you to `share`, where you choose a new audience; old flags are never silently
translated. Existing published URLs and legacy updates remain supported under
a separate retirement plan. After the window, sign in with `hyperframes auth login`
to update an existing publication; signed-out and API-key publishing cannot
preserve its ownership. Legacy server handling of missing update targets is unchanged.
Upload the project and get back a stable `hyperframes.studio` URL.
```bash
+57 -2
View File
@@ -3,15 +3,24 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { tmpdir } from "node:os";
const publishState = vi.hoisted(() => ({ publish: vi.fn() }));
const publishState = vi.hoisted(() => ({ publish: vi.fn(), noticeRelease: null as string | null }));
vi.mock("../utils/publishProject.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../utils/publishProject.js")>()),
publishProjectArchive: publishState.publish,
}));
vi.mock("../share/publishTransition.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("../share/publishTransition.js")>();
return {
...actual,
checkPublishTransition: (args: { dir?: string; update?: string }) =>
actual.checkPublishTransition(args, publishState.noticeRelease),
};
});
import publishCommand, { examples, parseUpdateTarget } from "./publish.js";
import { ensureProjectId } from "../utils/projectLink.js";
import { ensureProjectId, writeProjectLink, writeTeamProject } from "../utils/projectLink.js";
import { writeStore as writeUnboundStore, type Credentials } from "../auth/store.js";
import { oauthIdentity } from "../auth/config.js";
import { consumeCommandResult } from "../utils/commandResult.js";
@@ -371,3 +380,49 @@ describe("publish --update / --space ownership preflight", () => {
}
});
});
describe("expired transition preserves only owned legacy updates", () => {
it.each(["anonymous", "api-key", "oauth"])(
"checks %s ownership before publication",
async (kind) => {
const project = mkdtempSync(join(tmpdir(), "hf-publish-transition-owner-"));
const config = mkdtempSync(join(tmpdir(), "hf-publish-transition-config-"));
vi.stubEnv("HYPERFRAMES_CONFIG_DIR", config);
vi.stubEnv("HEYGEN_API_KEY", kind === "api-key" ? "fixture-key" : "");
vi.stubEnv("HYPERFRAMES_API_KEY", "");
writeFileSync(join(project, "index.html"), VISIBLE_INDEX);
writeProjectLink(project, { projectId: "legacy", url: "https://hyperframes.dev/p/legacy" });
writeTeamProject(project, { projectId: "legacy" });
if (kind === "oauth")
await writeStore({ oauth: { access_token: "fixture-token" } }, join(config, "credentials"));
mockPublished({
projectId: "legacy",
url: "https://hyperframes.dev/p/legacy",
updated: true,
});
publishState.noticeRelease = "2020-01-01T00:00:00.000Z";
try {
const run = () =>
publishCommand.run?.({ args: { dir: project, yes: true, proxy: false } } as never);
if (kind === "oauth") {
await captureLog(run);
expect(publishState.publish).toHaveBeenCalledWith(
project,
expect.objectContaining({
projectId: "legacy",
credential: expect.objectContaining({ type: "oauth" }),
}),
);
} else {
await expect(run()).rejects.toMatchObject({ code: "legacy_publish_login_required" });
expect(publishState.publish).not.toHaveBeenCalled();
}
} finally {
publishState.noticeRelease = null;
vi.unstubAllEnvs();
rmSync(project, { recursive: true, force: true });
rmSync(config, { recursive: true, force: true });
}
},
);
});
+5 -1
View File
@@ -1,3 +1,4 @@
import { assertLegacyPublishOwner, checkPublishTransition } from "../share/publishTransition.js";
import { join, posix, relative, resolve } from "node:path";
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
import { existsSync } from "node:fs";
@@ -61,7 +62,7 @@ export function parseUpdateTarget(value: string): string {
export default defineCommand({
meta: {
name: "publish",
description: "Upload the project to a stable URL (private by default)",
description: "Legacy source publishing; use share for new video reviews",
},
args: {
dir: { type: "positional", description: "Project directory", required: false },
@@ -96,6 +97,7 @@ export default defineCommand({
},
},
async run({ args }) {
const publishPhase = checkPublishTransition(args);
if (args.yes !== true && isUnattended()) {
clack.confirmationRequired("hyperframes publish", "Pass --yes to publish without asking.");
}
@@ -183,6 +185,8 @@ export default defineCommand({
return;
}
assertLegacyPublishOwner(publishPhase, credential?.type === "oauth");
// --update / --space only take effect for a login (an API-key publish is never owned).
// Fail loudly rather than silently minting a fresh URL.
if (updateTarget || spaceOverride) {
@@ -0,0 +1,91 @@
import { describe, expect, it } from "vitest";
import { publishPhase, publishTransitionDecision } from "./publishTransition.js";
describe("announced 60-day publish transition", () => {
const start = "2027-01-01T00:00:00.000Z";
const day = 86_400_000;
it("never starts the clock from approval or installation", () => {
expect(publishPhase(null, Date.parse(start) + 365 * day)).toBe("unscheduled");
expect(publishPhase(start, Date.parse(start) - 1)).toBe("unscheduled");
});
it("preserves exactly sixty days and guides only after the boundary", () => {
expect(publishPhase(start, Date.parse(start))).toBe("compatibility");
expect(publishPhase(start, Date.parse(start) + 60 * day - 1)).toBe("compatibility");
expect(publishPhase(start, Date.parse(start) + 60 * day)).toBe("share");
});
it("retains legacy updates after the new-project transition", () => {
expect(publishTransitionDecision("share", true)).toBe("keep_legacy");
expect(publishTransitionDecision("share", false)).toBe("guide_to_share");
expect(publishTransitionDecision("compatibility", false)).toBe("keep_legacy");
});
it("fails on an invalid scheduled date rather than silently switching behavior", () => {
expect(() => publishPhase("invalid")).toThrow("timestamp");
});
});
import { afterEach, beforeEach, vi } from "vitest";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { assertLegacyPublishOwner, checkPublishTransition } from "./publishTransition.js";
import { writeProjectLink, writeTeamProject } from "../utils/projectLink.js";
import { CliUsageError } from "../utils/commandResult.js";
describe("publish transition guard", () => {
let dir: string;
const start = "2027-01-01T00:00:00.000Z";
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), "publish-transition-"));
vi.stubEnv("HYPERFRAMES_CONFIG_DIR", join(dir, "config"));
vi.spyOn(process.stderr, "write").mockReturnValue(true);
vi.useFakeTimers();
vi.setSystemTime(new Date("2027-04-01T00:00:00.000Z"));
});
afterEach(() => {
vi.useRealTimers();
vi.restoreAllMocks();
vi.unstubAllEnvs();
rmSync(dir, { recursive: true, force: true });
});
it("leaves the shipped window unscheduled even far in the future", () => {
vi.setSystemTime(new Date("2099-01-01T00:00:00.000Z"));
expect(() => checkPublishTransition({ dir })).not.toThrow();
expect(process.stderr.write).toHaveBeenCalledWith(
expect.stringContaining("not been scheduled"),
);
});
it("guides new projects without changing their audience or uploading", () => {
expect(() => checkPublishTransition({ dir }, start)).toThrowError(CliUsageError);
try {
checkPublishTransition({ dir }, start);
} catch (error) {
expect(error).toMatchObject({
code: "publish_replaced",
result: { exitCode: 2 },
hint: expect.stringContaining("do not convert"),
});
}
});
it("keeps explicit legacy updates and stored published links", () => {
expect(() => checkPublishTransition({ dir, update: "legacy-project" }, start)).not.toThrow();
writeProjectLink(dir, { projectId: "legacy", url: "https://hyperframes.dev/p/legacy" });
expect(() => checkPublishTransition({ dir }, start)).not.toThrow();
expect(process.stderr.write).toHaveBeenCalledWith(
expect.stringContaining("uses the legacy update workflow"),
);
});
it("keeps committed team project targets", () => {
writeTeamProject(dir, { projectId: "legacy-team", spaceId: "team" });
expect(() => checkPublishTransition({ dir }, start)).not.toThrow();
});
it("does not count an unused local identity or whitespace as a published project", () => {
writeProjectLink(dir, { projectId: "unused", url: "" });
expect(() => checkPublishTransition({ dir, update: " " }, start)).toThrowError(CliUsageError);
});
});
it("requires an owner after the window so legacy targets cannot silently create fresh projects", () => {
expect(() => assertLegacyPublishOwner("share", false)).toThrowError(CliUsageError);
expect(() => assertLegacyPublishOwner("share", true)).not.toThrow();
expect(() => assertLegacyPublishOwner("compatibility", false)).not.toThrow();
expect(() => assertLegacyPublishOwner("unscheduled", false)).not.toThrow();
});
@@ -0,0 +1,81 @@
import { resolve } from "node:path";
import { CliUsageError } from "../utils/commandResult.js";
import { asNotice } from "../utils/jsonError.js";
import { readProjectLink, readTeamProject } from "../utils/projectLink.js";
/** Set to the announced notice release's UTC timestamp in the release PR, after launch gates pass. */
const PUBLISH_NOTICE_RELEASE: string | null = null;
const PUBLISH_COMPATIBILITY_DAYS = 60;
export function publishPhase(
start: string | null,
now: number = Date.now(),
): "unscheduled" | "compatibility" | "share" {
if (!start) return "unscheduled";
const begins = Date.parse(start);
if (!Number.isFinite(begins)) throw new Error("Invalid publish transition release timestamp.");
if (now < begins) return "unscheduled";
return now < begins + PUBLISH_COMPATIBILITY_DAYS * 86_400_000 ? "compatibility" : "share";
}
export function publishTransitionDecision(
phase: ReturnType<typeof publishPhase>,
legacyUpdate: boolean,
) {
if (phase === "share" && !legacyUpdate) return "guide_to_share";
return "keep_legacy";
}
export function checkPublishTransition(
args: { dir?: string; update?: string },
noticeRelease: string | null = PUBLISH_NOTICE_RELEASE,
): ReturnType<typeof publishPhase> {
const dir = resolve(args.dir ?? ".");
const prior = readProjectLink(dir);
const legacyUpdate = Boolean(
args.update?.trim() || prior?.url || readTeamProject(dir)?.projectId,
);
const phase = publishPhase(noticeRelease);
asNotice(() => process.stderr.write(publishNotice(phase, legacyUpdate) + "\n"));
if (publishTransitionDecision(phase, legacyUpdate) === "guide_to_share") {
throw new CliUsageError(
"New projects now use hyperframes share. Run it from this project folder and choose an audience; for scripts pass --public, --team, --invite-only or --private explicitly.",
{
code: "publish_replaced",
hint: "Existing publications remain reachable. Use publish --update <url|id> for a legacy update. --yes and legacy --public do not convert a project or consent to a new review audience.",
},
);
}
return phase;
}
export function assertLegacyPublishOwner(
phase: ReturnType<typeof publishPhase>,
signedIn: boolean,
): void {
if (phase === "share" && !signedIn)
throw new CliUsageError(
"Updating an existing publication requires a signed-in account. Run hyperframes auth login, then retry.",
{
code: "legacy_publish_login_required",
hint: "Without a login, publishing would create a new project instead of updating the existing URL.",
},
);
}
function publishNotice(phase: ReturnType<typeof publishPhase>, update: boolean): string {
const kept = update
? " This run uses the legacy update workflow."
: " This run keeps legacy publishing behavior.";
if (phase === "unscheduled")
return (
"For new video reviews, use hyperframes share. The legacy publish transition date has not been scheduled." +
kept
);
if (phase === "compatibility")
return (
"Legacy publish is in its 60-day compatibility window. Use hyperframes share for new video reviews." +
kept
);
return (
"New projects use hyperframes share. Existing published URLs and explicit legacy updates remain supported." +
(update ? kept : "")
);
}
+1 -1
View File
@@ -10,7 +10,7 @@
"files": 78
},
"hyperframes-cli": {
"hash": "53ea8e568639d20a",
"hash": "484117bedc3ef05f",
"files": 13
},
"hyperframes-registry": {
+3 -3
View File
@@ -1,6 +1,6 @@
---
name: hyperframes-cli
description: The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
description: HyperFrames CLI - scaffold, check frames, edit timelines, preview, render, share and project history; read JSON and recover from failures.
---
**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).
@@ -24,7 +24,7 @@ A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is
| Edit the timeline | `timeline` with `move`, `trim`, `split`, `set`, `duplicate`, `delete`, `apply`, `undo`, `ids` |
| Reuse | `catalog`, `add` (`/hyperframes-registry`) |
| Media and sound | `media-treatment`, `grade-compare`, `remove-background`, `tts`, `transcribe`, `beats`, `normalize-audio` (`/media-use`) |
| Show and ship | `preview`, `present` (`/slideshow`), `render`, `publish`, `cloud`, `lambda`, `cloudrun` |
| Show and ship | `preview`, `present` (`/slideshow`), `render`, `share`, `publish` (legacy), `cloud`, `lambda`, `cloudrun` |
| Desktop app | `open`, `catch-up` |
| Upkeep | `doctor`, `browser`, `upgrade`, `usage`, `clean`, `feedback` |
@@ -94,7 +94,7 @@ Read the row before running its command.
| `lint`, `check`, motion sidecars, `snapshot` | `references/lint-validate-inspect.md` |
| `compare`, `grade-compare`, `render --batch` | `references/compare-and-batch.md` |
| `beats` | `references/beats.md` |
| `preview`, `play`, `render`, `publish`, Studio context | `references/preview-render.md` |
| `preview`, `play`, `render`, `share`, `publish` (legacy), Studio context | `references/preview-render.md` |
| `doctor`, `browser` | `references/doctor-browser.md` |
| `auth`, `cloud`, template variables | `references/cloud.md` |
| `lambda`, `cloudrun` | `references/lambda.md`, `references/cloudrun.md` |
@@ -202,3 +202,23 @@ Uploads the project's source (HTML + assets) and returns a stable hosted URL tha
Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS, and for the final render on a paid HyperFrames plan (`cloud.md`). Use Lambda only when AWS ownership is a requirement. Use Cloud Run only when GCP ownership is a requirement. Read the matching reference before running any cloud path.
Skill attribution is automatic — the examples above need no `--skill`. A project scaffolded with `hyperframes init --skill=<slug>` records its owning skill in `hyperframes.json`, and every later render inherits it on usage telemetry: re-renders, `npm run render`, and `--batch` alike. Pass `--skill=<slug>` explicitly only to stamp a project that was not scaffolded with one (its first render then persists it).
## Share a video for review
Use `hyperframes share --public` only when the user explicitly wants anyone with
the link to access the review. First sign in with `hyperframes auth login`.
Other first-share choices are `--team`, `--invite-only` and `--private`, subject
to workspace entitlement. `--yes` is not audience consent.
Read `hyperframes share --status --json`: `ready: true` is required before
calling the video ready to watch. Re-running `share` retrieves the existing
link; `share --update` explicitly renders/uploads changed content. Five retained
free projects are counted per workspace across CLI and Desktop; versions do
not consume slots and turning a link off does not release a slot.
`publish` uploads source to legacy `/p/` pages. It is not a review share alias.
During the announced 60-day window its old behavior stays available with a
notice. The start date is release-owned and currently unscheduled. After it, new
projects are guided to Share; existing publications and legacy updates stay
reachable. After the window, legacy updates require a signed-in account.
Never convert legacy IDs or carry a legacy flag into review consent.