mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
feat(cli): stage the sixty-day publish transition (#7136)
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
@@ -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 : "")
|
||||
);
|
||||
}
|
||||
@@ -10,7 +10,7 @@
|
||||
"files": 78
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "53ea8e568639d20a",
|
||||
"hash": "484117bedc3ef05f",
|
||||
"files": 13
|
||||
},
|
||||
"hyperframes-registry": {
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user