hyper-animator-codex 0.4.0 → 0.5.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.5.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 prefer MiniMax generation when configured. 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/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;
+}