@storewright/cli 0.14.0

package/scripts/upload-shopify-media.mjs

@@ -0,0 +1,831 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const defaultApiVersion = "2026-04";
+const defaultStagedUploadTimeoutMs = 120000;
+const defaultStagedUploadMaxAttempts = 6;
+const defaultStagedUploadRetryDelayMs = 1000;
+const defaultGraphqlCommandMaxAttempts = 3;
+const defaultGraphqlCommandRetryDelayMs = 1000;
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--run-dir") {
+      args.runDir = argv[index + 1];
+      index += 1;
+    } else if (arg === "--manifest") {
+      args.manifestPath = argv[index + 1];
+      index += 1;
+    } else if (arg === "--store") {
+      args.store = argv[index + 1];
+      index += 1;
+    } else if (arg === "--output-report") {
+      args.outputReportPath = argv[index + 1];
+      index += 1;
+    } else if (arg === "--api-version") {
+      args.apiVersion = argv[index + 1];
+      index += 1;
+    } else if (arg === "--staged-upload-timeout-ms") {
+      args.stagedUploadTimeoutMs = Number(argv[index + 1]);
+      index += 1;
+    } else if (arg === "--staged-upload-max-attempts") {
+      args.stagedUploadMaxAttempts = Number(argv[index + 1]);
+      index += 1;
+    } else if (arg === "--staged-upload-retry-delay-ms") {
+      args.stagedUploadRetryDelayMs = Number(argv[index + 1]);
+      index += 1;
+    }
+  }
+  return args;
+}
+
+function resolveRunPath(runDir, filePath) {
+  if (!filePath || isAbsolute(filePath)) return filePath;
+  return join(runDir, filePath);
+}
+
+function serializeCommand(command, args) {
+  return [command, ...args].join(" ");
+}
+
+function runBufferedCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options.spawnOptions ?? {});
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, options.timeoutMs ?? 300000);
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (options.streamOutput) process.stdout.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      if (options.streamOutput) process.stderr.write(chunk);
+    });
+    child.on("error", (error) => {
+      stderr = stderr || error.message;
+      if (options.streamOutput) process.stderr.write(`${error.message}\n`);
+      finish({
+        exitCode: typeof error.code === "number" ? error.code : 1,
+        stdout,
+        stderr,
+        timedOut
+      });
+    });
+    child.on("close", (exitCode, signal) => {
+      finish({
+        exitCode: exitCode ?? 1,
+        stdout,
+        stderr,
+        timedOut: timedOut || signal === "SIGTERM"
+      });
+    });
+  });
+}
+
+function defaultRunCommand(command, args, options = {}) {
+  return runBufferedCommand(command, args, { ...options, streamOutput: true });
+}
+
+function describeError(error) {
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error ?? "Unknown error");
+  const cause = error?.cause;
+  if (!cause) return message;
+  if (cause instanceof Error) return `${message}; cause: ${cause.name}: ${cause.message}`;
+  if (typeof cause !== "object") return `${message}; cause: ${String(cause)}`;
+
+  const details = ["code", "errno", "syscall", "hostname", "host", "port", "address"]
+    .filter((key) => cause[key] !== undefined)
+    .map((key) => `${key}=${cause[key]}`)
+    .join(" ");
+  return details ? `${message}; cause: ${details}` : `${message}; cause: ${JSON.stringify(cause)}`;
+}
+
+async function defaultUploadStagedFile({
+  stagedTarget,
+  localPath,
+  mimeType = "application/octet-stream",
+  timeoutMs = defaultStagedUploadTimeoutMs
+}) {
+  const args = [
+    "--http1.1",
+    "--silent",
+    "--show-error",
+    "--max-time",
+    String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+    "--write-out",
+    "\n%{http_code}",
+    "--request",
+    "POST"
+  ];
+  for (const parameter of stagedTarget.parameters ?? []) {
+    args.push("--form-string", `${parameter.name}=${parameter.value}`);
+  }
+  args.push("--form", `file=@${localPath};type=${mimeType}`);
+  args.push(stagedTarget.url);
+
+  const result = await runBufferedCommand("curl", args, { timeoutMs: timeoutMs + 1000 });
+  const stdout = result.stdout ?? "";
+  const statusMatch = stdout.match(/\n(\d{3})\s*$/);
+  const status = statusMatch ? Number(statusMatch[1]) : 0;
+  const body = statusMatch ? stdout.slice(0, statusMatch.index) : stdout;
+  const stderr = result.stderr || (result.timedOut ? `staged upload timed out after ${timeoutMs}ms` : "");
+  return {
+    ok: result.exitCode === 0 && status >= 200 && status < 300,
+    status,
+    stdout: body,
+    stderr
+  };
+}
+
+function defaultWait(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function commandStatus(result) {
+  if (result.timedOut) return "timeout";
+  return result.exitCode === 0 ? "success" : "error";
+}
+
+function toAttempt(command, args, result, metadata = {}) {
+  return {
+    command: serializeCommand(command, args),
+    status: commandStatus(result),
+    exitCode: result.exitCode ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    ...metadata
+  };
+}
+
+function retryableShopifyCliFailure(result) {
+  if (!result) return false;
+  const evidence = `${result.stderr ?? ""}\n${result.stdout ?? ""}`;
+  if (/access denied|required access|missing access|scope|token|login|unauthor/i.test(evidence)) {
+    return false;
+  }
+  if (result.timedOut) return true;
+  if (result.exitCode === 0) return false;
+  return /network socket|TLS|SSL|ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|fetch failed|aborted a request|check your internet connection|shopify\/cli\/dist\/index\.js/i.test(evidence);
+}
+
+function graphqlTopErrors(json) {
+  return Array.isArray(json?.errors) ? json.errors : [];
+}
+
+function graphqlPayload(json, operationName) {
+  return json?.data?.[operationName] ?? json?.[operationName];
+}
+
+function parseJsonObject(text) {
+  const raw = String(text ?? "").trim();
+  try {
+    return JSON.parse(raw);
+  } catch {
+    let lastParsed = null;
+    for (let start = 0; start < raw.length; start += 1) {
+      if (raw[start] !== "{") continue;
+      let depth = 0;
+      let inString = false;
+      let escaped = false;
+      for (let index = start; index < raw.length; index += 1) {
+        const char = raw[index];
+        if (inString) {
+          if (escaped) {
+            escaped = false;
+          } else if (char === "\\") {
+            escaped = true;
+          } else if (char === "\"") {
+            inString = false;
+          }
+          continue;
+        }
+        if (char === "\"") {
+          inString = true;
+        } else if (char === "{") {
+          depth += 1;
+        } else if (char === "}") {
+          depth -= 1;
+          if (depth === 0) {
+            try {
+              lastParsed = JSON.parse(raw.slice(start, index + 1));
+            } catch {
+              // Keep scanning for the final valid JSON object in noisy CLI output.
+            }
+            start = index;
+            break;
+          }
+        }
+      }
+    }
+    return lastParsed;
+  }
+}
+
+function parseShopifyJson(result) {
+  return parseJsonObject(result.stdout);
+}
+
+function safeOperationName(operationName) {
+  return String(operationName ?? "operation")
+    .replace(/[^A-Za-z0-9_.-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "operation";
+}
+
+async function writeGraphqlOperationFiles({ operationFileDir, commandAttempts, operationName, query, variables }) {
+  const basename = `${String(commandAttempts.length + 1).padStart(2, "0")}-${safeOperationName(operationName)}`;
+  const queryFile = join(operationFileDir, `${basename}.graphql`);
+  const variableFile = join(operationFileDir, `${basename}-variables.json`);
+  await mkdir(operationFileDir, { recursive: true });
+  await writeFile(queryFile, `${query.trim()}\n`);
+  await writeFile(variableFile, `${JSON.stringify(variables ?? {}, null, 2)}\n`);
+  return { queryFile, variableFile };
+}
+
+async function runRecorded({ commandAttempts, runCommand, command, args, options, metadata }) {
+  const result = await runCommand(command, args, options);
+  commandAttempts.push(toAttempt(command, args, result, metadata));
+  return result;
+}
+
+async function runGraphql({
+  commandAttempts,
+  runCommand,
+  store,
+  apiVersion,
+  operationFileDir,
+  operationName,
+  query,
+  variables,
+  allowMutations = true,
+  wait = defaultWait,
+  graphqlCommandMaxAttempts = defaultGraphqlCommandMaxAttempts,
+  graphqlCommandRetryDelayMs = defaultGraphqlCommandRetryDelayMs
+}) {
+  const args = [
+    "store",
+    "execute",
+    "--store",
+    store
+  ];
+  if (allowMutations) args.push("--allow-mutations");
+  if (operationFileDir) {
+    const { queryFile, variableFile } = await writeGraphqlOperationFiles({
+      operationFileDir,
+      commandAttempts,
+      operationName,
+      query,
+      variables
+    });
+    args.push(
+      "--json",
+      "--version",
+      apiVersion,
+      "--query-file",
+      queryFile,
+      "--variable-file",
+      variableFile
+    );
+  } else {
+    args.push(
+      "--json",
+      "--version",
+      apiVersion,
+      "--query",
+      query,
+      "--variables",
+      JSON.stringify(variables)
+    );
+  }
+  const maxAttempts = Math.max(1, Number.isFinite(graphqlCommandMaxAttempts) ? graphqlCommandMaxAttempts : defaultGraphqlCommandMaxAttempts);
+  const retryDelayMs = Math.max(0, Number.isFinite(graphqlCommandRetryDelayMs) ? graphqlCommandRetryDelayMs : defaultGraphqlCommandRetryDelayMs);
+  let result = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    result = await runRecorded({
+      commandAttempts,
+      runCommand,
+      command: "shopify",
+      args,
+      metadata: maxAttempts > 1 ? { attempt, maxAttempts } : {}
+    });
+    if (!retryableShopifyCliFailure(result) || attempt >= maxAttempts) return result;
+    if (retryDelayMs > 0) await wait(retryDelayMs);
+  }
+  return result;
+}
+
+function stagedUploadsCreateMutation() {
+  return `mutation stagedUploadsCreate($input: [StagedUploadInput!]!) {
+    stagedUploadsCreate(input: $input) {
+      stagedTargets {
+        url
+        resourceUrl
+        parameters {
+          name
+          value
+        }
+      }
+      userErrors {
+        field
+        message
+      }
+    }
+  }`;
+}
+
+function fileCreateMutation() {
+  return `mutation fileCreate($files: [FileCreateInput!]!) {
+    fileCreate(files: $files) {
+      files {
+        id
+        fileStatus
+        alt
+        ... on MediaImage {
+          image {
+            url
+          }
+        }
+      }
+      userErrors {
+        field
+        message
+      }
+    }
+  }`;
+}
+
+function fileNodeQuery() {
+  return `query fileNode($id: ID!) {
+    node(id: $id) {
+      ... on MediaImage {
+        id
+        fileStatus
+        alt
+        image {
+          url
+        }
+      }
+    }
+  }`;
+}
+
+function userErrorMessages(errors) {
+  return (errors ?? []).map((error) => error.message).filter(Boolean);
+}
+
+function collectUserErrors(graphqlUserErrors, errors) {
+  for (const error of errors ?? []) {
+    graphqlUserErrors.push({
+      message: error.message,
+      ...(Array.isArray(error.field) ? { field: error.field } : {})
+    });
+  }
+}
+
+function baseAsset(asset) {
+  return {
+    assetId: asset.assetId,
+    ...(asset.slotId ? { slotId: asset.slotId } : {}),
+    ...(asset.candidateId ? { candidateId: asset.candidateId } : {}),
+    localPath: asset.localPath,
+    ...(asset.seoFilename ? { seoFilename: asset.seoFilename } : {}),
+    ...(asset.altText ? { altText: asset.altText } : {})
+  };
+}
+
+function shopifyFileUrl(file) {
+  return file?.image?.url || file?.url || null;
+}
+
+function uploadMetadataWarning(asset) {
+  if (!asset.seoFilename) {
+    return "ready-for-upload asset is missing seoFilename";
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+$/.test(asset.seoFilename)) {
+    return `seoFilename must be a lowercase hyphenated filename with extension: ${asset.seoFilename}`;
+  }
+  if (/^image-\d+\.[a-z0-9]+$/.test(asset.seoFilename)) {
+    return `seoFilename must be descriptive, not a raw downloaded image filename: ${asset.seoFilename}`;
+  }
+  if (!String(asset.altText ?? "").trim()) {
+    return "ready-for-upload asset is missing altText";
+  }
+  if (/\bproduct image\s*\d+\b/i.test(asset.altText) || /^image\s*\d+$/i.test(asset.altText)) {
+    return `altText must be descriptive, not generic altText: ${asset.altText}`;
+  }
+  return null;
+}
+
+function shopifyIdKey(id) {
+  return id?.includes("/MediaImage/") ? "shopifyMediaId" : "shopifyFileId";
+}
+
+function stagedTargetContentType(stagedTarget) {
+  return (stagedTarget.parameters ?? []).find((parameter) => parameter.name.toLowerCase() === "content-type")?.value;
+}
+
+async function resolveMediaImageUrl({
+  file,
+  commandAttempts,
+  graphqlUserErrors,
+  runCommand,
+  store,
+  apiVersion,
+  operationFileDir,
+  wait,
+  pollFileStatusAttempts,
+  pollFileStatusDelayMs,
+  graphqlCommandMaxAttempts,
+  graphqlCommandRetryDelayMs
+}) {
+  const immediateUrl = shopifyFileUrl(file);
+  if (!file?.id || immediateUrl || !file.id.includes("/MediaImage/")) {
+    return { file, shopifyUrl: immediateUrl, warnings: [] };
+  }
+
+  let lastStatus = file.fileStatus;
+  for (let attempt = 0; attempt < pollFileStatusAttempts; attempt += 1) {
+    if (attempt > 0 && pollFileStatusDelayMs > 0) await wait(pollFileStatusDelayMs);
+
+    const nodeResult = await runGraphql({
+      commandAttempts,
+      runCommand,
+      store,
+      apiVersion,
+      operationFileDir,
+      operationName: "fileNode",
+      query: fileNodeQuery(),
+      variables: { id: file.id },
+      allowMutations: false,
+      wait,
+      graphqlCommandMaxAttempts,
+      graphqlCommandRetryDelayMs
+    });
+
+    if (nodeResult.exitCode !== 0) {
+      return {
+        file,
+        shopifyUrl: null,
+        warnings: [nodeResult.stderr || nodeResult.stdout || "MediaImage URL status check failed"]
+      };
+    }
+
+    const nodeJson = parseShopifyJson(nodeResult);
+    const nodeTopErrors = graphqlTopErrors(nodeJson);
+    collectUserErrors(graphqlUserErrors, nodeTopErrors);
+    if (nodeTopErrors.length > 0) {
+      return { file, shopifyUrl: null, warnings: userErrorMessages(nodeTopErrors) };
+    }
+
+    const node = graphqlPayload(nodeJson, "node");
+    lastStatus = node?.fileStatus ?? lastStatus;
+    const nodeUrl = shopifyFileUrl(node);
+    if (node?.id && nodeUrl) return { file: node, shopifyUrl: nodeUrl, warnings: [] };
+  }
+
+  return {
+    file,
+    shopifyUrl: null,
+    warnings: [`MediaImage URL was not ready after ${pollFileStatusAttempts} status check(s); last fileStatus: ${lastStatus ?? "unknown"}`]
+  };
+}
+
+async function uploadReadyAsset({
+  asset,
+  runDir,
+  store,
+  apiVersion,
+  commandAttempts,
+  graphqlUserErrors,
+  runCommand,
+  operationFileDir,
+  uploadStagedFile,
+  wait,
+  pollFileStatusAttempts,
+  pollFileStatusDelayMs,
+  stagedUploadTimeoutMs,
+  stagedUploadMaxAttempts,
+  stagedUploadRetryDelayMs,
+  graphqlCommandMaxAttempts,
+  graphqlCommandRetryDelayMs
+}) {
+  const localPath = resolveRunPath(runDir, asset.localPath);
+  const warnings = [];
+
+  const stagedResult = await runGraphql({
+    commandAttempts,
+    runCommand,
+    store,
+    apiVersion,
+    operationFileDir,
+    operationName: "stagedUploadsCreate",
+    query: stagedUploadsCreateMutation(),
+    variables: {
+      input: [{
+        filename: asset.seoFilename,
+        mimeType: asset.mimeType ?? "image/webp",
+        resource: "IMAGE",
+        httpMethod: "POST"
+      }]
+    },
+    wait,
+    graphqlCommandMaxAttempts,
+    graphqlCommandRetryDelayMs
+  });
+
+  if (stagedResult.exitCode !== 0) {
+    warnings.push(stagedResult.stderr || stagedResult.stdout || "stagedUploadsCreate failed");
+    return { ...baseAsset(asset), uploadStatus: "error", warnings };
+  }
+
+  const stagedJson = parseShopifyJson(stagedResult);
+  const stagedTopErrors = graphqlTopErrors(stagedJson);
+  collectUserErrors(graphqlUserErrors, stagedTopErrors);
+  if (stagedTopErrors.length > 0) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: userErrorMessages(stagedTopErrors) };
+  }
+
+  const stagedPayload = graphqlPayload(stagedJson, "stagedUploadsCreate");
+  const stagedErrors = stagedPayload?.userErrors ?? [];
+  collectUserErrors(graphqlUserErrors, stagedErrors);
+  if (stagedErrors.length > 0) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: userErrorMessages(stagedErrors) };
+  }
+
+  const stagedTarget = stagedPayload?.stagedTargets?.[0];
+  if (!stagedTarget?.url || !stagedTarget?.resourceUrl) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: ["stagedUploadsCreate returned no staged target"] };
+  }
+
+  let uploadResult = null;
+  const uploadWarnings = [];
+  const maxAttempts = Math.max(1, Number.isFinite(stagedUploadMaxAttempts) ? stagedUploadMaxAttempts : defaultStagedUploadMaxAttempts);
+  const retryDelayMs = Math.max(0, Number.isFinite(stagedUploadRetryDelayMs) ? stagedUploadRetryDelayMs : defaultStagedUploadRetryDelayMs);
+  const mimeType = asset.mimeType ?? stagedTargetContentType(stagedTarget) ?? "application/octet-stream";
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      uploadResult = await uploadStagedFile({
+        stagedTarget,
+        localPath,
+        mimeType,
+        timeoutMs: stagedUploadTimeoutMs
+      });
+    } catch (error) {
+      uploadResult = {
+        ok: false,
+        status: 0,
+        stdout: "",
+        stderr: describeError(error)
+      };
+    }
+    commandAttempts.push({
+      command: `POST ${stagedTarget.url}`,
+      status: uploadResult.ok ? "success" : "error",
+      exitCode: uploadResult.ok ? 0 : uploadResult.status || 1,
+      stdout: uploadResult.stdout ?? "",
+      stderr: uploadResult.stderr ?? "",
+      attempt,
+      maxAttempts
+    });
+    if (uploadResult.ok) break;
+    uploadWarnings.push(uploadResult.stderr || "staged upload failed");
+    if (attempt < maxAttempts && retryDelayMs > 0) await wait(retryDelayMs);
+  }
+  if (!uploadResult.ok) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: uploadWarnings.length > 0 ? uploadWarnings : ["staged upload failed"] };
+  }
+
+  const fileResult = await runGraphql({
+    commandAttempts,
+    runCommand,
+    store,
+    apiVersion,
+    operationFileDir,
+    operationName: "fileCreate",
+    query: fileCreateMutation(),
+    variables: {
+      files: [{
+        alt: asset.altText,
+        contentType: "IMAGE",
+        duplicateResolutionMode: "RAISE_ERROR",
+        filename: asset.seoFilename,
+        originalSource: stagedTarget.resourceUrl
+      }]
+    },
+    wait,
+    graphqlCommandMaxAttempts,
+    graphqlCommandRetryDelayMs
+  });
+
+  if (fileResult.exitCode !== 0) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: [fileResult.stderr || fileResult.stdout || "fileCreate failed"] };
+  }
+
+  const fileJson = parseShopifyJson(fileResult);
+  const fileTopErrors = graphqlTopErrors(fileJson);
+  collectUserErrors(graphqlUserErrors, fileTopErrors);
+  if (fileTopErrors.length > 0) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: userErrorMessages(fileTopErrors) };
+  }
+
+  const filePayload = graphqlPayload(fileJson, "fileCreate");
+  const fileErrors = filePayload?.userErrors ?? [];
+  collectUserErrors(graphqlUserErrors, fileErrors);
+  if (fileErrors.length > 0) {
+    return { ...baseAsset(asset), uploadStatus: "error", warnings: userErrorMessages(fileErrors) };
+  }
+
+  const createdFile = filePayload?.files?.[0];
+  const resolvedFile = await resolveMediaImageUrl({
+    file: createdFile,
+    commandAttempts,
+    graphqlUserErrors,
+    runCommand,
+    store,
+    apiVersion,
+    operationFileDir,
+    wait,
+    pollFileStatusAttempts,
+    pollFileStatusDelayMs,
+    graphqlCommandMaxAttempts,
+    graphqlCommandRetryDelayMs
+  });
+
+  if (!resolvedFile.file?.id || !resolvedFile.shopifyUrl) {
+    return {
+      ...baseAsset(asset),
+      uploadStatus: "error",
+      warnings: resolvedFile.warnings.length > 0 ? resolvedFile.warnings : ["fileCreate returned no Shopify file ID or URL"]
+    };
+  }
+
+  const idKey = shopifyIdKey(resolvedFile.file.id);
+  return {
+    ...baseAsset(asset),
+    [idKey]: resolvedFile.file.id,
+    shopifyUrl: resolvedFile.shopifyUrl,
+    uploadStatus: "uploaded"
+  };
+}
+
+export async function uploadShopifyMedia({
+  runDir,
+  manifestPath,
+  store,
+  outputReportPath,
+  apiVersion = defaultApiVersion,
+  runCommand = defaultRunCommand,
+  uploadStagedFile = defaultUploadStagedFile,
+  wait = defaultWait,
+  pollFileStatusAttempts = 6,
+  pollFileStatusDelayMs = 5000,
+  stagedUploadTimeoutMs = defaultStagedUploadTimeoutMs,
+  stagedUploadMaxAttempts = defaultStagedUploadMaxAttempts,
+  stagedUploadRetryDelayMs = defaultStagedUploadRetryDelayMs,
+  graphqlCommandMaxAttempts = defaultGraphqlCommandMaxAttempts,
+  graphqlCommandRetryDelayMs = defaultGraphqlCommandRetryDelayMs
+}) {
+  if (!runDir) throw new Error("Missing --run-dir argument");
+  if (!manifestPath) throw new Error("Missing --manifest argument");
+  if (!store) throw new Error("Missing --store argument");
+
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  const resolvedOutputPath = outputReportPath ?? join(runDir, "shopify-media-upload-report.json");
+  const operationFileDir = join(dirname(resolvedOutputPath), "shopify-media-upload-graphql");
+  const commandAttempts = [];
+  const graphqlUserErrors = [];
+  const uploadedAssets = [];
+  const readySeoFilenameCounts = new Map();
+  for (const asset of manifest.media?.assets ?? []) {
+    if (asset.status === "ready-for-upload" && asset.seoFilename) {
+      const key = asset.seoFilename.toLowerCase();
+      readySeoFilenameCounts.set(key, (readySeoFilenameCounts.get(key) ?? 0) + 1);
+    }
+  }
+
+  for (const asset of manifest.media?.assets ?? []) {
+    if (asset.status !== "ready-for-upload") {
+      uploadedAssets.push({
+        ...baseAsset(asset),
+        uploadStatus: "skipped",
+        warnings: [`asset status is ${asset.status ?? "unknown"}, not ready-for-upload`]
+      });
+      continue;
+    }
+
+    if (/^https?:\/\//i.test(asset.localPath ?? "")) {
+      uploadedAssets.push({
+        ...baseAsset(asset),
+        uploadStatus: "error",
+        warnings: ["localPath must be a run-local file path; raw supplier URL cannot be final Shopify media"]
+      });
+      continue;
+    }
+
+    const metadataWarning = uploadMetadataWarning(asset);
+    if (metadataWarning) {
+      uploadedAssets.push({
+        ...baseAsset(asset),
+        uploadStatus: "error",
+        warnings: [metadataWarning]
+      });
+      continue;
+    }
+
+    if (readySeoFilenameCounts.get(asset.seoFilename.toLowerCase()) > 1) {
+      uploadedAssets.push({
+        ...baseAsset(asset),
+        uploadStatus: "error",
+        warnings: [`duplicate seoFilename among ready-for-upload assets: ${asset.seoFilename}`]
+      });
+      continue;
+    }
+
+    const localPath = resolveRunPath(runDir, asset.localPath);
+    if (!existsSync(localPath)) {
+      uploadedAssets.push({
+        ...baseAsset(asset),
+        uploadStatus: "error",
+        warnings: [`localPath does not exist: ${asset.localPath}`]
+      });
+      continue;
+    }
+
+    uploadedAssets.push(await uploadReadyAsset({
+      asset,
+      runDir,
+      store,
+      apiVersion,
+      commandAttempts,
+      graphqlUserErrors,
+      runCommand,
+      operationFileDir,
+      uploadStagedFile,
+      wait,
+      pollFileStatusAttempts,
+      pollFileStatusDelayMs,
+      stagedUploadTimeoutMs,
+      stagedUploadMaxAttempts,
+      stagedUploadRetryDelayMs,
+      graphqlCommandMaxAttempts,
+      graphqlCommandRetryDelayMs
+    }));
+  }
+
+  const report = {
+    schemaVersion: "1.0.0",
+    runId: manifest.runId,
+    authoring: {
+      mode: "worker-authored",
+      createdBy: "shopify-media-upload-worker",
+      sourceInputArtifacts: ["media-manifest.json"]
+    },
+    shopifyMediaUpload: {
+      targetStore: store,
+      apiVersion,
+      commandAttempts,
+      graphqlUserErrors,
+      assets: uploadedAssets
+    }
+  };
+
+  await mkdir(dirname(resolvedOutputPath), { recursive: true });
+  await writeFile(resolvedOutputPath, `${JSON.stringify(report, null, 2)}\n`);
+  return { outputReportPath: resolvedOutputPath, assetCount: uploadedAssets.length };
+}
+
+async function main() {
+  try {
+    const result = await uploadShopifyMedia(parseArgs(process.argv.slice(2)));
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}