@storewright/cli 0.14.0

package/scripts/audit-run-state.mjs

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const expectedGateArtifacts = new Map([
+  ["1 Intake", "intake-gate.json"],
+  ["1A Shopify Access Preflight", "shopify-access-preflight-gate.json"],
+  ["2 Product Source Normalize", "product-source-normalize-gate.json"],
+  ["3 Supplier Extraction", "supplier-extraction-gate.json"],
+  ["4 Product Content", "product-content-quality-report.json"],
+  ["5 Merchandising Strategy", "merchandising-quality-report.json"],
+  ["6 Brand Identity", "brand-identity-quality-report.json"],
+  ["7 Store Content", "store-content-quality-report.json"],
+  ["8 Design Direction", "design-quality-report.json"],
+  ["9 Store Blueprint", "store-blueprint-quality-report.json"],
+  ["10 Theme Build And Apply", "theme-quality-report.json"],
+  ["11A Shopify Preflight Auth Scope", "shopify-preflight-gate.json"],
+  ["11B Shopify Products Collections", "shopify-products-sync-gate.json"],
+  ["11C Shopify Content Navigation", "shopify-content-sync-gate.json"],
+  ["11D Shopify Theme Push", "theme-push-gate.json"],
+  ["11E Shopify Store Ops Consolidation", "store-ops-quality-report.json"],
+  ["12 Launch Readiness", "launch-readiness-gate.json"]
+]);
+
+const gateStatuses = new Set(["pass", "warning", "repairable", "blocked", "fatal"]);
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--run-dir") {
+      options.runDir = argv[index + 1];
+      index += 1;
+    } else if (arg === "--now") {
+      options.now = new Date(argv[index + 1]);
+      index += 1;
+    } else if (arg === "--json") {
+      options.json = true;
+    }
+  }
+  return options;
+}
+
+async function readTextIfExists(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  return readFile(path, "utf8");
+}
+
+async function readJsonIfExists(path) {
+  const text = await readTextIfExists(path);
+  if (text === null) {
+    return null;
+  }
+  return JSON.parse(text);
+}
+
+function check(name, result, details) {
+  return { name, result, details };
+}
+
+function isPass(checkResult) {
+  return checkResult.result === "ok";
+}
+
+function parseProgress(progress) {
+  const currentStage = progress.match(/^Current stage:\s*(.+)$/m)?.[1]?.trim() ?? null;
+  const lastUpdated = progress.match(/^Last updated:\s*(.+)$/m)?.[1]?.trim() ?? null;
+  const resumeInstructions = markdownSection(progress, "Resume Instructions").trim();
+  const rows = [];
+
+  for (const line of progress.split(/\r?\n/)) {
+    if (!line.startsWith("|")) {
+      continue;
+    }
+    if (/^\|\s*-+/.test(line) || /Stage\s*\|/.test(line)) {
+      continue;
+    }
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+    if (cells.length < 7) {
+      continue;
+    }
+    rows.push({
+      stage: cells[0],
+      workerProfile: cells[1],
+      executionMode: cells[2],
+      status: cells[3],
+      gate: cells[4],
+      outputs: parseArtifactList(cells[5]),
+      notes: cells[6]
+    });
+  }
+
+  return { currentStage, lastUpdated, resumeInstructions, rows };
+}
+
+function markdownSection(markdown, heading) {
+  const pattern = new RegExp(`^## ${escapeRegExp(heading)}\\s*$`, "m");
+  const match = markdown.match(pattern);
+  if (!match) {
+    return "";
+  }
+  const start = match.index + match[0].length;
+  const nextHeading = markdown.slice(start).match(/^## /m);
+  const end = nextHeading ? start + nextHeading.index : markdown.length;
+  return markdown.slice(start, end);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function parseArtifactList(value) {
+  if (!value || ["-", "none", "n/a"].includes(value.trim().toLowerCase())) {
+    return [];
+  }
+  return value
+    .split(/,\s*/)
+    .map((entry) => entry.replace(/[`*]/g, "").trim())
+    .map((entry) => entry.match(/[A-Za-z0-9._/-]+\.(?:json|md)$/)?.[0] ?? entry)
+    .filter((entry) => /^[A-Za-z0-9._/-]+\.(?:json|md)$/.test(entry));
+}
+
+function hasGateArtifact(row) {
+  return row.outputs.some((artifact) => artifact.endsWith("-gate.json") || artifact.endsWith("quality-report.json"));
+}
+
+function hasGateStatus(row) {
+  return gateStatuses.has(row.gate.toLowerCase());
+}
+
+function summaryArtifactNames(summary) {
+  const names = [];
+  for (const key of ["artifacts", "keyArtifacts", "artifactPaths"]) {
+    const value = summary?.[key];
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    for (const item of value) {
+      if (typeof item === "string") {
+        names.push(item);
+      } else if (item && typeof item === "object") {
+        names.push(item.path ?? item.file ?? item.filename ?? item.name);
+      }
+    }
+  }
+  return new Set(names.filter(Boolean).map((name) => name.replace(/^.*\//, "")));
+}
+
+function summaryStageRows(summary) {
+  if (Array.isArray(summary?.stageSummary)) {
+    return summary.stageSummary;
+  }
+  if (Array.isArray(summary?.stages)) {
+    return summary.stages;
+  }
+  return [];
+}
+
+async function progressLastUpdatedCheck(parsedProgress, now) {
+  const value = parsedProgress.lastUpdated;
+  if (!value) {
+    return check("progress-last-updated", "error", "PROGRESS.md is missing Last updated.");
+  }
+
+  const timestamp = new Date(value);
+  if (Number.isNaN(timestamp.getTime())) {
+    return check("progress-last-updated", "error", `PROGRESS.md Last updated is not parseable: ${value}`);
+  }
+
+  const maxFutureSkewMs = 60_000;
+  if (timestamp.getTime() > now.getTime() + maxFutureSkewMs) {
+    return check(
+      "progress-last-updated",
+      "error",
+      `PROGRESS.md Last updated ${value} is later than audit time ${now.toISOString()}.`
+    );
+  }
+
+  return check("progress-last-updated", "ok", `Last updated ${value} is not in the future.`);
+}
+
+async function progressOutputArtifactsCheck(runDir, parsedProgress) {
+  const missing = [];
+  for (const row of parsedProgress.rows) {
+    for (const output of row.outputs) {
+      if (!existsSync(join(runDir, output))) {
+        missing.push(`${row.stage}: ${output}`);
+      }
+    }
+  }
+
+  if (missing.length) {
+    return check("progress-output-artifacts", "error", `Missing output artifacts: ${missing.join(", ")}`);
+  }
+  return check("progress-output-artifacts", "ok", "All PROGRESS.md output artifacts exist.");
+}
+
+async function progressGateArtifactsCheck(runDir, parsedProgress) {
+  const missing = [];
+  const omitted = [];
+
+  for (const row of parsedProgress.rows.filter(hasGateStatus)) {
+    const expectedArtifact = expectedGateArtifacts.get(row.stage);
+    if (!expectedArtifact) {
+      continue;
+    }
+    if (!row.outputs.includes(expectedArtifact)) {
+      omitted.push(`${row.stage}: ${expectedArtifact}`);
+    }
+    if (!existsSync(join(runDir, expectedArtifact))) {
+      missing.push(`${row.stage}: ${expectedArtifact}`);
+    }
+  }
+
+  if (missing.length || omitted.length) {
+    const details = [];
+    if (missing.length) {
+      details.push(`Missing gate artifacts: ${missing.join(", ")}`);
+    }
+    if (omitted.length) {
+      details.push(`PROGRESS.md omits gate artifacts: ${omitted.join(", ")}`);
+    }
+    return check("progress-gate-artifacts", "error", details.join("; "));
+  }
+  return check("progress-gate-artifacts", "ok", "Expected Lead-authored gate artifacts exist and are listed in PROGRESS.md.");
+}
+
+async function workerRunningWaitStateCheck(runDir, parsedProgress) {
+  const currentRow = parsedProgress.rows.find((row) => (
+    row.stage === parsedProgress.currentStage && row.status.toLowerCase() === "in-progress"
+  ));
+
+  if (!currentRow) {
+    return check("worker-running-wait-state", "ok", "No current in-progress worker row is active.");
+  }
+
+  const launchEnvelope = currentRow.outputs.find((output) => output.endsWith("control/launch-envelope.json"));
+  if (!launchEnvelope) {
+    if (currentRow.executionMode === "worker-running") {
+      return check("worker-running-wait-state", "error", "Current worker-running row is missing a launch envelope.");
+    }
+    return check("worker-running-wait-state", "ok", "Current in-progress row does not advertise a launch envelope.");
+  }
+
+  if (!existsSync(join(runDir, launchEnvelope))) {
+    return check("worker-running-wait-state", "error", `Current worker launch envelope is missing: ${launchEnvelope}`);
+  }
+
+  const resume = parsedProgress.resumeInstructions;
+  const hasActiveWorker = /Active worker:\s*\S+/i.test(resume);
+  const waitsForNotification = /subagent_notification/i.test(resume);
+  const respawnsSameWorker = new RegExp(`spawn\\s+${escapeRegExp(currentRow.workerProfile)}\\b`, "i").test(resume);
+
+  if (currentRow.executionMode !== "worker-running") {
+    return check(
+      "worker-running-wait-state",
+      "error",
+      `Current stage has launch envelope ${launchEnvelope} but execution mode is ${currentRow.executionMode}, not worker-running.`
+    );
+  }
+  if (!hasActiveWorker || !waitsForNotification || respawnsSameWorker) {
+    const failures = [];
+    if (!hasActiveWorker) {
+      failures.push("missing Active worker resume field");
+    }
+    if (!waitsForNotification) {
+      failures.push("resume instructions do not wait for subagent_notification or worker handoff");
+    }
+    if (respawnsSameWorker) {
+      failures.push("resume instructions tell Lead to spawn the same worker again");
+    }
+    return check("worker-running-wait-state", "error", failures.join("; "));
+  }
+
+  return check("worker-running-wait-state", "ok", `Waiting for active worker handoff from ${currentRow.workerProfile}.`);
+}
+
+async function gateArtifactStatusCheck(runDir, parsedProgress) {
+  const mismatches = [];
+
+  for (const row of parsedProgress.rows) {
+    const gateArtifacts = row.outputs.filter((artifact) => artifact.endsWith("-gate.json"));
+    for (const artifact of gateArtifacts) {
+      const gate = await readJsonIfExists(join(runDir, artifact));
+      const gateStatus = gate?.qualityGate?.status;
+      if (gateStatus && row.gate && !["-", "n/a"].includes(row.gate.toLowerCase()) && gateStatus !== row.gate) {
+        mismatches.push(`${artifact}: PROGRESS gate=${row.gate}, artifact status=${gateStatus}`);
+      }
+    }
+  }
+
+  if (mismatches.length) {
+    return check("gate-artifact-status", "error", `Gate status mismatches: ${mismatches.join(", ")}`);
+  }
+  return check("gate-artifact-status", "ok", "Gate artifact statuses agree with PROGRESS.md.");
+}
+
+function blockedGateUserActionErrors(artifact, qualityGate) {
+  const errors = [];
+  if (qualityGate.userActionRequired !== true) {
+    errors.push("userActionRequired must be true");
+  }
+  for (const field of ["blockers", "missingInputs", "questionsForUser", "actionsForUser"]) {
+    if (!Array.isArray(qualityGate[field])) {
+      errors.push(`${field} must be an array`);
+      continue;
+    }
+    for (const [index, item] of qualityGate[field].entries()) {
+      if (typeof item !== "string" || item.trim() === "") {
+        errors.push(`${field}[${index}] must be a non-empty string`);
+      }
+    }
+  }
+  const questionCount = nonEmptyStringCount(qualityGate.questionsForUser);
+  const actionCount = nonEmptyStringCount(qualityGate.actionsForUser);
+  if (questionCount + actionCount === 0) {
+    errors.push("questionsForUser or actionsForUser must be non-empty");
+  }
+  for (const field of ["resumeCondition", "resumeStage"]) {
+    if (!qualityGate[field] || typeof qualityGate[field] !== "string") {
+      errors.push(`${field} must be a non-empty string`);
+    }
+  }
+  return errors.length ? `${artifact}: ${errors.join(", ")}` : "";
+}
+
+function nonEmptyStringCount(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim() !== "").length : 0;
+}
+
+function isGateArtifact(artifact) {
+  return artifact.endsWith("-gate.json") || artifact.endsWith("quality-report.json");
+}
+
+async function blockedGateUserActionCheck(runDir, parsedProgress) {
+  const failures = [];
+  for (const row of parsedProgress.rows) {
+    for (const artifact of row.outputs.filter(isGateArtifact)) {
+      const value = await readJsonIfExists(join(runDir, artifact));
+      const qualityGate = value?.qualityGate;
+      if (qualityGate?.status !== "blocked") {
+        continue;
+      }
+      const error = blockedGateUserActionErrors(artifact, qualityGate);
+      if (error) {
+        failures.push(error);
+      }
+    }
+  }
+
+  if (failures.length) {
+    return check("blocked-gate-user-action", "error", `Blocked gate user-action fields are invalid: ${failures.join("; ")}`);
+  }
+  return check("blocked-gate-user-action", "ok", "Blocked gate artifacts include user-action fields when required.");
+}
+
+async function runSummaryStageGatesCheck(runDir, parsedProgress) {
+  const summary = await readJsonIfExists(join(runDir, "run-summary.json"));
+  if (!summary) {
+    return check("run-summary-stage-gates", "ok", "run-summary.json is absent.");
+  }
+
+  const summaryRows = summaryStageRows(summary);
+  const mismatches = [];
+  for (const row of parsedProgress.rows.filter(hasGateArtifact)) {
+    const summaryRow = summaryRows.find((candidate) => candidate.stage === row.stage || candidate.name === row.stage);
+    const summaryGate = summaryRow?.gate ?? summaryRow?.qualityGate?.status;
+    if (summaryGate && summaryGate !== row.gate) {
+      mismatches.push(`${row.stage}: PROGRESS gate=${row.gate}, summary gate=${summaryGate}`);
+    }
+  }
+
+  if (mismatches.length) {
+    return check("run-summary-stage-gates", "error", `Run summary gate mismatches: ${mismatches.join(", ")}`);
+  }
+  return check("run-summary-stage-gates", "ok", "Run summary stage gates do not contradict PROGRESS.md.");
+}
+
+async function runSummaryArtifactsCheck(runDir, parsedProgress) {
+  const summary = await readJsonIfExists(join(runDir, "run-summary.json"));
+  if (!summary) {
+    return check("run-summary-artifacts", "ok", "run-summary.json is absent.");
+  }
+
+  const summaryArtifacts = summaryArtifactNames(summary);
+  if (summaryArtifacts.size === 0) {
+    return check("run-summary-artifacts", "ok", "run-summary.json does not expose an artifact list.");
+  }
+
+  const expected = parsedProgress.rows.flatMap((row) => row.outputs).filter((artifact) => existsSync(join(runDir, artifact)));
+  const missing = expected.filter((artifact) => !summaryArtifacts.has(artifact.replace(/^.*\//, "")));
+
+  if (missing.length) {
+    return check("run-summary-artifacts", "error", `run-summary.json omits artifacts present in PROGRESS.md: ${missing.join(", ")}`);
+  }
+  return check("run-summary-artifacts", "ok", "run-summary.json artifact list matches PROGRESS.md outputs.");
+}
+
+async function runSummaryMarkdownCheck(runDir) {
+  const markdown = await readTextIfExists(join(runDir, "run-summary.md"));
+  if (markdown === null) {
+    return check("run-summary-markdown", "ok", "run-summary.md is absent.");
+  }
+
+  const launchGateExists = existsSync(join(runDir, "launch-readiness-gate.json"));
+  const staleGateClaim = /no gate artifact was written|not-written-by-worker/i.test(markdown);
+  if (launchGateExists && staleGateClaim) {
+    return check("run-summary-markdown", "error", "run-summary.md claims no gate was written although launch-readiness-gate.json exists.");
+  }
+  if (launchGateExists && !/launch-readiness-gate\.json/.test(markdown)) {
+    return check("run-summary-markdown", "error", "run-summary.md omits launch-readiness-gate.json.");
+  }
+
+  return check("run-summary-markdown", "ok", "run-summary.md does not contain stale gate claims.");
+}
+
+export async function auditRunState({ runDir, now = new Date() } = {}) {
+  if (!runDir) {
+    throw new Error("--run-dir is required");
+  }
+  const progressPath = join(runDir, "PROGRESS.md");
+  const progress = await readTextIfExists(progressPath);
+  if (progress === null) {
+    return {
+      result: "error",
+      runDir,
+      checks: [check("progress-exists", "error", "PROGRESS.md is required.")]
+    };
+  }
+
+  const parsedProgress = parseProgress(progress);
+  const checks = [
+    check("progress-exists", "ok", "PROGRESS.md exists."),
+    await progressLastUpdatedCheck(parsedProgress, now),
+    await progressOutputArtifactsCheck(runDir, parsedProgress),
+    await progressGateArtifactsCheck(runDir, parsedProgress),
+    await workerRunningWaitStateCheck(runDir, parsedProgress),
+    await gateArtifactStatusCheck(runDir, parsedProgress),
+    await blockedGateUserActionCheck(runDir, parsedProgress),
+    await runSummaryStageGatesCheck(runDir, parsedProgress),
+    await runSummaryArtifactsCheck(runDir, parsedProgress),
+    await runSummaryMarkdownCheck(runDir)
+  ];
+
+  return {
+    result: checks.every(isPass) ? "ok" : "error",
+    runDir,
+    checks
+  };
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    const result = await auditRunState(options);
+    console.log(JSON.stringify(result, null, 2));
+    if (result.result !== "ok") {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/execute-shopify-operation.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { executeShopifyOperation } from "../lib/internal/shopify-operation-adapter.mjs";
+
+export function parseShopifyOperationArgs(argv) {
+  const options = { validateOnly: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--input") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) throw new Error("--input requires a value");
+      options.inputPath = value;
+      index += 1;
+    } else if (arg === "--run-dir") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) throw new Error("--run-dir requires a value");
+      options.runDir = value;
+      index += 1;
+    } else if (arg === "--validate-only") {
+      options.validateOnly = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function hasRelativeSafePath(value) {
+  if (!isNonEmptyString(value) || isAbsolute(value)) return false;
+  const normalized = normalize(value);
+  return normalized !== "." && !normalized.startsWith("..");
+}
+
+const allowedRequestFields = new Set([
+  "schemaVersion",
+  "runDir",
+  "stageId",
+  "attemptId",
+  "launchEnvelopePath",
+  "envelope",
+  "actionId",
+  "launchEnvelopeSha256",
+  "grantedScopes",
+  "approvalGrantPath",
+  "operationKey",
+  "targetStore",
+  "apiVersion",
+  "requestFingerprint",
+  "naturalResourceKey",
+  "providerIdempotencySupported",
+  "resourceType",
+  "executorInput"
+]);
+
+const allowedExecutorFieldsByKind = {
+  "admin-graphql": new Set(["kind", "operationName", "query", "variables"]),
+  "theme-push-unpublished": new Set(["kind", "themeWorkspace", "themeId", "themeName", "nodelete"])
+};
+
+export function validateShopifyOperationRequest(request) {
+  const errors = [];
+  if (!request || typeof request !== "object") {
+    return { ok: false, errors: ["Request must be an object"] };
+  }
+  for (const field of Object.keys(request)) {
+    if (!allowedRequestFields.has(field)) errors.push(`Unsupported request field: ${field}`);
+  }
+  if (request.schemaVersion !== "1.0.0") errors.push("schemaVersion must be 1.0.0");
+  if (Object.hasOwn(request, "actionRegistry")) errors.push("actionRegistry override is forbidden");
+  if (!request.envelope && !request.launchEnvelopePath) errors.push("Request must include launchEnvelopePath or envelope");
+  if (request.launchEnvelopePath && !hasRelativeSafePath(request.launchEnvelopePath)) {
+    errors.push("launchEnvelopePath must be a relative path inside runDir");
+  }
+
+  for (const field of [
+    "runDir",
+    "stageId",
+    "attemptId",
+    "actionId",
+    "launchEnvelopeSha256",
+    "operationKey",
+    "targetStore",
+    "apiVersion",
+    "requestFingerprint",
+    "naturalResourceKey",
+    "resourceType"
+  ]) {
+    if (!isNonEmptyString(request[field])) errors.push(`${field} is required`);
+  }
+  if (!Array.isArray(request.grantedScopes)) errors.push("grantedScopes must be an array");
+  if (typeof request.providerIdempotencySupported !== "boolean") {
+    errors.push("providerIdempotencySupported must be boolean");
+  }
+
+  const executorInput = request.executorInput;
+  if (!executorInput || typeof executorInput !== "object") {
+    errors.push("executorInput is required");
+  } else if (executorInput.kind === "admin-graphql") {
+    for (const field of Object.keys(executorInput)) {
+      if (!allowedExecutorFieldsByKind["admin-graphql"].has(field)) errors.push(`Unsupported executorInput field: ${field}`);
+    }
+    if (!isNonEmptyString(executorInput.operationName)) errors.push("executorInput.operationName is required");
+    if (!isNonEmptyString(executorInput.query)) errors.push("executorInput.query is required");
+    if (
+      executorInput.variables !== undefined
+      && (executorInput.variables === null || typeof executorInput.variables !== "object" || Array.isArray(executorInput.variables))
+    ) {
+      errors.push("executorInput.variables must be an object when provided");
+    }
+  } else if (executorInput.kind === "theme-push-unpublished") {
+    for (const field of Object.keys(executorInput)) {
+      if (!allowedExecutorFieldsByKind["theme-push-unpublished"].has(field)) errors.push(`Unsupported executorInput field: ${field}`);
+    }
+    if (!isNonEmptyString(executorInput.themeWorkspace)) errors.push("executorInput.themeWorkspace is required");
+  } else {
+    errors.push("executorInput.kind must be admin-graphql or theme-push-unpublished");
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export async function validateShopifyOperationRequestFile({ inputPath, runDir }) {
+  if (!inputPath) {
+    throw new Error("Missing --input Shopify operation request JSON");
+  }
+  const request = await readJson(inputPath);
+  const resolvedRunDir = runDir ?? request.runDir;
+  return validateShopifyOperationRequest({ ...request, runDir: resolvedRunDir });
+}
+
+export async function executeShopifyOperationRequest({
+  packageRoot = join(import.meta.dirname, ".."),
+  inputPath,
+  runDir,
+  runCommand
+}) {
+  if (!inputPath) {
+    throw new Error("Missing --input Shopify operation request JSON");
+  }
+  const request = await readJson(inputPath);
+  const resolvedRunDir = runDir ?? request.runDir;
+  const requestForValidation = { ...request, runDir: resolvedRunDir };
+  const validation = validateShopifyOperationRequest(requestForValidation);
+  if (!validation.ok) {
+    throw new Error(validation.errors.join("\n"));
+  }
+  const actionRegistry = await readJson(join(packageRoot, "contracts", "action-registry.json"));
+  const envelope = request.envelope
+    ?? await readJson(join(resolvedRunDir, request.launchEnvelopePath));
+
+  return executeShopifyOperation({
+    ...request,
+    runDir: resolvedRunDir,
+    actionRegistry,
+    envelope,
+    runCommand
+  });
+}
+
+async function main() {
+  try {
+    const options = parseShopifyOperationArgs(process.argv.slice(2));
+    if (options.validateOnly) {
+      const validation = await validateShopifyOperationRequestFile(options);
+      console.log(JSON.stringify(validation, null, 2));
+      if (!validation.ok) process.exitCode = 1;
+      return;
+    }
+    const result = await executeShopifyOperationRequest(options);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}