hyper-animator-codex 0.4.0 → 0.6.0

package/README.md

@@ -37,6 +37,21 @@ Use a custom Codex skills directory:
 npx hyper-animator-codex install --target /path/to/codex/skills
 ```
 
+## Git Checkpoints
+
+During `/hyper-animator` runs, the installed skill initializes a normal Git repository in a new output directory and creates rollback-friendly stage commits. It does not create branches or worktrees.
+
+The bundled helper can be run from an installed skill directory or repository checkout:
+
+```bash
+node skills/hyper-animator-codex/scripts/git_checkpoint.mjs \
+  --phase init \
+  --message "chore: initialize hyper animator workspace" \
+  --allow-empty
+```
+
+Existing Git repositories with uncommitted changes are protected: the helper stops instead of mixing user edits into automatic commits. Large video and audio files above 10 MB are skipped by default and recorded in a manifest under `hyper-animator-output/git-checkpoints/`.
+
 ## MiniMax Music Configuration
 
 MiniMax is the preferred generated-background-music provider. Configure it during install so the copied Codex skill can generate music without asking for credentials later:
@@ -93,6 +108,7 @@ When rendering video, hide preview controls with any one of:
 
 - `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
 - `skills/hyper-animator-codex/references/`: HyperFrames catalog map, workflow guide, pseudocode, and request examples.
+- `skills/hyper-animator-codex/scripts/git_checkpoint.mjs`: Git initialization and stage-commit helper for `/hyper-animator` runs.
 - `skills/hyper-animator-codex/scripts/validate_hyperframes_html.py`: static pre-render HTML quality gate.
 
 ## Optional Beat Detection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Install the Hyper Animator Codex skill for Codex.",
   "type": "module",
   "bin": {

package/skills/hyper-animator-codex/SKILL.md

@@ -11,22 +11,24 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 
 ## Required Flow
 
-1. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
-2. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
-3. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
-4. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
-5. Decide generation mode:
+1. Read `references/git-checkpoint-workflow.md` and run `scripts/git_checkpoint.mjs --phase init --message "chore: initialize hyper animator workspace" --allow-empty` before requirement capture. If the helper reports an existing dirty repository or linked worktree, stop and ask the user to resolve it.
+2. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
+3. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
+4. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
+5. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
+6. Decide generation mode:
    - `generate_new_hyperframes_html` when the user asks to write HTML, create a new effect, customize style, match a brand, use complex animation, or when component snippets are only paste placeholders.
    - `assemble_existing_catalog_items` only when the user asks to use existing catalog items or quickly compose installed blocks/components.
-6. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
-7. If background music is requested or undecided, read `references/minimax-music-workflow.md` and prefer MiniMax generation when configured. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
-8. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
-9. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
-10. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.
-11. Run pre-render quality gates on the base HTML.
-12. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
-13. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-14. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
+7. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
+8. If background music is requested or undecided, read `references/minimax-music-workflow.md` and use `scripts/generate_minimax_music.mjs` for every MiniMax request. Do not construct MiniMax HTTP calls directly. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
+9. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
+10. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
+11. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.
+12. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
+13. Run pre-render quality gates on the base HTML.
+14. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
+15. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
+16. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
 
 ## Interactive Questions
 
@@ -41,6 +43,7 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 
 ## References
 
+- Read `references/git-checkpoint-workflow.md` before any `/hyper-animator` run writes files or initializes output.
 - Read `references/hyperframes-intent-workflow.md` for the full AskUserQuestion workflow, generation-mode rules, scoring model, and render confirmation requirements.
 - Read `references/hyperframes-catalog-map.json` whenever selecting catalog candidates or determining visual references.
 - Read `references/hyperframes-agent-pseudocode.ts` when implementing the end-to-end loop or when the correct sequence is ambiguous.
@@ -102,5 +105,6 @@ Before rendering, summarize:
 - content assumptions;
 - preview location;
 - validator result.
+- Git checkpoint status, latest commit hash, skipped large media manifest path, and any dirty-worktree caveats;
 
 Ask the user whether to render or revise. If rendering tools or project-specific commands are unavailable, stop at validated HTML and report the exact missing render command or dependency.

package/skills/hyper-animator-codex/references/git-checkpoint-workflow.md

@@ -0,0 +1,87 @@
+# Git Checkpoint Workflow
+
+Use this workflow whenever `/hyper-animator` writes files. The goal is rollback-friendly stage commits without creating branches or worktrees.
+
+## Start Of Run
+
+Run this before requirement capture or file generation:
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase init \
+  --message "chore: initialize hyper animator workspace" \
+  --allow-empty
+```
+
+If the helper reports an existing repository with uncommitted changes, stop and ask the user to resolve those files before continuing.
+
+## Phase Commits
+
+Use explicit allowlists for every checkpoint:
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase brief \
+  --message "feat: capture animation brief" \
+  --allow "hyper-animator-output/brief/**" \
+  --allow "hyper-animator-output/catalog/**"
+```
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase base-html \
+  --message "feat: create base animation html" \
+  --allow "*.html" \
+  --allow "hyper-animator-output/html/**" \
+  --allow "hyper-animator-output/assets/**"
+```
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase audio \
+  --message "feat: add audio assets" \
+  --allow "hyper-animator-output/music/**" \
+  --allow "hyper-animator-output/beat-maps/**"
+```
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase preview \
+  --message "feat: add preview controls" \
+  --allow "*.preview.html" \
+  --allow "hyper-animator-output/preview/**"
+```
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase render \
+  --message "chore: render animation video" \
+  --allow "hyper-animator-output/render/**" \
+  --allow "*.mp4" \
+  --allow "*.webm"
+```
+
+For preview feedback revisions:
+
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase refine \
+  --message "refine: update animation from preview feedback" \
+  --allow "*.html" \
+  --allow "hyper-animator-output/**"
+```
+
+## Media Policy
+
+The default large media threshold is 10 MB. Large audio/video files are skipped unless `--include-large-media` is passed. When a file is skipped, the helper commits a manifest under:
+
+```text
+hyper-animator-output/git-checkpoints/<phase>-skipped-media.json
+```
+
+## Hard Rules
+
+- Do not run `git switch`, `git checkout -b`, `git branch`, or `git worktree add`.
+- Do not create or recommend branches or worktrees for `/hyper-animator` output.
+- Do not commit MiniMax credentials, `.firecrawl/`, `node_modules/`, or render caches.
+- If unrelated dirty files are reported, stop and ask the user before continuing.

package/skills/hyper-animator-codex/references/minimax-music-workflow.md

@@ -2,6 +2,10 @@
 
 Use this when the user wants generated background music or asks whether Hyper Animator Codex can create music for an animation.
 
+## Script-Only Rule
+
+Do not hand-assemble MiniMax HTTP requests in agent reasoning or shell commands. Always call `scripts/generate_minimax_music.mjs`. The script owns request validation, retry policy, error normalization, audio writing, metadata writing, and secret redaction.
+
 ## MiniMax Preference
 
 Prefer MiniMax before other background-music sources when `config/minimax.json` exists in the installed skill or `MINIMAX_API_KEY` and `MINIMAX_GROUP_ID` are present in the environment.
@@ -60,6 +64,13 @@ node scripts/generate_minimax_music.mjs \
 
 Use `--dry-run` before a real call when checking config, request shape, or model choice.
 
+To generate a request JSON file for a scripted call:
+
+```bash
+node scripts/generate_minimax_music.mjs \
+  --request-json hyper-animator-output/music/minimax-request.json
+```
+
 ## Beat Sync
 
 After music generation succeeds, analyze the generated audio:

package/skills/hyper-animator-codex/scripts/generate_minimax_music.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -10,7 +10,7 @@ import {
   validateMinimaxConfig,
 } from "./minimax_runtime_config.mjs";
 
-const ENDPOINT = "https://api.minimaxi.com/v1/music_generation";
+const DEFAULT_ENDPOINT = "https://api.minimaxi.com/v1/music_generation";
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const skillRoot = dirname(scriptDir);
 
@@ -28,15 +28,16 @@ function parseArgs(args) {
   const parsed = {
     prompt: undefined,
     lyrics: undefined,
-    lyrics_optimizer: false,
-    is_instrumental: true,
-    output_dir: join(process.cwd(), "hyper-animator-output", "music"),
-    output_format: "hex",
-    audio_format: "mp3",
-    sample_rate: 44100,
-    bitrate: 256000,
+    lyrics_optimizer: undefined,
+    is_instrumental: undefined,
+    output_dir: undefined,
+    output_format: undefined,
+    audio_format: undefined,
+    sample_rate: undefined,
+    bitrate: undefined,
     model: undefined,
     config_path: undefined,
+    request_json: undefined,
     dry_run: false,
   };
 
@@ -76,6 +77,9 @@ function parseArgs(args) {
     } else if (arg === "--config") {
       parsed.config_path = requireValue(args, index, arg);
       index += 1;
+    } else if (arg === "--request-json") {
+      parsed.request_json = requireValue(args, index, arg);
+      index += 1;
     } else if (arg === "--dry-run") {
       parsed.dry_run = true;
     } else if (arg === "--help" || arg === "-h") {
@@ -105,41 +109,108 @@ Options:
   --bitrate <bits>             32000, 64000, 128000, or 256000; default 256000
   --model <model>              music-2.6 or music-2.6-free
   --config <file>              Explicit MiniMax config JSON
+  --request-json <file>        Read request options from a JSON file
   --dry-run                    Print redacted request without contacting MiniMax
 `);
 }
 
+async function readRequestJson(path) {
+  if (!path) {
+    return {};
+  }
+
+  const parsed = JSON.parse(await readFile(path, "utf8"));
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw Object.assign(new Error(`--request-json must contain a JSON object: ${path}`), {
+      kind: "validation",
+    });
+  }
+
+  return parsed;
+}
+
+function mergeOptions(jsonOptions, cliOptions) {
+  return {
+    ...cliOptions,
+    prompt: cliOptions.prompt ?? jsonOptions.prompt,
+    lyrics: cliOptions.lyrics ?? jsonOptions.lyrics,
+    lyrics_optimizer: cliOptions.lyrics_optimizer ?? Boolean(jsonOptions.lyrics_optimizer),
+    is_instrumental: cliOptions.is_instrumental ?? jsonOptions.is_instrumental ?? true,
+    output_dir: cliOptions.output_dir ?? jsonOptions.output_dir ?? join(process.cwd(), "hyper-animator-output", "music"),
+    output_format: cliOptions.output_format ?? jsonOptions.output_format ?? "hex",
+    audio_format: cliOptions.audio_format ?? jsonOptions.audio_format ?? "mp3",
+    sample_rate: cliOptions.sample_rate ?? jsonOptions.sample_rate ?? 44100,
+    bitrate: cliOptions.bitrate ?? jsonOptions.bitrate ?? 256000,
+    model: cliOptions.model ?? jsonOptions.model,
+  };
+}
+
+function endpointFromEnv(env = process.env) {
+  return env.MINIMAX_MUSIC_ENDPOINT || DEFAULT_ENDPOINT;
+}
+
+function timeoutFromEnv(env = process.env) {
+  const value = Number.parseInt(env.MINIMAX_REQUEST_TIMEOUT_MS || "60000", 10);
+  return Number.isFinite(value) && value > 0 ? value : 60000;
+}
+
+function makeErrorEnvelope(error, attempts = 0) {
+  return {
+    ok: false,
+    provider: "minimax",
+    error: {
+      kind: error.kind || "validation",
+      message: error.message,
+      retryable: Boolean(error.retryable),
+      http_status: error.http_status ?? null,
+      status_code: error.status_code ?? null,
+    },
+    attempts,
+  };
+}
+
+function minimaxError(message, fields = {}) {
+  const error = new Error(message);
+  Object.assign(error, fields);
+  return error;
+}
+
+function printJson(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
 function validateOptions(options) {
   if (!options.prompt || options.prompt.trim().length === 0) {
-    throw new Error("--prompt is required");
+    throw Object.assign(new Error("--prompt is required"), { kind: "validation" });
   }
 
   if (options.prompt.length > 2000) {
-    throw new Error("--prompt must be 2000 characters or fewer");
+    throw Object.assign(new Error("--prompt must be 2000 characters or fewer"), { kind: "validation" });
   }
 
   if (!["hex", "url"].includes(options.output_format)) {
-    throw new Error("--output-format must be hex or url");
+    throw Object.assign(new Error("--output-format must be hex or url"), { kind: "validation" });
   }
 
   if (!["mp3", "wav", "pcm"].includes(options.audio_format)) {
-    throw new Error("--format must be mp3, wav, or pcm");
+    throw Object.assign(new Error("--format must be mp3, wav, or pcm"), { kind: "validation" });
   }
 
   if (![16000, 24000, 32000, 44100].includes(options.sample_rate)) {
-    throw new Error("--sample-rate must be 16000, 24000, 32000, or 44100");
+    throw Object.assign(new Error("--sample-rate must be 16000, 24000, 32000, or 44100"), { kind: "validation" });
   }
 
   if (![32000, 64000, 128000, 256000].includes(options.bitrate)) {
-    throw new Error("--bitrate must be 32000, 64000, 128000, or 256000");
+    throw Object.assign(new Error("--bitrate must be 32000, 64000, 128000, or 256000"), { kind: "validation" });
   }
 
   if (!options.is_instrumental && !options.lyrics && !options.lyrics_optimizer) {
-    throw new Error("Vocal MiniMax generation requires --lyrics or --lyrics-optimizer");
+    throw Object.assign(new Error("Vocal MiniMax generation requires --lyrics or --lyrics-optimizer"), { kind: "validation" });
   }
 
   if (options.lyrics && options.lyrics.length > 3500) {
-    throw new Error("--lyrics must be 3500 characters or fewer");
+    throw Object.assign(new Error("--lyrics must be 3500 characters or fewer"), { kind: "validation" });
   }
 }
 
@@ -202,48 +273,148 @@ function decodeHexAudio(value) {
   return Buffer.from(value, "hex");
 }
 
-async function callMiniMax(config, request) {
-  const response = await fetch(ENDPOINT, {
+function classifyHttpStatus(status) {
+  if (status === 401 || status === 403) {
+    return { kind: "auth", retryable: false };
+  }
+
+  if (status === 429) {
+    return { kind: "rate_limit", retryable: true };
+  }
+
+  if (status >= 500) {
+    return { kind: "server", retryable: true };
+  }
+
+  return { kind: "response", retryable: false };
+}
+
+async function fetchWithTimeout(url, options, timeoutMs) {
+  if (!URL.canParse(url)) {
+    throw minimaxError(`MiniMax endpoint is not a valid URL: ${url}`, {
+      kind: "validation",
+      retryable: false,
+    });
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw minimaxError("MiniMax request timed out", { kind: "timeout", retryable: true });
+    }
+
+    if (typeof error?.cause?.code === "string") {
+      throw minimaxError(`MiniMax network error: ${error.message}`, { kind: "network", retryable: true });
+    }
+
+    throw minimaxError(`MiniMax request setup failed: ${error.message}`, {
+      kind: "response",
+      retryable: false,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function callMiniMax(config, request, { endpoint, timeoutMs }) {
+  const response = await fetchWithTimeout(endpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${config.api_key}`,
     },
     body: JSON.stringify(request),
-  });
+  }, timeoutMs);
 
   const text = await response.text();
-  let json;
+  let json = null;
+
+  if (!response.ok) {
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+
+    const message = json?.base_resp?.status_msg || `HTTP ${response.status}`;
+    throw minimaxError(`MiniMax request failed: ${message}`, {
+      ...classifyHttpStatus(response.status),
+      http_status: response.status,
+      status_code: json?.base_resp?.status_code ?? null,
+    });
+  }
 
   try {
     json = JSON.parse(text);
   } catch (error) {
-    throw new Error(`MiniMax returned non-JSON response with HTTP ${response.status}`);
-  }
-
-  if (!response.ok) {
-    const message = json.base_resp?.status_msg || `HTTP ${response.status}`;
-    throw new Error(`MiniMax request failed: ${message}`);
+    throw minimaxError(`MiniMax returned non-JSON response with HTTP ${response.status}`, {
+      kind: "response",
+      retryable: false,
+      http_status: response.status,
+    });
   }
 
   const statusCode = json.base_resp?.status_code;
   if (statusCode !== 0) {
     const message = json.base_resp?.status_msg || "unknown MiniMax error";
-    throw new Error(`MiniMax request failed with status_code ${statusCode}: ${message}`);
+    throw minimaxError(`MiniMax request failed with status_code ${statusCode}: ${message}`, {
+      kind: "provider",
+      retryable: false,
+      http_status: response.status,
+      status_code: statusCode,
+    });
   }
 
   if (json.data?.status !== 2) {
-    throw new Error(`MiniMax generation is not complete; data.status is ${json.data?.status}`);
+    throw minimaxError(`MiniMax generation is not complete; data.status is ${json.data?.status}`, {
+      kind: "provider",
+      retryable: false,
+      http_status: response.status,
+      status_code: statusCode,
+    });
   }
 
   if (!json.data?.audio) {
-    throw new Error("MiniMax response did not include data.audio");
+    throw minimaxError("MiniMax response did not include data.audio", {
+      kind: "provider",
+      retryable: false,
+      http_status: response.status,
+      status_code: statusCode,
+    });
   }
 
   return json;
 }
 
-async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
+async function callMiniMaxWithRetries(config, request, { endpoint, timeoutMs, maxRetries = 2 }) {
+  let attempts = 0;
+
+  while (attempts <= maxRetries) {
+    attempts += 1;
+
+    try {
+      return {
+        responseJson: await callMiniMax(config, request, { endpoint, timeoutMs }),
+        attempts,
+      };
+    } catch (error) {
+      if (!error.retryable || attempts > maxRetries) {
+        error.attempts = attempts;
+        throw error;
+      }
+    }
+  }
+
+  throw minimaxError("MiniMax request failed", { kind: "network", retryable: true, attempts });
+}
+
+async function writeAudioOutput({ responseJson, request, outputDir, prompt, endpoint }) {
   await mkdir(outputDir, { recursive: true });
 
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -261,7 +432,7 @@ async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
     metadataPath,
     `${JSON.stringify({
       provider: "minimax",
-      endpoint: ENDPOINT,
+      endpoint,
       request,
       response: {
         base_resp: responseJson.base_resp,
@@ -283,64 +454,90 @@ async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2));
+  try {
+    const cliOptions = parseArgs(process.argv.slice(2));
+    const endpoint = endpointFromEnv();
+    const timeoutMs = timeoutFromEnv();
 
-  if (options.help) {
-    printHelp();
-    return;
-  }
+    if (cliOptions.help) {
+      printHelp();
+      return;
+    }
 
-  validateOptions(options);
+    const requestJson = await readRequestJson(cliOptions.request_json);
+    const options = mergeOptions(requestJson, cliOptions);
 
-  const runtime = await readMinimaxRuntimeConfig({
-    skillRoot,
-    env: process.env,
-    configPath: options.config_path,
-  });
+    validateOptions(options);
 
-  if (!runtime) {
-    throw new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key and --minimax-group-id, or set MINIMAX_API_KEY and MINIMAX_GROUP_ID.");
-  }
+    let runtime;
+    try {
+      runtime = await readMinimaxRuntimeConfig({
+        skillRoot,
+        env: process.env,
+        configPath: options.config_path,
+      });
+    } catch (error) {
+      throw Object.assign(error, { kind: "config", retryable: false });
+    }
+
+    if (!runtime) {
+      throw Object.assign(new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key and --minimax-group-id, or set MINIMAX_API_KEY and MINIMAX_GROUP_ID."), {
+        kind: "config",
+        retryable: false,
+      });
+    }
+
+    let request;
+    try {
+      request = buildRequest(options, runtime.config);
+    } catch (error) {
+      throw Object.assign(error, { kind: "config", retryable: false });
+    }
+    const redactedConfig = redactMinimaxConfig(runtime.config);
+
+    if (options.dry_run) {
+      printJson({
+        ok: true,
+        dry_run: true,
+        provider: "minimax",
+        endpoint,
+        config: {
+          source: runtime.source,
+          path: runtime.configPath,
+          redacted: redactedConfig,
+        },
+        request_path: cliOptions.request_json,
+        request,
+        output_dir: options.output_dir,
+      });
+      return;
+    }
 
-  const request = buildRequest(options, runtime.config);
-  const redactedConfig = redactMinimaxConfig(runtime.config);
+    const { responseJson, attempts } = await callMiniMaxWithRetries(runtime.config, request, {
+      endpoint,
+      timeoutMs,
+    });
+    const output = await writeAudioOutput({
+      responseJson,
+      request,
+      outputDir: options.output_dir,
+      prompt: options.prompt,
+      endpoint,
+    });
 
-  if (options.dry_run) {
-    console.log(JSON.stringify({
+    printJson({
       ok: true,
-      dry_run: true,
       provider: "minimax",
-      endpoint: ENDPOINT,
-      config: {
-        source: runtime.source,
-        path: runtime.configPath,
-        redacted: redactedConfig,
-      },
-      request,
-      output_dir: options.output_dir,
-    }, null, 2));
-    return;
+      model: request.model,
+      attempts,
+      output_path: output.audioPath,
+      metadata_path: output.metadataPath,
+      beat_analysis_command: `python3 scripts/analyze_music_beats.py ${output.audioPath} -o ${join(options.output_dir, "beat-map.json")} --fps 60 --pretty`,
+    });
+  } catch (error) {
+    printJson(makeErrorEnvelope(error, error.attempts ?? 0));
+    process.exitCode = 1;
   }
-
-  const responseJson = await callMiniMax(runtime.config, request);
-  const output = await writeAudioOutput({
-    responseJson,
-    request,
-    outputDir: options.output_dir,
-    prompt: options.prompt,
-  });
-
-  console.log(JSON.stringify({
-    ok: true,
-    provider: "minimax",
-    model: request.model,
-    output_path: output.audioPath,
-    metadata_path: output.metadataPath,
-    beat_analysis_command: `python3 scripts/analyze_music_beats.py ${output.audioPath} -o ${join(options.output_dir, "beat-map.json")} --fps 60 --pretty`,
-  }, null, 2));
 }
 
-main().catch((error) => {
-  console.error(`Error: ${error.message}`);
-  process.exitCode = 1;
-});
+main();

package/skills/hyper-animator-codex/scripts/git_checkpoint.mjs

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+const FALLBACK_USER_NAME = "Hyper Animator Codex";
+const FALLBACK_USER_EMAIL = "hyper-animator-codex@local";
+const DEFAULT_MAX_BINARY_MB = 10;
+const SKIPPED_MANIFEST_DIR = join("hyper-animator-output", "git-checkpoints");
+const MEDIA_EXTENSIONS = new Set([
+  ".mp4",
+  ".mov",
+  ".webm",
+  ".mkv",
+  ".avi",
+  ".m4v",
+  ".mp3",
+  ".wav",
+  ".m4a",
+  ".aac",
+  ".flac",
+  ".ogg",
+  ".wma",
+]);
+const DEFAULT_EXCLUDES = [
+  ".firecrawl/",
+  ".gitconfig-global",
+  ".git/",
+  "node_modules/",
+  "config/minimax.json",
+  "skills/hyper-animator-codex/config/minimax.json",
+  "tmp/",
+  ".tmp/",
+];
+
+let repositoryRootCache = null;
+let gitPrefixCache = null;
+
+function requireValue(argv, index, flag) {
+  const value = argv[index + 1];
+
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+
+  return value;
+}
+
+function parseArgs(argv) {
+  const options = {
+    phase: "",
+    message: "",
+    allow: [],
+    exclude: [],
+    maxBinaryMb: DEFAULT_MAX_BINARY_MB,
+    includeLargeMedia: false,
+    allowEmpty: false,
+    dryRun: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--phase") {
+      options.phase = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg === "--message") {
+      options.message = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg === "--allow") {
+      options.allow.push(requireValue(argv, index, arg));
+      index += 1;
+    } else if (arg === "--exclude") {
+      options.exclude.push(requireValue(argv, index, arg));
+      index += 1;
+    } else if (arg === "--max-binary-mb") {
+      options.maxBinaryMb = Number(requireValue(argv, index, arg));
+      index += 1;
+    } else if (arg === "--include-large-media") {
+      options.includeLargeMedia = true;
+    } else if (arg === "--allow-empty") {
+      options.allowEmpty = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  if (!options.phase) {
+    throw new Error("--phase is required");
+  }
+
+  if (!options.message) {
+    throw new Error("--message is required");
+  }
+
+  if (!Number.isFinite(options.maxBinaryMb) || options.maxBinaryMb < 0) {
+    throw new Error("--max-binary-mb must be a non-negative number");
+  }
+
+  return options;
+}
+
+function git(args, { check = true } = {}) {
+  const result = spawnSync("git", args, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+  });
+
+  if (check && result.status !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `git ${args.join(" ")}`;
+    throw new Error(detail);
+  }
+
+  return result;
+}
+
+function normalizeGitPath(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function repositoryRoot() {
+  if (repositoryRootCache !== null) {
+    return repositoryRootCache;
+  }
+
+  const result = git(["rev-parse", "--show-toplevel"], { check: false });
+  repositoryRootCache = result.status === 0 && result.stdout.trim() ? result.stdout.trim() : process.cwd();
+
+  return repositoryRootCache;
+}
+
+function gitPrefix() {
+  if (gitPrefixCache !== null) {
+    return gitPrefixCache;
+  }
+
+  const result = git(["rev-parse", "--show-prefix"], { check: false });
+  gitPrefixCache = result.status === 0 ? normalizeGitPath(result.stdout) : "";
+
+  return gitPrefixCache;
+}
+
+function cwdRelativeToGitPath(path) {
+  const prefix = gitPrefix();
+
+  return normalizeGitPath(prefix ? join(prefix, path) : path);
+}
+
+function resolveGitDirPath(value) {
+  const trimmed = value.trim();
+  const absolute = isAbsolute(trimmed) ? trimmed : resolve(process.cwd(), trimmed);
+
+  try {
+    return normalizeGitPath(realpathSync(absolute));
+  } catch {
+    return normalizeGitPath(absolute);
+  }
+}
+
+function isDefaultExcluded(path) {
+  const normalized = normalizeGitPath(path);
+
+  return DEFAULT_EXCLUDES.some((entry) => {
+    const cleaned = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    return normalized === cleaned || normalized.startsWith(`${cleaned}/`);
+  });
+}
+
+function isInsideGitRepo() {
+  const result = git(["rev-parse", "--is-inside-work-tree"], { check: false });
+
+  return result.status === 0 && result.stdout.trim() === "true";
+}
+
+function isLinkedWorktree() {
+  const gitDir = resolveGitDirPath(git(["rev-parse", "--git-dir"]).stdout);
+  const commonDir = resolveGitDirPath(git(["rev-parse", "--git-common-dir"]).stdout);
+
+  return gitDir !== commonDir;
+}
+
+function hasAnyCommit() {
+  return git(["rev-parse", "--verify", "HEAD"], { check: false }).status === 0;
+}
+
+function parsePorcelainLine(line) {
+  const path = line.slice(3).replace(/^"|"$/g, "");
+  const target = path.includes(" -> ") ? path.split(" -> ").pop() : path;
+
+  return normalizeGitPath(target);
+}
+
+function porcelainLines(pathspecs = []) {
+  const args = ["status", "--porcelain=v1", "--untracked-files=all"];
+
+  if (pathspecs.length > 0) {
+    args.push("--", ...pathspecs);
+  }
+
+  return git(args, { check: true }).stdout
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+}
+
+function dirtyLines() {
+  return porcelainLines().filter((line) => !isDefaultExcluded(parsePorcelainLine(line)));
+}
+
+function allDirtyFiles(pathspecs = []) {
+  const seen = new Set();
+
+  return porcelainLines(pathspecs)
+    .map(parsePorcelainLine)
+    .filter((path) => !isDefaultExcluded(path))
+    .filter((path) => {
+      if (seen.has(path)) {
+        return false;
+      }
+
+      seen.add(path);
+      return true;
+    });
+}
+
+function trackedOrUntrackedMatching(pathspecs) {
+  return allDirtyFiles(pathspecs);
+}
+
+function stagedFiles() {
+  return git(["diff", "--cached", "--name-only", "--diff-filter=ACDMR"], { check: true }).stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map(normalizeGitPath);
+}
+
+function patternToRegExp(pattern) {
+  let escaped = "";
+
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        escaped += ".*";
+        index += 1;
+      } else {
+        escaped += "[^/]*";
+      }
+    } else if (/[.+^${}()|[\]\\]/.test(char)) {
+      escaped += `\\${char}`;
+    } else {
+      escaped += char;
+    }
+  }
+
+  return new RegExp(`^${escaped}$`);
+}
+
+function isExplicitlyExcluded(path, patterns) {
+  return patterns.some((pattern) => {
+    const normalized = normalizeGitPath(pattern);
+
+    if (normalized.endsWith("/")) {
+      return path.startsWith(normalized);
+    }
+
+    if (normalized.includes("*")) {
+      return patternToRegExp(normalized).test(path);
+    }
+
+    return path === normalized;
+  });
+}
+
+function ensureIdentity() {
+  const name = git(["config", "--get", "user.name"], { check: false }).stdout.trim();
+  const email = git(["config", "--get", "user.email"], { check: false }).stdout.trim();
+
+  if (!name) {
+    git(["config", "--local", "user.name", FALLBACK_USER_NAME]);
+  }
+
+  if (!email) {
+    git(["config", "--local", "user.email", FALLBACK_USER_EMAIL]);
+  }
+}
+
+function extensionOf(path) {
+  const index = path.lastIndexOf(".");
+
+  return index === -1 ? "" : path.slice(index).toLowerCase();
+}
+
+function fileSizeBytes(path) {
+  const fsPath = isAbsolute(path) ? path : join(repositoryRoot(), path);
+
+  try {
+    return statSync(fsPath).size;
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return 0;
+    }
+
+    throw error;
+  }
+}
+
+function isLargeMedia(path, maxBinaryMb) {
+  return MEDIA_EXTENSIONS.has(extensionOf(path)) && fileSizeBytes(path) > maxBinaryMb * 1024 * 1024;
+}
+
+function writeSkippedMediaManifest(phase, skipped) {
+  if (skipped.length === 0) {
+    return null;
+  }
+
+  mkdirSync(SKIPPED_MANIFEST_DIR, { recursive: true });
+  const manifestPath = join(SKIPPED_MANIFEST_DIR, `${phase}-skipped-media.json`);
+  const manifest = {
+    phase,
+    skipped: skipped.map((path) => ({
+      path,
+      size_bytes: fileSizeBytes(path),
+      reason: "larger than max-binary-mb",
+    })),
+  };
+
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return cwdRelativeToGitPath(manifestPath);
+}
+
+function readKnownSkippedMedia() {
+  const known = new Set();
+
+  if (!existsSync(SKIPPED_MANIFEST_DIR)) {
+    return known;
+  }
+
+  for (const entry of readdirSync(SKIPPED_MANIFEST_DIR, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith("-skipped-media.json")) {
+      continue;
+    }
+
+    const manifestPath = join(SKIPPED_MANIFEST_DIR, entry.name);
+    let manifest;
+
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    } catch {
+      continue;
+    }
+
+    if (!Array.isArray(manifest?.skipped)) {
+      continue;
+    }
+
+    for (const item of manifest.skipped) {
+      const path = typeof item === "string" ? item : item?.path;
+
+      if (typeof path === "string" && path.trim()) {
+        known.add(normalizeGitPath(path));
+      }
+    }
+  }
+
+  return known;
+}
+
+function stageFiles(paths) {
+  if (paths.length > 0) {
+    git(["add", "--", ...paths.map((path) => `:(top)${normalizeGitPath(path)}`)]);
+  }
+}
+
+function planStageFiles(options) {
+  const dirty = allDirtyFiles();
+  const selected = trackedOrUntrackedMatching(options.allow);
+  const selectedSet = new Set(selected);
+  const knownSkippedMedia = readKnownSkippedMedia();
+  const explicitExcluded = new Set();
+  const stageable = [];
+  const skippedMedia = [];
+
+  for (const path of dirty) {
+    if (isExplicitlyExcluded(path, options.exclude)) {
+      explicitExcluded.add(path);
+    }
+  }
+
+  for (const path of selected) {
+    if (isDefaultExcluded(path) || isExplicitlyExcluded(path, options.exclude)) {
+      continue;
+    }
+
+    if (!options.includeLargeMedia && isLargeMedia(path, options.maxBinaryMb)) {
+      skippedMedia.push(path);
+      continue;
+    }
+
+    stageable.push(path);
+  }
+
+  const skippedSet = new Set(skippedMedia);
+  const unrelated = dirty.filter((path) => {
+    if (selectedSet.has(path) || explicitExcluded.has(path) || skippedSet.has(path)) {
+      return false;
+    }
+
+    return options.includeLargeMedia || !knownSkippedMedia.has(path) || !isLargeMedia(path, options.maxBinaryMb);
+  });
+
+  return { stageable, skippedMedia, unrelated };
+}
+
+function ensureOnlyPlannedFilesStaged(expectedPaths) {
+  const expected = new Set(expectedPaths.map(normalizeGitPath));
+  const unexpected = stagedFiles().filter((path) => !expected.has(path));
+
+  if (unexpected.length > 0) {
+    throw new Error(`Existing repository has staged files outside the planned set:\n${unexpected.join("\n")}`);
+  }
+}
+
+function createCommit(message, allowEmpty) {
+  const args = ["commit"];
+
+  if (allowEmpty) {
+    args.push("--allow-empty");
+  }
+
+  args.push("-m", message);
+
+  const result = git(args, { check: false });
+  const output = `${result.stdout}\n${result.stderr}`;
+
+  if (result.status !== 0 && /nothing to commit|no changes added/i.test(output)) {
+    return false;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(output.trim() || `git ${args.join(" ")}`);
+  }
+
+  return true;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+
+  if (options.phase !== "init" && options.allow.length === 0) {
+    throw new Error("--allow is required for non-init phases");
+  }
+
+  if (options.dryRun) {
+    console.log(`dry run: phase=${options.phase} message=${options.message}`);
+    console.log(isInsideGitRepo() ? "dry run: existing Git repository detected" : "dry run: would initialize Git repository");
+    return;
+  }
+
+  const startedInsideRepo = isInsideGitRepo();
+
+  if (startedInsideRepo && isLinkedWorktree()) {
+    throw new Error("Refusing to run in a linked worktree. Use a normal repository directory for /hyper-animator.");
+  }
+
+  if (startedInsideRepo) {
+    if (options.phase === "init" && hasAnyCommit()) {
+      const dirty = dirtyLines();
+
+      if (dirty.length > 0) {
+        throw new Error(`Existing repository has uncommitted changes:\n${dirty.join("\n")}`);
+      }
+
+      ensureIdentity();
+      console.log(`checkpoint ${options.phase}: ${git(["rev-parse", "--short", "HEAD"]).stdout.trim()}`);
+      return;
+    }
+  } else {
+    git(["init"]);
+  }
+
+  ensureIdentity();
+
+  if (!hasAnyCommit()) {
+    const plan = planStageFiles({ ...options, allow: [] });
+    ensureOnlyPlannedFilesStaged(plan.stageable);
+    const manifestPath = writeSkippedMediaManifest(options.phase, plan.skippedMedia);
+    const stageable = manifestPath ? [...plan.stageable, manifestPath] : plan.stageable;
+    stageFiles(stageable);
+    ensureOnlyPlannedFilesStaged(stageable);
+    if (!createCommit(options.message, options.allowEmpty)) {
+      throw new Error("nothing to commit");
+    }
+  } else {
+    const plan = planStageFiles(options);
+
+    if (plan.unrelated.length > 0) {
+      throw new Error(`Existing repository has unrelated dirty files outside allowlist:\n${plan.unrelated.join("\n")}`);
+    }
+
+    ensureOnlyPlannedFilesStaged(plan.stageable);
+    const manifestPath = writeSkippedMediaManifest(options.phase, plan.skippedMedia);
+    const stageable = manifestPath ? [...plan.stageable, manifestPath] : plan.stageable;
+    stageFiles(stageable);
+    ensureOnlyPlannedFilesStaged(stageable);
+
+    if (!createCommit(options.message, options.allowEmpty)) {
+      throw new Error("nothing to commit");
+    }
+  }
+
+  console.log(`checkpoint ${options.phase}: ${git(["rev-parse", "--short", "HEAD"]).stdout.trim()}`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}