// 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"; 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 { 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/ in dev, dist/templates/ when packed). // Dev-mode also checks registry/examples/ 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/ (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 { 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 = [ ``, ``, ].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 { 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 = /]*)>/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, ``); 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 { 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 { 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). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-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 ` + `(or aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-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 ${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 ${name}`)} && ${c.accent("npm run dev")}`); console.log(); console.log(` ${c.accent("5.")} Check the composition:`); console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run check")}`); console.log(); console.log(` ${c.accent("6.")} Render to MP4 when ready:`); console.log(` ${c.accent(`cd ${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 } }, });