Files
hyperframes/packages/cli/src/commands/init.ts
T
wonjangandClaude Opus 5.5 213f7c5383 fix(cli): quote the project name in init's printed cd commands (#7608)
`hyperframes init --non-interactive` closes with `cd <name> && npm run …`
lines for the person or agent to paste. The name went in as typed, so a
name with a space or a quote printed a command that fails as written:
`cd my first video` (bash: "cd: my: No such file or directory", zsh: "too
many arguments") and `cd it's mine` (an unterminated quote).

A new `shellArg` quotes a word only when a shell would split or expand
it: double quotes, or single quotes when the text holds `$`, a backtick,
`\`, `"` or `!`; on Windows, double quotes, with `\` paths left bare.
`hyperframes open` / `preview --stop` hints (desktopApp's `shownDir`)
already quoted whitespace with JSON.stringify and now use it too, so a
name like `it's` or `a&b` is covered there as well.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 03:47:58 +00:00

1278 lines
46 KiB
TypeScript

// The scaffolding command predates the complexity gate: run(), probeVideo,
// handleVideoFile, and applyResolutionPreset carry its interactive branching.
// This branch only repointed the scaffolded npm scripts; the refactor is its
// own task.
// fallow-ignore-file complexity
import { failCommand, finishCommand, failUsage } from "../utils/commandResult.js";
import { writeNewFileSync } from "../utils/writeNewFile.js";
import { runCommand } from "citty";
import { defineCommand } from "../utils/defineCommand.js";
import type { Example } from "./_examples.js";
import { patchMediaPlaceholders, type InitMediaOptions } from "./initMedia.js";
export const examples: Example[] = [
["Create a project with the interactive wizard", "hyperframes init my-video"],
["Pick a starter example", "hyperframes init my-video --example warm-grain"],
["Scaffold a 4K project", "hyperframes init my-video --resolution 4k"],
["Scaffold a portrait video", "hyperframes init my-video --resolution portrait"],
["Start from an existing video file", "hyperframes init my-video --video clip.mp4"],
["Start from an audio file", "hyperframes init my-video --audio track.mp3"],
["Scaffold with Tailwind CSS", "hyperframes init my-video --tailwind"],
["Non-interactive mode (for CI or AI agents)", "hyperframes init my-video --non-interactive"],
["Skip installing AI skills", "hyperframes init my-video --skip-skills"],
];
import {
existsSync,
lstatSync,
mkdirSync,
copyFileSync,
statSync,
writeFileSync,
readFileSync,
readdirSync,
} from "node:fs";
import { copyDirSync } from "../utils/copyDir.js";
import { resolve, basename, join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { execFileSync, spawn } from "node:child_process";
import * as clack from "../ui/prompts.js";
import { c } from "../ui/colors.js";
import { isUnattended } from "../utils/attendedTerminal.js";
import { printBanner } from "../ui/banner.js";
import {
BUNDLED_TEMPLATES,
resolveTemplateList,
type TemplateOption,
} from "../templates/generators.js";
import { fetchRemoteTemplate } from "../templates/remote.js";
import { trackInitTemplate } from "../telemetry/events.js";
import { DEFAULT_MODEL, hasFFmpeg } from "../whisper/manager.js";
import { TRANSCRIPT_FILE } from "../whisper/transcriptFile.js";
import { initialModelForLanguage } from "../whisper/transcribe.js";
import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
import { VERSION } from "../version.js";
import {
CANVAS_DIMENSIONS,
normalizeResolutionFlag,
type CanvasResolution,
} from "@hyperframes/core";
import {
HTML_BODY_CSS_HEIGHT_FIRST_RE,
HTML_BODY_CSS_WIDTH_FIRST_RE,
VIEWPORT_META_SIZE_RE,
} from "@hyperframes/parsers";
import { decodableAudioStream } from "@hyperframes/parsers/media-streams";
import { cliSourced } from "../utils/sourceTag.js";
import { shellArg } from "../utils/shellArg.js";
function resolveScaffoldTemplateId(exampleFlag: string | undefined, hasMediaFile: boolean): string {
const example = exampleFlag === "agent" ? "blank" : exampleFlag;
if (example && example !== "blank") return example;
if (hasMediaFile) return "from-file";
return "blank";
}
interface VideoMeta {
durationSeconds: number;
width: number;
height: number;
fps: number;
hasAudio: boolean;
videoCodec: string;
}
const WEB_CODECS = new Set(["h264", "vp8", "vp9", "av1"]);
const DEFAULT_META: VideoMeta = {
durationSeconds: 5,
width: 1920,
height: 1080,
fps: 30,
// ffprobe unavailable: assume sound. A wrong guess fails loudly at RENDER (lint catches it only once #3638 lands); assuming silence would mute real audio.
hasAudio: true,
videoCodec: "h264",
};
// Pin the browser runtime exactly so repeated renders do not drift as Tailwind
// ships JIT/preflight changes on the CDN.
const TAILWIND_BROWSER_VERSION = "4.2.4";
const TAILWIND_BROWSER_SRC = `https://cdn.jsdelivr.net/npm/@tailwindcss/browser@${TAILWIND_BROWSER_VERSION}/dist/index.global.js`;
const TAILWIND_BROWSER_INTEGRITY =
"sha384-v5YF9xS+gLRWdvrQ0u/WRbCkjSIH0NjHIPe8tBL1ZRrmI7PiSH6LLdzs0aAIMCuh";
export function resolveVideoDurationSeconds({
streamDuration,
frameDuration,
formatDuration,
}: {
streamDuration: number;
frameDuration: number;
formatDuration: number;
}): number {
return (
[streamDuration, frameDuration, formatDuration].find(
(duration) => Number.isFinite(duration) && duration > 0,
) ?? DEFAULT_META.durationSeconds
);
}
// ---------------------------------------------------------------------------
// ffprobe helper — shells out to ffprobe to avoid engine dependency
// ---------------------------------------------------------------------------
function probeVideo(filePath: string): VideoMeta | undefined {
try {
const ffprobePath = findFFprobe();
if (!ffprobePath) return undefined;
const raw = execFileSync(
ffprobePath,
["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "--", filePath],
{ encoding: "utf-8", timeout: 15_000 },
);
const parsed: {
streams?: {
codec_type?: string;
codec_name?: string;
width?: number;
height?: number;
r_frame_rate?: string;
avg_frame_rate?: string;
duration?: string;
nb_frames?: string;
tags?: { rotate?: string };
side_data_list?: { rotation?: number }[];
sample_aspect_ratio?: string;
}[];
format?: { duration?: string };
} = JSON.parse(raw);
const streams = parsed.streams ?? [];
const videoStream = streams.find((s) => s.codec_type === "video");
if (!videoStream) return undefined;
const hasAudio = decodableAudioStream(streams) !== null;
let fps = 30;
const fpsStr = videoStream.avg_frame_rate ?? videoStream.r_frame_rate;
if (fpsStr) {
const parts = fpsStr.split("/");
const num = parseFloat(parts[0] ?? "");
const den = parseFloat(parts[1] ?? "1");
if (den !== 0 && !Number.isNaN(num) && !Number.isNaN(den)) {
fps = Math.round((num / den) * 100) / 100;
}
}
const streamDuration = parseFloat(videoStream.duration ?? "");
const frameCount = parseInt(videoStream.nb_frames ?? "", 10);
const frameDuration = Number.isFinite(frameCount) && fps > 0 ? frameCount / fps : NaN;
const formatDuration = parseFloat(parsed.format?.duration ?? "");
const durationSeconds = resolveVideoDurationSeconds({
streamDuration,
frameDuration,
formatDuration,
});
// Non-square pixels (anamorphic SD, "64:45") play wider or narrower than they are stored.
const [sarW, sarH] = (videoStream.sample_aspect_ratio ?? "").split(":").map(Number);
const sar = sarW && sarH ? sarW / sarH : 1;
const width = Math.round((videoStream.width ?? 1920) * sar);
const height = videoStream.height ?? 1080;
// A phone clip is often stored landscape with a rotation; it plays (and decodes) turned upright.
const turn = Number(
videoStream.side_data_list?.find((d) => d.rotation !== undefined)?.rotation ??
videoStream.tags?.rotate ??
0,
);
const turned = Math.abs(turn) % 180 === 90;
return {
durationSeconds,
width: turned ? height : width,
height: turned ? width : height,
fps,
hasAudio,
videoCodec: videoStream.codec_name ?? "unknown",
};
} catch {
return undefined;
}
}
type CanvasSize = { width: number; height: number };
// A from-file stage is the clip at its own shape, 1080 short side like every preset; 16:9 is the template's own.
function clipFrame(templateId: string, clip: CanvasSize | undefined): CanvasSize | undefined {
if (templateId !== "from-file" || !clip || !(clip.width > 0 && clip.height > 0)) return undefined;
const even = (n: number) => 2 * Math.round(n / 2);
const frame =
clip.width >= clip.height
? { width: even((1080 * clip.width) / clip.height), height: 1080 }
: { width: 1080, height: even((1080 * clip.height) / clip.width) };
return frame.width === 1920 && frame.height === 1080 ? undefined : frame;
}
function isWebCompatible(codec: string): boolean {
return WEB_CODECS.has(codec.toLowerCase());
}
// hasFFmpeg is imported from whisper/manager.ts to avoid duplication
export function transcodeToMp4(inputPath: string, outputPath: string): Promise<boolean> {
return new Promise((resolvePromise) => {
const ffmpegPath = findFFmpeg();
if (!ffmpegPath) {
resolvePromise(false);
return;
}
const child = spawn(
ffmpegPath,
[
"-i",
inputPath,
"-c:v",
"libx264",
"-preset",
"fast",
"-crf",
"18",
"-c:a",
"aac",
"-b:a",
"192k",
"-y",
outputPath,
],
{ stdio: "ignore", windowsHide: true },
);
child.on("close", (code) => resolvePromise(code === 0));
child.on("error", () => resolvePromise(false));
});
}
// ---------------------------------------------------------------------------
// Static template helpers
// ---------------------------------------------------------------------------
/** Resolve an asset directory that differs between dev (src/) and built (dist/). */
function resolveAssetDir(devSegments: string[], builtSegments: string[]): string {
const base = dirname(fileURLToPath(import.meta.url));
const devPath = resolve(base, ...devSegments);
const builtPath = resolve(base, ...builtSegments);
return existsSync(devPath) ? devPath : builtPath;
}
// Resolves bundled templates shipped inside the CLI package
// (packages/cli/src/templates/<id> in dev, dist/templates/<id> when packed).
// Dev-mode also checks registry/examples/<id> so that smoke CI tests pick up
// PR-branch template changes before the PR is merged to main.
function getStaticTemplateDir(templateId: string): string {
const base = dirname(fileURLToPath(import.meta.url));
const devPath = resolve(base, "..", "templates", templateId);
if (existsSync(devPath)) return devPath;
// fallback: repo-root registry/examples/<id> (4 levels up from src/commands/)
const registryPath = resolve(base, "..", "..", "..", "..", "registry", "examples", templateId);
if (existsSync(registryPath)) return registryPath;
return resolve(base, "templates", templateId);
}
function getSharedTemplateDir(): string {
return resolveAssetDir(["..", "templates", "_shared"], ["templates", "_shared"]);
}
const MEDIA_THE_SCAFFOLD_NEVER_WRITES =
/\.(mp4|m4v|mov|webm|mkv|avi|mpe?g|wav|mp3|m4a|aac|ogg|oga|opus|flac)$/i;
function fileOnDisk(path: string): string | undefined {
try {
const { dev, ino } = statSync(path);
return `${dev}:${ino}`;
} catch {
return undefined;
}
}
function holdsFilesBesideProjectConfigOrSources(
dir: string,
sources: (string | undefined)[] = [],
): boolean {
const kept = new Set(
sources.flatMap((s) => (s && MEDIA_THE_SCAFFOLD_NEVER_WRITES.test(s) ? [fileOnDisk(s)] : [])),
);
kept.delete(undefined);
const isKeptSource = (name: string) =>
MEDIA_THE_SCAFFOLD_NEVER_WRITES.test(name) && kept.has(fileOnDisk(resolve(dir, name)));
return (
existsSync(dir) &&
readdirSync(dir).some((name) => name !== "hyperframes.json" && !isKeptSource(name))
);
}
function nothingAt(path: string): boolean {
try {
lstatSync(path);
return false;
} catch {
return true;
}
}
/**
* The first of `name.mp4`, `name.h264.mp4`, `name.h264-2.mp4`, ... with nothing at its path. FFmpeg
* overwrites its output, and a link or a case-only spelling there can be the source itself.
*/
function freeTranscodeName(destDir: string, localVideoName: string): string {
const stem = localVideoName.replace(/\.[^.]+$/, "");
for (let n = 0; ; n++) {
const name = n === 0 ? `${stem}.mp4` : `${stem}.h264${n === 1 ? "" : `-${n}`}.mp4`;
if (nothingAt(resolve(destDir, name))) return name;
}
}
function copyIntoProjectUnlessAlreadyThere(src: string, dest: string): void {
const same = resolve(src) === resolve(dest) || fileOnDisk(src) === (fileOnDisk(dest) ?? "");
if (!same) copyFileSync(src, dest);
}
/** The longest folder name the common disks hold: 255 UTF-8 bytes on Linux, 255 UTF-16 units on macOS and Windows. */
const MAX_FOLDER_NAME = 255;
/** One plain sentence when a folder in `name` is too long for the disk, null when all fit. Checked before mkdir,
* which otherwise throws Node's raw ENAMETOOLONG and the full path (repro: init a 256-character name). */
export function nameTooLongMessage(
name: string,
platform: NodeJS.Platform = process.platform,
): string | null {
const inBytes = platform === "linux";
const unit = inBytes ? "bytes" : "characters";
for (const folder of name.split(platform === "win32" ? /[\\/]/ : "/")) {
const length = inBytes ? Buffer.byteLength(folder) : folder.length;
if (length > MAX_FOLDER_NAME)
return `That name is ${length} ${unit} long; a folder name can be at most ${MAX_FOLDER_NAME} ${unit}.`;
}
return null;
}
function toPackageName(projectName: string): string {
const normalized = basename(projectName)
.trim()
.toLowerCase()
.replace(/^[._]+/, "")
.replace(/[^a-z0-9._~-]+/g, "-")
.replace(/-+/g, "-")
.replace(/^[-.]+|[-.]+$/g, "");
return normalized || "hyperframes-project";
}
function getHyperframesPackageSpecifier(): string {
return VERSION === "0.0.0-dev" ? "hyperframes" : `hyperframes@${VERSION}`;
}
function hyperframesScript(command: string): string {
return `npx --yes ${getHyperframesPackageSpecifier()} ${command}`;
}
function buildPackageScripts(): Record<string, string> {
return {
dev: hyperframesScript("preview"),
check: hyperframesScript("check"),
render: hyperframesScript("render"),
publish: hyperframesScript("publish"),
};
}
function writeDefaultPackageJson(destDir: string, projectName: string): void {
const packageJsonPath = resolve(destDir, "package.json");
if (existsSync(packageJsonPath)) return;
writeNewFileSync(
packageJsonPath,
`${JSON.stringify(
{
name: toPackageName(projectName),
private: true,
type: "module",
scripts: buildPackageScripts(),
},
null,
2,
)}\n`,
);
}
function listHtmlFiles(dir: string): string[] {
const files: string[] = [];
const ignoredDirs = new Set([".git", "dist", "node_modules"]);
function walk(currentDir: string): void {
for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
const entryPath = join(currentDir, entry.name);
if (entry.isDirectory()) {
if (!ignoredDirs.has(entry.name)) walk(entryPath);
continue;
}
if (entry.isFile() && entry.name.endsWith(".html")) {
files.push(entryPath);
}
}
}
walk(dir);
return files;
}
export function injectTailwindBrowserScript(html: string): string {
if (html.includes(TAILWIND_BROWSER_SRC)) return html;
const script = [
`<script>`,
`window.__tailwindReady=new Promise(function(resolve){`,
`var loaded=document.readyState==="complete";`,
`var resolved=false;`,
`var observer;`,
`function readTailwindCss(){var styles=document.querySelectorAll("style");for(var i=styles.length-1;i>=0;i--){var text=styles[i].textContent||"";if(text.indexOf("tailwindcss v")!==-1)return text;}return "";}`,
`function finish(){if(resolved||!loaded||!readTailwindCss())return;resolved=true;if(observer)observer.disconnect();resolve(true);}`,
`observer=new MutationObserver(finish);`,
`observer.observe(document.documentElement,{childList:true,subtree:true,characterData:true});`,
`if(loaded){finish();}else{window.addEventListener("load",function(){loaded=true;finish();},{once:true});}`,
`});`,
`</script>`,
`<script src="${TAILWIND_BROWSER_SRC}" integrity="${TAILWIND_BROWSER_INTEGRITY}" crossorigin="anonymous"></script>`,
].join("\n");
if (/<\/head>/i.test(html)) {
return html.replace(/<\/head>/i, (closingHead) => `\n${script}\n${closingHead}`);
}
return `${script}\n${html}`;
}
function writeTailwindSupport(destDir: string): void {
for (const file of listHtmlFiles(destDir)) {
const html = readFileSync(file, "utf-8");
writeFileSync(file, injectTailwindBrowserScript(html), "utf-8");
}
}
function patchVideoSrc(dir: string, media: InitMediaOptions): void {
const htmlFiles = readdirSync(dir, { withFileTypes: true, recursive: true })
.filter((e) => e.isFile() && e.name.endsWith(".html"))
.map((e) => join(e.parentPath, e.name));
for (const file of htmlFiles) {
writeFileSync(file, patchMediaPlaceholders(readFileSync(file, "utf-8"), media), "utf-8");
}
}
async function finishScaffold(destDir: string, templateId: string, tailwind: boolean) {
trackInitTemplate(templateId, { tailwind });
const transcriptFile = resolve(destDir, TRANSCRIPT_FILE);
if (existsSync(transcriptFile)) await patchTranscript(destDir, transcriptFile);
}
async function patchTranscript(dir: string, transcriptPath: string): Promise<void> {
const { loadTranscript, patchCaptionHtml } = await import("../whisper/normalize.js");
const { words } = loadTranscript(transcriptPath);
if (words.length === 0) return;
patchCaptionHtml(dir, words);
}
// ---------------------------------------------------------------------------
// handleVideoFile — probe, check codec, optionally transcode, copy to destDir
// ---------------------------------------------------------------------------
async function handleVideoFile(
videoPath: string,
destDir: string,
interactive: boolean,
keepOriginal: boolean,
): Promise<{ meta: VideoMeta; localVideoName: string }> {
const probed = probeVideo(videoPath);
let meta: VideoMeta = { ...DEFAULT_META };
let localVideoName = basename(videoPath);
if (probed) {
meta = probed;
if (interactive) {
clack.log.info(
`Video: ${meta.width}x${meta.height}, ${meta.durationSeconds.toFixed(1)}s, ${meta.fps}fps${meta.hasAudio ? ", has audio" : ""}`,
);
}
} else {
const msg = `ffprobe not found — using defaults (1920x1080, 5s, 30fps) and assuming the video has sound (data-has-audio="true"); if it is silent, replace that with muted. Install: ${getFFmpegInstallHint()}`;
if (interactive) {
clack.log.warn(msg);
} else {
console.log(c.warn(msg));
}
}
// Check codec compatibility
if (probed && !keepOriginal && !isWebCompatible(probed.videoCodec)) {
if (interactive) {
clack.log.warn(
c.warn(`Video codec "${probed.videoCodec}" is not supported by web browsers.`),
);
} else {
console.log(c.warn(`Video codec "${probed.videoCodec}" is not supported by browsers.`));
}
if (hasFFmpeg()) {
let shouldTranscode = !interactive; // non-interactive auto-transcodes
if (interactive) {
const transcode = await clack.select({
message: "Transcode to H.264 MP4 for browser playback?",
options: [
{
value: "yes",
label: "Yes, transcode",
hint: "converts to H.264 MP4",
},
{
value: "no",
label: "No, keep original",
hint: "video won't play in browser",
},
],
});
if (clack.isCancel(transcode)) {
clack.cancel("Setup cancelled.");
finishCommand(0);
}
shouldTranscode = transcode === "yes";
}
if (shouldTranscode) {
const mp4Name = freeTranscodeName(destDir, localVideoName);
const mp4Path = resolve(destDir, mp4Name);
const spin = clack.spinner();
spin.start("Transcoding to H.264 MP4...");
const ok = await transcodeToMp4(videoPath, mp4Path);
if (ok) {
spin.stop(c.success(`Transcoded to ${mp4Name}`));
localVideoName = mp4Name;
} else {
spin.stop(c.warn("Transcode failed — copying original file"));
copyIntoProjectUnlessAlreadyThere(videoPath, resolve(destDir, localVideoName));
}
} else {
copyIntoProjectUnlessAlreadyThere(videoPath, resolve(destDir, localVideoName));
}
} else {
if (interactive) {
clack.log.warn(c.dim("ffmpeg not installed — cannot transcode."));
clack.log.info(c.accent(`Install: ${getFFmpegInstallHint()}`));
} else {
console.log(c.warn("ffmpeg not installed — cannot transcode. Copying original."));
console.log(c.dim("Install: ") + c.accent(getFFmpegInstallHint()));
}
copyIntoProjectUnlessAlreadyThere(videoPath, resolve(destDir, localVideoName));
}
} else {
copyIntoProjectUnlessAlreadyThere(videoPath, resolve(destDir, localVideoName));
}
return { meta, localVideoName };
}
// ---------------------------------------------------------------------------
// applyResolutionPreset — rewrite stage dimensions in scaffolded HTML
// ---------------------------------------------------------------------------
/**
* Rewrite the canvas dimensions in every scaffolded HTML file to match a
* preset. We rewrite by regex rather than DOM-parsing so template comments
* and indentation survive byte-for-byte — these are review-target files,
* not transient build artifacts.
*
* Scope: HTML files only. Templates whose `#stage` dimensions live in an
* external `.css` stylesheet are not patched — the bundled `blank` template
* inlines its CSS, and that's the convention for new templates. If you
* author a template with external CSS, replicate the dimension swap there
* by hand or move the dimensions inline.
*/
export function applyResolutionPreset(destDir: string, resolution: CanvasResolution): void {
applyCanvasSize(destDir, CANVAS_DIMENSIONS[resolution], resolution);
}
function applyCanvasSize(
destDir: string,
{ width, height }: CanvasSize,
resolution?: CanvasResolution,
): void {
for (const file of listHtmlFiles(destDir)) {
let html = readFileSync(file, "utf-8");
let changed = false;
const dataWidthRe = /(data-width=)["'](\d+)["']/g;
if (dataWidthRe.test(html)) {
html = html.replace(dataWidthRe, `$1"${width}"`);
changed = true;
}
const dataHeightRe = /(data-height=)["'](\d+)["']/g;
if (dataHeightRe.test(html)) {
html = html.replace(dataHeightRe, `$1"${height}"`);
changed = true;
}
const htmlOpenRe = /<html\b([^>]*)>/i;
const htmlOpen = html.match(htmlOpenRe);
if (htmlOpen && resolution) {
const attrs = htmlOpen[1] ?? "";
let next: string;
if (/data-resolution=/.test(attrs)) {
next = attrs.replace(/data-resolution=["'][^"']*["']/, `data-resolution="${resolution}"`);
} else {
next = `${attrs.replace(/\s+$/, "")} data-resolution="${resolution}"`;
}
if (next !== attrs) {
html = html.replace(htmlOpenRe, `<html${next}>`);
changed = true;
}
}
// Inline `html, body { ... }` CSS: handle width-before-height and
// height-before-width orderings. Hand-authored templates can use either.
// Groups 1 and 3 are the text before each dimension, 2 and 4 the digits.
if (HTML_BODY_CSS_WIDTH_FIRST_RE.test(html)) {
html = html.replace(HTML_BODY_CSS_WIDTH_FIRST_RE, `$1${width}px$3${height}px`);
changed = true;
}
if (HTML_BODY_CSS_HEIGHT_FIRST_RE.test(html)) {
html = html.replace(HTML_BODY_CSS_HEIGHT_FIRST_RE, `$1${height}px$3${width}px`);
changed = true;
}
if (VIEWPORT_META_SIZE_RE.test(html)) {
html = html.replace(VIEWPORT_META_SIZE_RE, `$1${width}$3${height}`);
changed = true;
}
if (changed) writeFileSync(file, html, "utf-8");
}
}
// ---------------------------------------------------------------------------
// scaffoldProject — copy template, patch video refs, write meta.json
// ---------------------------------------------------------------------------
async function scaffoldProject(
destDir: string,
name: string,
templateId: string,
media: InitMediaOptions,
tailwind = false,
canvas?: CanvasResolution | CanvasSize,
authoringSkill?: string,
): Promise<void> {
mkdirSync(destDir, { recursive: true });
// Use bundled template if available, otherwise fetch from GitHub.
// Check for index.html inside the dir — an empty directory left by the
// build toolchain should not prevent the remote fetch fallback.
const templateDir = getStaticTemplateDir(templateId);
if (existsSync(join(templateDir, "index.html"))) {
copyDirSync(templateDir, destDir);
} else {
await fetchRemoteTemplate(templateId, destDir);
}
patchVideoSrc(destDir, media);
if (tailwind) writeTailwindSupport(destDir);
if (typeof canvas === "string") applyResolutionPreset(destDir, canvas);
else if (canvas) applyCanvasSize(destDir, canvas);
writeFileSync(
resolve(destDir, "meta.json"),
JSON.stringify(
{
id: name,
name,
createdAt: new Date().toISOString(),
},
null,
2,
),
"utf-8",
);
// Write hyperframes.json so `hyperframes add` knows which registry to use
// and where to drop block/component files. Overwritten only if absent.
// When the scaffolding workflow declared itself via --skill, stamp the owning
// skill here so every later render of this project is attributed to it.
if (!existsSync(resolve(destDir, "hyperframes.json"))) {
const { createProjectConfig, DEFAULT_PROJECT_CONFIG } =
await import("../utils/projectConfig.js");
const { normalizeSkillSlug } = await import("../telemetry/skill.js");
const skill = normalizeSkillSlug(authoringSkill);
createProjectConfig(
destDir,
skill ? { ...DEFAULT_PROJECT_CONFIG, authoringSkill: skill } : DEFAULT_PROJECT_CONFIG,
);
}
writeDefaultPackageJson(destDir, name);
// Copy shared files (CLAUDE.md, AGENTS.md) for AI agent context
const sharedDir = getSharedTemplateDir();
if (existsSync(sharedDir)) {
for (const entry of readdirSync(sharedDir, { withFileTypes: true })) {
const src = join(sharedDir, entry.name);
const dest = resolve(destDir, entry.name);
if (entry.isFile() || entry.isSymbolicLink()) {
copyFileSync(src, dest);
}
}
}
}
// Installs the core set when missing, globally; an installed skill is never refreshed or removed
// here (that is `hyperframes skills update`). Offline it only checks presence.
async function keepSkillsCurrent(destDir: string): Promise<void> {
const { updateSkills } = await import("./skills.js");
console.log();
console.log(c.bold("Checking AI coding skills against GitHub..."));
// Wrap defensively (non-strict already swallows most failures): a
// skills-install failure can never break `init` itself — it warns and
// proceeds.
try {
const result = await updateSkills({ onlyMissing: true, cwd: destDir });
if (result.presenceOnly) {
// Freshness never got checked (GitHub unreachable) — don't claim
// "up to date"; the engine already reported what it could verify or
// blind-install. Point at the recovery command instead.
console.log(
c.dim(
"Skills freshness unverified (offline?). For the user: `npx hyperframes skills update` refreshes them once online.",
),
);
} else if (result.installed.length === 0) {
console.log(c.success("AI coding skills are already up to date."));
} else {
console.log(
c.dim("Workflow skills not installed here are added on demand, when first used."),
);
}
} catch (err) {
console.log(
c.dim(`AI coding skills install skipped: ${err instanceof Error ? err.message : err}`),
);
}
}
// ---------------------------------------------------------------------------
// Exported command
// ---------------------------------------------------------------------------
export default defineCommand({
meta: {
name: "init",
description: "Scaffold a new composition project",
},
args: {
name: { type: "positional", description: "Project name", required: false },
example: {
type: "string",
description: "Example name (e.g. warm-grain, swiss-grid, blank)",
alias: "e",
},
// Accepted-but-errored so users who still type the old flag get a clear
// message rather than citty silently ignoring it and producing a blank
// project. The actual behavior is gone — this exists purely for the
// diagnostic. `hidden` keeps it out of --help output so new users aren't
// taught about a flag that's already gone.
template: {
type: "string",
description: "[renamed] Use --example instead.",
alias: "t",
hidden: true,
},
video: {
type: "string",
description: "Path to a video file (MP4, WebM, MOV)",
alias: "v",
},
"video-legacy": {
type: "string",
description: "[renamed] Use --video (or -v) instead of -V.",
alias: "V",
hidden: true,
},
audio: {
type: "string",
description: "Path to an audio file (MP3, WAV, M4A)",
alias: "a",
},
"skip-transcribe": {
type: "boolean",
description: "Skip whisper transcription",
},
"keep-original": {
type: "boolean",
description: "Copy the --video file as is, without converting it to H.264 MP4",
},
model: {
type: "string",
description:
"Whisper model for transcription (e.g. tiny.en, base.en, small.en, medium.en, large)",
},
language: {
type: "string",
description:
"Language code for transcription (e.g. en, es, ja). Filters out non-target speech.",
},
"non-interactive": {
type: "boolean",
description: "Disable interactive prompts (for CI/agents)",
},
agent: {
type: "boolean",
hidden: true,
description: "Deprecated alias; default init is the centered blank",
},
"skip-skills": {
type: "boolean",
description: "Skip installing missing core AI skills (also HYPERFRAMES_SKIP_SKILLS=1)",
},
tailwind: {
type: "boolean",
description: "Add Tailwind CSS browser-runtime support",
},
resolution: {
type: "string",
description:
"Canvas resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160), landscape-1440p (2560x1440), portrait-1440p (1440x2560), square-1440p (1440x1440). Aliases: 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square. Default: a --video clip's own shape as it plays, 1080 on the short side (4:3 -> 1440x1080), else the template's dimensions (typically 1920x1080).",
},
skill: {
type: "string",
description:
"Owning authoring skill slug (e.g. hyperframes). Stamped into " +
"hyperframes.json so every render of this project is attributed to it on " +
"usage telemetry, without re-passing --skill on each render. Ignored unless it is a slug.",
},
},
async run({ args }) {
if (args.template !== undefined) {
// Quote the value in case it looks flag-like — keeps the suggested
// command copy-pasteable.
console.error(
c.error(
`The --template flag was renamed to --example. Example:\n npx hyperframes init ${args.name ?? "my-video"} --example "${args.template}"`,
),
);
failUsage();
}
if (args["video-legacy"] !== undefined) {
console.error(
c.error(
`The -V short flag no longer maps to --video. Use --video (or -v). Example:\n npx hyperframes init ${args.name ?? "my-video"} --video "${args["video-legacy"]}"`,
),
);
failUsage();
}
const exampleFlag = args.example;
const videoFlag = args.video;
const audioFlag = args.audio;
const skipTranscribe = args["skip-transcribe"] === true;
const keepOriginal = args["keep-original"] === true;
const skipSkills = args["skip-skills"] === true || process.env.HYPERFRAMES_SKIP_SKILLS === "1";
const tailwind = args.tailwind === true;
const nonInteractive = args["non-interactive"] === true || args.agent === true;
const modelFlag = args.model;
const languageFlag = args.language;
const initialTranscriptionModel = initialModelForLanguage(
modelFlag ?? DEFAULT_MODEL,
languageFlag,
);
const interactive = !nonInteractive && !isUnattended();
let resolutionPreset: CanvasResolution | undefined;
if (args.resolution !== undefined) {
resolutionPreset = normalizeResolutionFlag(args.resolution);
if (!resolutionPreset) {
console.error(
c.error(
`Invalid --resolution: "${args.resolution}". ` +
`Use one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` +
`landscape-1440p, portrait-1440p, square-1440p ` +
`(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`,
),
);
failUsage();
}
}
// -----------------------------------------------------------------------
// Non-interactive mode — all inputs from flags, defaults where missing
// -----------------------------------------------------------------------
if (!interactive) {
const templateId = resolveScaffoldTemplateId(exampleFlag, Boolean(videoFlag || audioFlag));
const name = args.name ?? "my-video";
const destDir = resolve(name);
const tooLong = nameTooLongMessage(destDir);
if (tooLong) {
console.error(c.error(tooLong));
failCommand();
}
if (holdsFilesBesideProjectConfigOrSources(destDir, [videoFlag, audioFlag])) {
console.error(c.error(`Directory already exists and is not empty: ${name}`));
failCommand();
}
if (videoFlag && audioFlag) {
console.error(c.error("Cannot use --video and --audio together"));
failUsage();
}
// Validate source files before creating destDir so a failed run does
// not leave an empty orphan directory behind. The interactive path
// already validates in this order.
const videoPath = videoFlag ? resolve(videoFlag) : undefined;
if (videoPath && !existsSync(videoPath)) {
console.error(c.error(`Video file not found: ${videoFlag}`));
failCommand();
}
const audioPath = audioFlag ? resolve(audioFlag) : undefined;
if (audioPath && !existsSync(audioPath)) {
console.error(c.error(`Audio file not found: ${audioFlag}`));
failCommand();
}
mkdirSync(destDir, { recursive: true });
let localVideoName: string | undefined;
let videoHasAudio = true;
let videoDuration: number | undefined;
let videoSize: VideoMeta | undefined;
let sourceFilePath: string | undefined;
// Handle video
if (videoPath) {
sourceFilePath = videoPath;
const result = await handleVideoFile(videoPath, destDir, false, keepOriginal);
localVideoName = result.localVideoName;
videoHasAudio = result.meta.hasAudio;
videoDuration = result.meta.durationSeconds;
videoSize = result.meta;
console.log(
`Video: ${result.meta.width}x${result.meta.height}, ${result.meta.durationSeconds.toFixed(1)}s`,
);
}
// Handle audio
if (audioPath) {
sourceFilePath = audioPath;
copyIntoProjectUnlessAlreadyThere(audioPath, resolve(destDir, basename(audioPath)));
const { getMediaDurationSeconds } = await import("../whisper/transcribe.js");
videoDuration = getMediaDurationSeconds(audioPath) ?? undefined;
console.log(`Audio: ${basename(audioPath)}`);
}
// Transcribe
if (sourceFilePath && !skipTranscribe) {
try {
const { ensureWhisper, ensureModel } = await import("../whisper/manager.js");
await ensureWhisper();
await ensureModel(initialTranscriptionModel);
console.log("Transcribing...");
const { transcribe: runTranscribe } = await import("../whisper/transcribe.js");
const result = await runTranscribe(sourceFilePath, destDir, {
model: modelFlag,
language: languageFlag,
});
console.log(
`Transcribed: ${result.wordCount} words (${result.durationSeconds.toFixed(1)}s)`,
);
if (!videoDuration) videoDuration = result.durationSeconds;
} catch (err) {
console.log(`Transcription skipped: ${err instanceof Error ? err.message : err}`);
}
}
// Scaffold
try {
const media: InitMediaOptions = {
video: localVideoName ? { filename: localVideoName, hasAudio: videoHasAudio } : undefined,
audio: audioPath ? { filename: basename(audioPath) } : undefined,
durationSeconds: videoDuration,
};
await scaffoldProject(
destDir,
basename(destDir),
templateId,
media,
tailwind,
resolutionPreset ?? clipFrame(templateId, videoSize),
args.skill,
);
} catch (err) {
console.error(
c.error(
`Failed to scaffold example "${templateId}": ${err instanceof Error ? err.message : err}`,
),
);
console.error(c.dim("Use --example blank for offline use."));
failCommand();
}
await finishScaffold(destDir, templateId, tailwind);
console.log(c.success(`Created ${c.accent(name + "/")}`));
for (const f of readdirSync(destDir).filter((f) => !f.startsWith("."))) {
console.log(` ${c.accent(f)}`);
}
if (!skipSkills) {
await keepSkillsCurrent(destDir);
}
console.log();
console.log("Get started:");
console.log();
if (skipSkills) {
console.log(
` ${c.accent("1.")} For the user: use your HyperFrames plugin, or install standalone skills with:`,
);
console.log(` ${c.accent("npx hyperframes skills update")}`);
} else {
console.log(
` ${c.accent("1.")} Restart your AI agent (new session) so it loads the skills.`,
);
}
console.log();
console.log(` ${c.accent("2.")} Open this project with your AI coding agent:`);
console.log(
` ${c.accent(`cd ${shellArg(name)}`)} then start ${c.accent("Claude Code")}, ${c.accent("Cursor")}, or your preferred agent`,
);
console.log();
console.log(` ${c.accent("3.")} Try a starter prompt:`);
console.log(
` ${c.dim('"Using /hyperframes, create a 15-second intro about [your topic]"')}`,
);
console.log(
` ${c.dim(`More patterns: ${cliSourced("https://hyperframes.heygen.com/prompting/overview")}`)}`,
);
console.log();
console.log(` ${c.accent("4.")} Preview in the browser:`);
console.log(` ${c.accent(`cd ${shellArg(name)}`)} && ${c.accent("npm run dev")}`);
console.log();
console.log(` ${c.accent("5.")} Check the composition:`);
console.log(` ${c.accent(`cd ${shellArg(name)}`)} && ${c.accent("npm run check")}`);
console.log();
console.log(` ${c.accent("6.")} Render to MP4 when ready:`);
console.log(` ${c.accent(`cd ${shellArg(name)}`)} && ${c.accent("npm run render")}`);
console.log();
console.log(` ${c.dim(`Full docs: ${cliSourced("https://hyperframes.heygen.com")}`)}`);
return;
}
// -----------------------------------------------------------------------
// Interactive mode
// -----------------------------------------------------------------------
printBanner();
clack.intro("Create a new HyperFrames project");
// 1. Project name
let name: string;
const hasPositionalName = args.name !== undefined && args.name !== "";
if (hasPositionalName) {
name = args.name ?? "my-video";
} else {
const nameResult = await clack.text({
message: "Project name",
placeholder: "my-video",
defaultValue: "my-video",
});
if (clack.isCancel(nameResult)) {
clack.cancel("Setup cancelled.");
finishCommand(0);
}
name = nameResult;
}
const destDir = resolve(name);
const tooLong = nameTooLongMessage(destDir);
if (tooLong) {
clack.log.error(tooLong);
clack.cancel("Setup cancelled.");
failCommand();
}
if (holdsFilesBesideProjectConfigOrSources(destDir, [videoFlag, audioFlag])) {
const overwrite = await clack.confirm({
message: `Directory ${c.accent(name)} already exists and is not empty. Overwrite?`,
initialValue: false,
});
if (clack.isCancel(overwrite) || !overwrite) {
clack.cancel("Setup cancelled.");
finishCommand(0);
}
}
// 2. Video/audio file handling (only via --video/--audio flags, no interactive prompt)
let localVideoName: string | undefined;
let videoHasAudio = true;
let sourceFilePath: string | undefined;
let videoDuration: number | undefined;
let videoSize: VideoMeta | undefined;
if (videoFlag) {
const videoPath = resolve(videoFlag);
if (!existsSync(videoPath)) {
clack.log.error(`File not found: ${videoFlag}`);
clack.cancel("Setup cancelled.");
failCommand();
}
mkdirSync(destDir, { recursive: true });
sourceFilePath = videoPath;
const result = await handleVideoFile(videoPath, destDir, true, keepOriginal);
localVideoName = result.localVideoName;
videoHasAudio = result.meta.hasAudio;
videoDuration = result.meta.durationSeconds;
videoSize = result.meta;
} else if (audioFlag) {
const audioPath = resolve(audioFlag);
if (!existsSync(audioPath)) {
clack.log.error(`File not found: ${audioFlag}`);
clack.cancel("Setup cancelled.");
failCommand();
}
mkdirSync(destDir, { recursive: true });
sourceFilePath = audioPath;
copyIntoProjectUnlessAlreadyThere(audioPath, resolve(destDir, basename(audioPath)));
const { getMediaDurationSeconds } = await import("../whisper/transcribe.js");
videoDuration = getMediaDurationSeconds(audioPath) ?? undefined;
clack.log.info(`Audio copied to ${c.accent(basename(audioPath))}`);
}
// 2b. Transcribe if we have a source file with audio (via flags)
if (sourceFilePath) {
const transcribeChoice = await clack.confirm({
message: "Generate captions from audio?",
initialValue: true,
});
if (!clack.isCancel(transcribeChoice) && transcribeChoice) {
const { findWhisper } = await import("../whisper/manager.js");
const needsInstall = findWhisper() === undefined;
if (needsInstall) {
clack.log.info(c.dim("whisper-cpp not found — installing automatically..."));
}
const spin = clack.spinner();
spin.start(
needsInstall
? "Installing whisper-cpp (this may take a moment)..."
: "Preparing transcription...",
);
try {
const { ensureWhisper, ensureModel } = await import("../whisper/manager.js");
await ensureWhisper({
onProgress: (msg) => spin.message(msg),
});
await ensureModel(initialTranscriptionModel, {
onProgress: (msg) => spin.message(msg),
});
spin.message("Transcribing audio...");
const { transcribe: runTranscribe } = await import("../whisper/transcribe.js");
const transcribeResult = await runTranscribe(sourceFilePath, destDir, {
model: modelFlag,
language: languageFlag,
onProgress: (msg) => spin.message(msg),
});
spin.stop(
c.success(
`Transcribed ${transcribeResult.wordCount} words (${transcribeResult.durationSeconds.toFixed(1)}s)`,
),
);
} catch (err) {
spin.stop(c.dim(`Transcription skipped: ${err instanceof Error ? err.message : err}`));
}
}
}
// 3. Pick example — skip prompt if --example was provided
let templateId: string;
if (exampleFlag || videoFlag || audioFlag) {
templateId = resolveScaffoldTemplateId(exampleFlag, Boolean(videoFlag || audioFlag));
} else {
// Resolve full template list (bundled + remote)
const allTemplates = await resolveTemplateList();
const defaultTemplate = "blank";
const templateResult = await clack.select({
message: "Pick an example",
options: allTemplates.map((t: TemplateOption) => ({
value: t.id,
label: t.label,
hint: t.source === "remote" ? `${t.hint} (download)` : t.hint,
})),
initialValue: defaultTemplate,
});
if (clack.isCancel(templateResult)) {
clack.cancel("Setup cancelled.");
finishCommand(0);
}
templateId = templateResult;
}
// 4. Scaffold project (bundled templates are instant, remote templates download from GitHub)
const spin = clack.spinner();
const isBundled = BUNDLED_TEMPLATES.some((t) => t.id === templateId);
if (!isBundled) {
spin.start(`Downloading example ${c.accent(templateId)}...`);
}
try {
const media: InitMediaOptions = {
video: localVideoName ? { filename: localVideoName, hasAudio: videoHasAudio } : undefined,
audio: audioFlag ? { filename: basename(audioFlag) } : undefined,
durationSeconds: videoDuration,
};
await scaffoldProject(
destDir,
name,
templateId,
media,
tailwind,
resolutionPreset ?? clipFrame(templateId, videoSize),
args.skill,
);
if (!isBundled) {
spin.stop(c.success(`Downloaded ${templateId}`));
}
} catch (err) {
if (!isBundled) {
spin.stop(c.error("Download failed"));
}
clack.log.error(
`${err instanceof Error ? err.message : err}\n${c.dim("Use --example blank for offline use.")}`,
);
failCommand();
}
// 4b. Patch captions with transcript if available
await finishScaffold(destDir, templateId, tailwind);
const files = readdirSync(destDir);
clack.note(files.map((f) => c.accent(f)).join("\n"), c.success(`Created ${name}/`));
// Install the core set if it is missing; installed skills are left alone.
// --skip-skills (or HYPERFRAMES_SKIP_SKILLS=1) leaves skills alone.
if (!skipSkills) {
await keepSkillsCurrent(destDir);
}
// Auto-launch studio preview
clack.log.info("Opening studio preview...");
try {
const previewCmd = await import("./preview.js").then((m) => m.default);
await runCommand(previewCmd, { rawArgs: [destDir] });
} catch {
// Ctrl+C or error — that's fine
}
},
});