// fallow-ignore-file code-duplication
import { failCommand } from "../utils/commandResult.js";
/**
 * `hyperframes cloudrun` — deploy + drive distributed renders on Google
 * Cloud Run + Cloud Workflows.
 *
 * The GCP counterpart to `hyperframes lambda`. Thin glue: argument parsing
 * + help here; the work lives in `@hyperframes/gcp-cloud-run/sdk`
 * (`deploySite` / `renderToCloudRun` / `getRenderProgress`) plus `terraform`
 * and `gcloud` for provisioning + the image build.
 *
 * Stack coordinates (bucket / service URL / workflow id) are captured by
 * `deploy` into a small state file under `~/.hyperframes/` so `render` and
 * `progress` don't need them re-passed every call.
 */

import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve } from "node:path";
import { defineCommand } from "citty";
import { type CanvasResolution } from "@hyperframes/core";
import { parseOutputResolutionFlag } from "../utils/parseOutputResolution.js";
import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
import {
  reportVariableIssues,
  resolveVariablesArg,
  validateVariablesAgainstProject,
} from "../utils/variables.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { readAllowedCompositionFpsFromDir } from "../utils/compositionFps.js";

export const examples: Example[] = [
  ["Deploy the Cloud Run render stack", "hyperframes cloudrun deploy --project my-gcp-project"],
  [
    "Render a composition on the deployed stack",
    "hyperframes cloudrun render ./my-project --width 1920 --height 1080 --wait",
  ],
  [
    "Render a personalised template with variables",
    'hyperframes cloudrun render ./my-template --width 1920 --height 1080 --variables \'{"title":"Hello Alice"}\'',
  ],
  [
    "Supersample a 1080p composition to 4K",
    "hyperframes cloudrun render ./my-project --width 1920 --height 1080 --output-resolution 4k --wait",
  ],
  [
    "Batch-render N personalised videos from a JSONL file",
    "hyperframes cloudrun render-batch ./my-template --batch ./users.jsonl --width 1920 --height 1080 --max-concurrent 10",
  ],
  ["Check progress for a started render", "hyperframes cloudrun progress <executionName>"],
  [
    "Pre-upload a project so renders share the upload",
    "hyperframes cloudrun sites create ./my-project",
  ],
  ["Tear the stack down", "hyperframes cloudrun destroy --project my-gcp-project"],
];

const HELP = `
${c.bold("hyperframes cloudrun")} ${c.dim("<subcommand> [args]")}

Deploy + drive distributed video renders on Google Cloud Run + Workflows.

${c.bold("SUBCOMMANDS:")}
  ${c.accent("deploy")}        ${c.dim("Build the image + apply the Terraform module (Cloud Run + Workflows + GCS)")}
  ${c.accent("sites create")}  ${c.dim("Tar + upload a project to GCS (reusable across renders)")}
  ${c.accent("render")}        ${c.dim("Start a distributed render (returns an execution name)")}
  ${c.accent("render-batch")}  ${c.dim("Fan out N personalised renders from a JSONL batch file")}
  ${c.accent("progress")}      ${c.dim("Print progress + cost for an in-flight or finished render")}
  ${c.accent("destroy")}       ${c.dim("Tear the stack down")}

${c.bold("FIRST RUN:")}
  ${c.accent("hyperframes cloudrun deploy --project my-gcp-project")}
  ${c.accent("hyperframes cloudrun render ./my-project --width 1920 --height 1080 --wait")}

${c.bold("REQUIREMENTS:")}
  • gcloud authenticated; the target project must have billing enabled
  • terraform (>= 1.5) and docker / Cloud Build access on PATH
`;

interface StackState {
  projectId: string;
  region: string;
  bucketName: string;
  serviceUrl: string;
  workflowId: string;
}

type CloudRunAdapter = typeof import("@hyperframes/gcp-cloud-run/sdk") &
  typeof import("@hyperframes/gcp-cloud-run/terraform");
let cloudRunAdapterPromise: Promise<CloudRunAdapter> | undefined;

function loadCloudRunAdapter(): Promise<CloudRunAdapter> {
  cloudRunAdapterPromise ??= Promise.all([
    import("@hyperframes/gcp-cloud-run/sdk"),
    import("@hyperframes/gcp-cloud-run/terraform"),
  ]).then(([sdk, terraform]) => ({ ...sdk, ...terraform }));
  return cloudRunAdapterPromise;
}

export function isMissingCloudRunAdapterError(error: unknown): boolean {
  return (
    (error as NodeJS.ErrnoException)?.code === "ERR_MODULE_NOT_FOUND" &&
    normalizeErrorMessage(error).includes("@hyperframes/gcp-cloud-run")
  );
}

export function missingCloudRunAdapterMessage(subcommand: string): string {
  return (
    `${c.error("@hyperframes/gcp-cloud-run is not installed.")} The ${c.accent(`hyperframes cloudrun ${subcommand}`)} command needs it at runtime.\n` +
    `Install it alongside the CLI:\n` +
    `  ${c.accent("npm install -g @hyperframes/gcp-cloud-run")}\n` +
    `Or, for an opt-in project setup:\n` +
    `  ${c.accent("npm install @hyperframes/gcp-cloud-run")}`
  );
}

export default defineCommand({
  meta: { name: "cloudrun", description: "Deploy and drive renders on Google Cloud Run" },
  args: {
    subcommand: {
      type: "positional",
      required: false,
      description: "deploy | sites | render | render-batch | progress | destroy",
    },
    target: {
      type: "positional",
      required: false,
      description: "Subcommand positional (project dir, execution name, sites verb)",
    },
    extra: {
      type: "positional",
      required: false,
      description: "Extra positional (e.g. `sites create <projectDir>`)",
    },

    // Stack identity
    project: {
      type: "string",
      description: "GCP project id (required for deploy/destroy; cached after deploy)",
    },
    region: { type: "string", description: "GCP region (default: us-central1)" },
    image: {
      type: "string",
      description:
        "Container image for the render service (deploy). If unset, deploy builds it via Cloud Build.",
    },
    repo: {
      type: "string",
      description: "Artifact Registry repo for the built image (default: hyperframes)",
    },
    // Machine sizing / scaling (deploy). Omitted flags keep the Terraform
    // module defaults (4 vCPU / 16Gi / 100 instances / 3600s).
    cpu: { type: "string", description: "vCPU per Cloud Run instance: 1 | 2 | 4 | 8 (deploy)" },
    memory: { type: "string", description: "Memory per instance, e.g. 16Gi | 32Gi (deploy)" },
    "max-instances": {
      type: "string",
      description: "Max Cloud Run instances = render fan-out ceiling (deploy)",
    },
    timeout: {
      type: "string",
      description: "Per-request timeout in seconds, max 3600 (deploy)",
    },

    // sites / render
    "site-id": { type: "string", description: "Explicit site id (overrides content hash)" },
    width: { type: "string", description: "Render width in pixels" },
    height: { type: "string", description: "Render height in pixels" },
    fps: { type: "string", description: "Render fps (24 | 30 | 60)" },
    format: { type: "string", description: "mp4 | mov | png-sequence | webm (default: mp4)" },
    codec: { type: "string", description: "h264 | h265 (mp4 only)" },
    quality: { type: "string", description: "draft | standard | high" },
    "chunk-size": { type: "string", description: "Frames per chunk" },
    "max-parallel-chunks": { type: "string", description: "Max concurrent chunks" },
    "target-chunk-frames": {
      type: "string",
      description:
        "Cap per-chunk frames; auto-adds chunks (up to --max-parallel-chunks) to keep each under this. Ignored if --chunk-size is set.",
    },
    "output-resolution": {
      type: "string",
      description:
        "Output resolution preset that engages Chrome deviceScaleFactor supersampling (e.g. 4k, 1080p, landscape-4k). The composition's authored data-width/data-height is supersampled to the target without changing layout.",
    },
    variables: {
      type: "string",
      description:
        'JSON object of composition variable values, e.g. --variables \'{"title":"Hi"}\'',
    },
    "variables-file": { type: "string", description: "Path to a JSON file of variable values" },
    "strict-variables": {
      type: "boolean",
      description:
        "Fail the render if any --variables key is undeclared or mistyped vs the composition's data-composition-variables. Without it, mismatches are warnings.",
      default: false,
    },
    batch: {
      type: "string",
      description:
        'Path to a JSONL batch file for `render-batch`. Each line: {"outputKey":"...","variables":{...}}',
    },
    "max-concurrent": {
      type: "string",
      description: "Max in-flight executions for `render-batch` (default: 50).",
    },
    "dry-run": {
      type: "boolean",
      description:
        "For `render-batch`: parse the batch file and print the manifest without starting any execution.",
      default: false,
    },
    "render-id": {
      type: "string",
      description: "Client render id / GCS prefix (default: hf-render-<uuid>)",
    },
    "output-key": {
      type: "string",
      description: "Final output GCS key (default: renders/<renderId>/output.<ext>)",
    },
    wait: { type: "boolean", description: "Block until the render finishes" },
    "wait-interval-ms": {
      type: "string",
      description: "Poll cadence in ms when --wait is set (default: 5000)",
    },
    json: { type: "boolean", description: "Emit machine-readable JSON" },
  },
  // fallow-ignore-next-line complexity
  async run({ args }) {
    const subcommand = args.subcommand as string | undefined;
    if (!subcommand) {
      console.log(HELP);
      return;
    }
    const verbsNeedingAdapter = new Set([
      "deploy",
      "sites",
      "render",
      "render-batch",
      "progress",
      "destroy",
    ]);
    if (verbsNeedingAdapter.has(subcommand)) {
      try {
        await loadCloudRunAdapter();
      } catch (error) {
        if (isMissingCloudRunAdapterError(error)) {
          console.error(missingCloudRunAdapterMessage(subcommand));
          failCommand();
        }
        throw error;
      }
    }
    switch (subcommand) {
      case "deploy":
        return runDeploy(args);
      case "sites":
        return runSites(args);
      case "render":
        return runRender(args);
      case "render-batch":
        return runRenderBatch(args);
      case "progress":
        return runProgress(args);
      case "destroy":
        return runDestroy(args);
      default:
        console.error(`${c.error("Unknown subcommand:")} ${subcommand}\n${HELP}`);
        failCommand();
    }
  },
});

// ── State helpers ─────────────────────────────────────────────────────────

function stateDir(): string {
  return join(homedir(), ".hyperframes");
}
function statePath(): string {
  return join(stateDir(), "cloudrun-state.json");
}
function writeState(state: StackState): void {
  mkdirSync(stateDir(), { recursive: true });
  writeFileSync(statePath(), JSON.stringify(state, null, 2));
}
function readState(args: Record<string, unknown>): StackState {
  const overrides = {
    projectId: args.project as string | undefined,
    region: args.region as string | undefined,
  };
  let base: Partial<StackState> = {};
  if (existsSync(statePath())) {
    try {
      base = JSON.parse(readFileSync(statePath(), "utf8")) as StackState;
    } catch {
      // ignore a corrupt state file; flags must supply the values.
    }
  }
  const merged: Partial<StackState> = { ...base, ...stripUndefined(overrides) };
  const missing = (
    ["projectId", "region", "bucketName", "serviceUrl", "workflowId"] as const
  ).filter((k) => !merged[k]);
  if (missing.length > 0) {
    console.error(
      `[cloudrun] missing stack coordinates: ${missing.join(", ")}. ` +
        `Run \`hyperframes cloudrun deploy --project <id>\` first, or pass them as flags.`,
    );
    failCommand();
  }
  return merged as StackState;
}
function stripUndefined<T extends Record<string, unknown>>(o: T): Partial<T> {
  return Object.fromEntries(Object.entries(o).filter(([, v]) => v != null)) as Partial<T>;
}

function run(cmd: string, cmdArgs: string[], opts: { cwd?: string } = {}): void {
  const res = spawnSync(cmd, cmdArgs, { stdio: "inherit", cwd: opts.cwd });
  if (res.status !== 0) {
    throw new Error(`[cloudrun] \`${cmd} ${cmdArgs.join(" ")}\` exited with ${res.status}`);
  }
}
function capture(cmd: string, cmdArgs: string[], opts: { cwd?: string } = {}): string {
  const res = spawnSync(cmd, cmdArgs, { encoding: "utf8", cwd: opts.cwd });
  if (res.status !== 0) {
    throw new Error(`[cloudrun] \`${cmd} ${cmdArgs.join(" ")}\` failed: ${res.stderr}`);
  }
  return res.stdout.trim();
}

// ── deploy ──────────────────────────────────────────────────────────────────

// fallow-ignore-next-line complexity
async function runDeploy(args: Record<string, unknown>): Promise<void> {
  const project = args.project as string | undefined;
  if (!project) {
    console.error("[cloudrun deploy] --project <gcp-project-id> is required.");
    failCommand();
  }
  const region = (args.region as string | undefined) ?? "us-central1";
  const repo = (args.repo as string | undefined) ?? "hyperframes";
  const { getTerraformModuleDir } = await loadCloudRunAdapter();
  const tfDir = getTerraformModuleDir();
  const repoRoot = findRepoRoot(tfDir);

  console.log(`→ Enabling required APIs on ${project}`);
  run("gcloud", [
    "services",
    "enable",
    "run.googleapis.com",
    "workflows.googleapis.com",
    "workflowexecutions.googleapis.com",
    "artifactregistry.googleapis.com",
    "cloudbuild.googleapis.com",
    "monitoring.googleapis.com",
    "--project",
    project,
  ]);

  let image = args.image as string | undefined;
  if (!image) {
    if (!repoRoot) {
      console.error(
        "[cloudrun deploy] --image is required when not running from a hyperframes checkout (no Dockerfile context found).",
      );
      failCommand();
    }
    // Ensure the Artifact Registry repo exists.
    const exists =
      spawnSync("gcloud", [
        "artifacts",
        "repositories",
        "describe",
        repo,
        "--location",
        region,
        "--project",
        project,
      ]).status === 0;
    if (!exists) {
      run("gcloud", [
        "artifacts",
        "repositories",
        "create",
        repo,
        "--repository-format",
        "docker",
        "--location",
        region,
        "--project",
        project,
      ]);
    }
    const tag = new Date()
      .toISOString()
      .replace(/[^0-9]/g, "")
      .slice(0, 14);
    image = `${region}-docker.pkg.dev/${project}/${repo}/hyperframes-render:${tag}`;
    console.log(`→ Building + pushing ${image} via Cloud Build`);
    run("gcloud", [
      "builds",
      "submit",
      repoRoot,
      "--project",
      project,
      "--timeout",
      "3600s",
      "--config",
      writeCloudBuildConfig(image),
    ]);
  }

  console.log("→ terraform apply");
  run("terraform", ["init", "-input=false"], { cwd: tfDir });
  run(
    "terraform",
    ["apply", "-input=false", "-auto-approve", ...machineVars(args, project, region, image)],
    { cwd: tfDir },
  );

  const state: StackState = {
    projectId: project,
    region,
    bucketName: capture("terraform", ["output", "-raw", "render_bucket_name"], { cwd: tfDir }),
    serviceUrl: capture("terraform", ["output", "-raw", "service_url"], { cwd: tfDir }),
    workflowId: capture("terraform", ["output", "-raw", "workflow_name"], { cwd: tfDir }),
  };
  writeState(state);
  console.log(`${c.accent("✓ deployed.")} bucket=${state.bucketName} workflow=${state.workflowId}`);
  console.log(`  service=${state.serviceUrl}`);
  console.log(
    `  Next: ${c.accent("hyperframes cloudrun render ./my-project --width 1920 --height 1080 --wait")}`,
  );
}

/**
 * Build the `-var` list for `terraform apply`: always project/region/image,
 * plus any machine-sizing / scaling flags the caller supplied. Omitted flags
 * fall through to the Terraform module defaults (4 vCPU / 16Gi / 100 / 3600s).
 */
// fallow-ignore-next-line complexity
function machineVars(
  args: Record<string, unknown>,
  project: string,
  region: string,
  image: string,
): string[] {
  const vars = [
    "-var",
    `project_id=${project}`,
    "-var",
    `region=${region}`,
    "-var",
    `image=${image}`,
  ];
  const cpu = args.cpu as string | undefined;
  const memory = args.memory as string | undefined;
  const maxInstances = parsePositiveInt(args["max-instances"], "--max-instances");
  const timeout = parsePositiveInt(args.timeout, "--timeout");
  if (cpu) vars.push("-var", `cpu=${cpu}`);
  if (memory) vars.push("-var", `memory=${memory}`);
  if (maxInstances !== undefined) vars.push("-var", `max_instances=${maxInstances}`);
  if (timeout !== undefined) vars.push("-var", `request_timeout_seconds=${timeout}`);
  return vars;
}

/** Walk up from the terraform dir to find the repo root (the one with the Dockerfile context). */
function findRepoRoot(tfDir: string): string | null {
  // tfDir is <root>/packages/gcp-cloud-run/terraform
  const candidate = resolve(tfDir, "..", "..", "..");
  if (existsSync(join(candidate, "packages", "gcp-cloud-run", "Dockerfile"))) return candidate;
  return null;
}

function writeCloudBuildConfig(image: string): string {
  const cfgPath = join(stateDir(), "cloudrun-cloudbuild.yaml");
  mkdirSync(stateDir(), { recursive: true });
  // The build context (passed to `gcloud builds submit` as the repo root) is
  // referenced as "." inside the config; the Dockerfile path is relative to
  // that context.
  writeFileSync(
    cfgPath,
    [
      "steps:",
      "- name: gcr.io/cloud-builders/docker",
      `  args: ["build","-f","packages/gcp-cloud-run/Dockerfile","-t","${image}","."]`,
      `images: ["${image}"]`,
      "timeout: 3600s",
      "",
    ].join("\n"),
  );
  return cfgPath;
}

// ── sites create ──────────────────────────────────────────────────────────

// fallow-ignore-next-line complexity
async function runSites(args: Record<string, unknown>): Promise<void> {
  if (args.target !== "create") {
    console.error(
      `[cloudrun sites] unknown verb "${String(args.target)}". Only "create" is supported.`,
    );
    failCommand();
  }
  const projectDir = args.extra as string | undefined;
  if (!projectDir) {
    console.error("[cloudrun sites create] usage: hyperframes cloudrun sites create <projectDir>");
    failCommand();
  }
  const state = readState(args);
  const { deploySite } = await loadCloudRunAdapter();
  const handle = await deploySite({
    projectDir: resolve(projectDir),
    bucketName: state.bucketName,
    siteId: args["site-id"] as string | undefined,
  });
  if (args.json) {
    console.log(JSON.stringify(handle, null, 2));
  } else {
    console.log(
      `${handle.uploaded ? c.accent("✓ uploaded") : c.dim("• already present")} ` +
        `site=${handle.siteId} (${handle.bytes} bytes)\n  ${handle.projectGcsUri}`,
    );
  }
}

// ── render ──────────────────────────────────────────────────────────────────

function resolveCloudRunFps(
  args: Record<string, unknown>,
  projectDir: string,
  command: "render" | "render-batch",
): 24 | 30 | 60 {
  const fps =
    parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir, [24, 30, 60]) ?? 30;
  if (fps === 24 || fps === 30 || fps === 60) return fps;
  console.error(`[cloudrun ${command}] --fps must be 24, 30, or 60; got ${fps}.`);
  failCommand();
}

// fallow-ignore-next-line complexity
async function runRender(args: Record<string, unknown>): Promise<void> {
  const projectDir = args.target as string | undefined;
  if (!projectDir) {
    console.error(
      "[cloudrun render] usage: hyperframes cloudrun render <projectDir> --width <px> --height <px>",
    );
    failCommand();
  }
  const width = parsePositiveInt(args.width, "--width");
  const height = parsePositiveInt(args.height, "--height");
  if (width === undefined || height === undefined) {
    console.error("[cloudrun render] --width and --height are required.");
    failCommand();
  }
  const fps = resolveCloudRunFps(args, projectDir, "render");
  const state = readState(args);
  const variables = resolveAndValidateVariables(args, resolve(projectDir));
  const config = buildRenderConfig(args, fps, width, height, variables);

  const { renderToCloudRun, getRenderProgress } = await loadCloudRunAdapter();
  const handle = await renderToCloudRun({
    projectDir: resolve(projectDir),
    config: config as Parameters<typeof renderToCloudRun>[0]["config"],
    bucketName: state.bucketName,
    projectId: state.projectId,
    location: state.region,
    workflowId: state.workflowId,
    serviceUrl: state.serviceUrl,
    renderId: args["render-id"] as string | undefined,
    outputKey: args["output-key"] as string | undefined,
  } as Parameters<typeof renderToCloudRun>[0]);

  if (!args.wait) {
    if (args.json) console.log(JSON.stringify(handle, null, 2));
    else {
      console.log(`${c.accent("✓ render started")} renderId=${handle.renderId}`);
      console.log(`  output → ${handle.outputGcsUri}`);
      console.log(
        `  progress: ${c.accent(`hyperframes cloudrun progress ${handle.executionName}`)}`,
      );
    }
    return;
  }

  const intervalMs = parsePositiveInt(args["wait-interval-ms"], "--wait-interval-ms") ?? 5000;
  let progress = await getRenderProgress({ executionName: handle.executionName });
  while (progress.status === "running") {
    await new Promise((r) => setTimeout(r, intervalMs));
    progress = await getRenderProgress({ executionName: handle.executionName });
    if (!args.json) process.stdout.write(`\r  status=${progress.status} `);
  }
  if (!args.json) process.stdout.write("\n");
  if (args.json) {
    console.log(JSON.stringify(progress, null, 2));
  } else if (progress.status === "succeeded") {
    console.log(
      `${c.accent("✓ done.")} ${progress.outputFile?.gcsUri} (${progress.costs.displayCost})`,
    );
  } else {
    console.error(`${c.error("✗ render " + progress.status)}`);
    for (const e of progress.errors) console.error(`  ${e.state}: ${e.cause}`);
    failCommand();
  }
}

// ── progress ──────────────────────────────────────────────────────────────

// fallow-ignore-next-line complexity
async function runProgress(args: Record<string, unknown>): Promise<void> {
  const executionName = args.target as string | undefined;
  if (!executionName) {
    console.error("[cloudrun progress] usage: hyperframes cloudrun progress <executionName>");
    failCommand();
  }
  const { getRenderProgress } = await loadCloudRunAdapter();
  const progress = await getRenderProgress({ executionName });
  if (args.json) {
    console.log(JSON.stringify(progress, null, 2));
    return;
  }
  console.log(`status=${progress.status} progress=${(progress.overallProgress * 100).toFixed(0)}%`);
  if (progress.totalFrames)
    console.log(`frames=${progress.framesRendered}/${progress.totalFrames}`);
  if (progress.outputFile) console.log(`output=${progress.outputFile.gcsUri}`);
  console.log(`cost=${progress.costs.displayCost}`);
  for (const e of progress.errors) console.error(`  error ${e.state}: ${e.cause}`);
}

// ── render-batch ────────────────────────────────────────────────────────────

interface BatchEntry {
  outputKey: string;
  variables?: Record<string, unknown>;
}

const DEFAULT_BATCH_MAX_CONCURRENT = 50;

/**
 * Fan out N personalised renders of the same project from a JSONL batch file
 * (one `{ outputKey, variables }` per line). Deploys the site once, then
 * starts an execution per entry with a concurrency cap. `--dry-run` prints the
 * resolved manifest without starting anything. Mirrors `hyperframes lambda
 * render-batch`.
 */
// fallow-ignore-next-line complexity
async function runRenderBatch(args: Record<string, unknown>): Promise<void> {
  const projectDir = args.target as string | undefined;
  const batchPath = args.batch as string | undefined;
  if (!projectDir || !batchPath) {
    console.error(
      "[cloudrun render-batch] usage: hyperframes cloudrun render-batch <projectDir> --batch <file.jsonl> --width <px> --height <px>",
    );
    failCommand();
  }
  const width = parsePositiveInt(args.width, "--width");
  const height = parsePositiveInt(args.height, "--height");
  if (width === undefined || height === undefined) {
    console.error("[cloudrun render-batch] --width and --height are required.");
    failCommand();
  }
  const fps = resolveCloudRunFps(args, projectDir, "render-batch");
  if (!existsSync(resolve(batchPath))) {
    console.error(`[cloudrun render-batch] batch file not found: ${batchPath}`);
    failCommand();
  }
  const entries = parseBatchFile(resolve(batchPath));
  if (entries.length === 0) {
    console.error("[cloudrun render-batch] batch file has no entries.");
    failCommand();
  }

  const dryRun = Boolean(args["dry-run"]);
  if (dryRun) {
    const manifest = entries.map((e, i) => ({
      line: i + 1,
      outputKey: e.outputKey,
      status: "would-start",
    }));
    console.log(JSON.stringify(manifest, null, 2));
    return;
  }

  const state = readState(args);
  const maxConcurrent =
    parsePositiveInt(args["max-concurrent"], "--max-concurrent") ?? DEFAULT_BATCH_MAX_CONCURRENT;
  const { deploySite, renderToCloudRun } = await loadCloudRunAdapter();

  // Upload the project once; every entry reuses the same content-addressed
  // site handle so the tar+upload cost is paid a single time.
  const siteHandle = await deploySite({
    projectDir: resolve(projectDir),
    bucketName: state.bucketName,
    siteId: args["site-id"] as string | undefined,
  });

  const results: Array<{ outputKey: string; executionName?: string; error?: string }> = [];
  // Start executions in fixed-size waves so we never exceed `maxConcurrent`
  // in-flight CreateExecution calls.
  for (let i = 0; i < entries.length; i += maxConcurrent) {
    const wave = entries.slice(i, i + maxConcurrent);
    const settled = await Promise.all(
      wave.map(async (entry) => {
        try {
          const config = buildRenderConfig(args, fps, width, height, entry.variables);
          const handle = await renderToCloudRun({
            siteHandle,
            config: config as Parameters<typeof renderToCloudRun>[0]["config"],
            bucketName: state.bucketName,
            projectId: state.projectId,
            location: state.region,
            workflowId: state.workflowId,
            serviceUrl: state.serviceUrl,
            outputKey: entry.outputKey,
          } as Parameters<typeof renderToCloudRun>[0]);
          return { outputKey: entry.outputKey, executionName: handle.executionName };
        } catch (err) {
          return {
            outputKey: entry.outputKey,
            error: normalizeErrorMessage(err),
          };
        }
      }),
    );
    results.push(...settled);
  }

  const failed = results.filter((r) => r.error);
  if (args.json) {
    console.log(JSON.stringify(results, null, 2));
  } else {
    console.log(
      `${c.accent("✓ started")} ${results.length - failed.length}/${results.length} renders`,
    );
    for (const r of failed) console.error(`  ✗ ${r.outputKey}: ${r.error}`);
  }
  if (failed.length > 0) failCommand();
}

/** Parse a JSONL batch file into entries, exiting with a clear error on a bad line. */
function parseBatchFile(path: string): BatchEntry[] {
  const lines = readFileSync(path, "utf8").split(/\r?\n/);
  const entries: BatchEntry[] = [];
  // fallow-ignore-next-line complexity
  lines.forEach((line, idx) => {
    const trimmed = line.trim();
    if (!trimmed) return;
    let parsed: unknown;
    try {
      parsed = JSON.parse(trimmed);
    } catch {
      console.error(`[cloudrun render-batch] line ${idx + 1}: not valid JSON`);
      failCommand();
    }
    if (
      !parsed ||
      typeof parsed !== "object" ||
      typeof (parsed as BatchEntry).outputKey !== "string"
    ) {
      console.error(
        `[cloudrun render-batch] line ${idx + 1}: must be an object with a string "outputKey"`,
      );
      failCommand();
    }
    entries.push(parsed as BatchEntry);
  });
  return entries;
}

// ── destroy ──────────────────────────────────────────────────────────────

// fallow-ignore-next-line complexity
async function runDestroy(args: Record<string, unknown>): Promise<void> {
  const { getTerraformModuleDir } = await loadCloudRunAdapter();
  const tfDir = getTerraformModuleDir();
  const state = existsSync(statePath())
    ? (JSON.parse(readFileSync(statePath(), "utf8")) as Partial<StackState>)
    : {};
  const project = (args.project as string | undefined) ?? state.projectId;
  const region = (args.region as string | undefined) ?? state.region ?? "us-central1";
  const image = (args.image as string | undefined) ?? "unused:latest";
  if (!project) {
    console.error("[cloudrun destroy] --project is required (or deploy first to cache it).");
    failCommand();
  }
  const vars = [
    "-var",
    `project_id=${project}`,
    "-var",
    `region=${region}`,
    "-var",
    `image=${image}`,
    "-var",
    "bucket_force_destroy=true",
  ];
  console.log("→ terraform destroy");
  run("terraform", ["init", "-input=false"], { cwd: tfDir });
  // Apply `bucket_force_destroy=true` into state FIRST. Terraform reads a
  // bucket's force_destroy from prior state when emptying it during destroy,
  // so passing the var only at destroy time can't flip it — a destroy of a
  // bucket that still holds render artifacts would fail with "bucket not
  // empty". The quick apply updates the attribute, then destroy can sweep
  // the (scratch) bucket. Best-effort: if there's nothing to apply this
  // no-ops.
  try {
    run("terraform", ["apply", "-input=false", "-auto-approve", ...vars], { cwd: tfDir });
  } catch {
    // A failed pre-apply shouldn't block the destroy attempt below.
  }
  run("terraform", ["destroy", "-input=false", "-auto-approve", ...vars], { cwd: tfDir });
  console.log(`${c.accent("✓ destroyed.")}`);
}

// ── config + variables helpers (shared by render + render-batch) ────────────

/**
 * Build the serializable render config from CLI flags. `variables` is resolved
 * separately (it differs per batch entry). Mirrors the local `hyperframes
 * render` flag surface so the two stay consistent.
 */
/**
 * Exported for unit-test coverage of the aspect-agnostic wire shape — the
 * portrait-1080p sibling-surface regression that shipped in v0.7.60 landed
 * here because this builder dropped the tier-alias signal on the floor.
 */
export function buildRenderConfig(
  args: Record<string, unknown>,
  fps: number,
  width: number,
  height: number,
  variables: Record<string, unknown> | undefined,
): Record<string, unknown> {
  const { outputResolution, outputResolutionAspectAgnostic } = parseOutputResolution(
    args["output-resolution"],
  );
  return stripUndefined({
    fps,
    width,
    height,
    format: parseFormat(args.format),
    codec: parseCodec(args.codec),
    quality: parseQuality(args.quality),
    chunkSize: parsePositiveInt(args["chunk-size"], "--chunk-size"),
    maxParallelChunks: parsePositiveInt(args["max-parallel-chunks"], "--max-parallel-chunks"),
    targetChunkFrames: parsePositiveInt(args["target-chunk-frames"], "--target-chunk-frames"),
    outputResolution,
    // Set only when true so the wire shape stays sparse for the common
    // canonical-preset path (matches how the flag flows through
    // `SerializableDistributedRenderConfig` from every other emitter).
    outputResolutionAspectAgnostic: outputResolutionAspectAgnostic ? true : undefined,
    variables,
  });
}

/**
 * Resolve --variables / --variables-file via the shared CLI parser (the same
 * one `hyperframes render` and `hyperframes lambda render` use), then validate
 * against the composition's `data-composition-variables` when an `index.html`
 * is on disk. `--strict-variables` turns mismatches into a hard failure.
 */
function resolveAndValidateVariables(
  args: Record<string, unknown>,
  projectDir: string,
): Record<string, unknown> | undefined {
  const variables = resolveVariablesArg(
    args.variables as string | undefined,
    args["variables-file"] as string | undefined,
  );
  if (variables && Object.keys(variables).length > 0) {
    const indexPath = join(projectDir, "index.html");
    if (existsSync(indexPath)) {
      const issues = validateVariablesAgainstProject(indexPath, variables);
      reportVariableIssues(issues, {
        strict: Boolean(args["strict-variables"]),
        quiet: Boolean(args.json),
      });
    }
  }
  return variables;
}

/**
 * Cloud Run flavor of the shared {@link parseOutputResolutionFlag} — carries
 * the aspect-agnostic signal through so `SerializableDistributedRenderConfig`
 * can trigger the compile-stage remap. The runtime work lives in the shared
 * util; wire-config-level coverage lives at `cloudrun.test.ts`, and full
 * input-space coverage at `../utils/parseOutputResolution.test.ts`.
 */
function parseOutputResolution(raw: unknown): {
  outputResolution: CanvasResolution | undefined;
  outputResolutionAspectAgnostic: boolean;
} {
  return parseOutputResolutionFlag(raw, { surfaceLabel: "[cloudrun render]" });
}

// ── parse helpers ─────────────────────────────────────────────────────────

// fallow-ignore-next-line complexity
function parseIntFlag(raw: unknown): number | undefined {
  if (raw === undefined || raw === null || raw === "") return undefined;
  const n = Number.parseInt(String(raw), 10);
  return Number.isFinite(n) ? n : undefined;
}
function parsePositiveInt(raw: unknown, flagName: string): number | undefined {
  const n = parseIntFlag(raw);
  if (n === undefined) return undefined;
  if (!Number.isInteger(n) || n < 1) {
    throw new Error(`[cloudrun] ${flagName} must be a positive integer; got ${n}`);
  }
  return n;
}
// fallow-ignore-next-line complexity
function parseEnum<T extends string>(
  raw: unknown,
  allowed: readonly T[],
  errorPrefix: string,
  defaultValue: T | undefined,
): T | undefined {
  if (raw === undefined || raw === null || raw === "") return defaultValue;
  const s = String(raw);
  if ((allowed as readonly string[]).includes(s)) return s as T;
  throw new Error(`${errorPrefix} must be ${allowed.join("|")}; got ${s}`);
}
const FORMATS = ["mp4", "mov", "png-sequence", "webm"] as const;
const CODECS = ["h264", "h265"] as const;
const QUALITIES = ["draft", "standard", "high"] as const;
const parseFormat = (raw: unknown): (typeof FORMATS)[number] =>
  parseEnum(raw, FORMATS, "[cloudrun render] --format", "mp4")!;
const parseCodec = (raw: unknown): (typeof CODECS)[number] | undefined =>
  parseEnum(raw, CODECS, "[cloudrun render] --codec", undefined);
const parseQuality = (raw: unknown): (typeof QUALITIES)[number] | undefined =>
  parseEnum(raw, QUALITIES, "[cloudrun render] --quality", undefined);