@storewright/cli 0.14.0

package/lib/internal/shopify-operation-adapter.mjs

@@ -0,0 +1,456 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import {
+  prepareExternalOperation,
+  transitionExternalOperation
+} from "./operation-ledger.mjs";
+
+const allowedGraphqlOperationsByAction = {
+  "shopify.products.upsert": ["productCreate", "productSet", "productUpdate", "productVariantsBulkUpdate"],
+  "shopify.products.publishToOnlineStore": ["publishablePublish"],
+  "shopify.collections.upsert": ["collectionCreate", "collectionUpdate"],
+  "shopify.collections.attachProducts": ["productUpdate"],
+  "shopify.collections.publishToOnlineStore": ["publishablePublish"],
+  "shopify.content.upsertPages": ["pageCreate", "pageUpdate"],
+  "shopify.navigation.upsertPreviewMenu": ["menuCreate", "menuUpdate"]
+};
+
+const expectedExecutorToolByAction = {
+  "shopify.products.upsert": "catalog_upsert",
+  "shopify.products.publishToOnlineStore": "publishable_publish",
+  "shopify.collections.upsert": "collection_upsert",
+  "shopify.collections.attachProducts": "collection_attach_products",
+  "shopify.collections.publishToOnlineStore": "publishable_publish",
+  "shopify.content.upsertPages": "content_upsert_pages",
+  "shopify.navigation.upsertPreviewMenu": "navigation_upsert_preview_menu",
+  "shopify.theme.pushUnpublished": "theme_push_unpublished"
+};
+
+const expectedExecutorServer = "storewright-operations";
+
+function defaultRunCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: options.cwd });
+    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;
+      process.stdout.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      process.stderr.write(chunk);
+    });
+    child.on("error", (error) => {
+      finish({
+        exitCode: 1,
+        stdout,
+        stderr: stderr || error.message,
+        timedOut
+      });
+    });
+    child.on("close", (exitCode, signal) => {
+      finish({
+        exitCode: exitCode ?? 1,
+        stdout,
+        stderr,
+        timedOut: timedOut || signal === "SIGTERM"
+      });
+    });
+  });
+}
+
+function summarize(text) {
+  return String(text ?? "").replace(/\s+/g, " ").trim().slice(0, 500);
+}
+
+function parseJson(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 parsedFacts({ executorInput, result }) {
+  const facts = [];
+  const json = parseJson(result.stdout);
+  if (executorInput.kind === "admin-graphql") {
+    const summary = graphqlPayloadSummary({ json, operationName: executorInput.operationName });
+    if (summary.payloadCount === 1) {
+      facts.push(`${executorInput.operationName}:payload-present`);
+    } else if (summary.payloadCount > 1) {
+      facts.push(`${executorInput.operationName}:payloadCount=${summary.payloadCount}`);
+    }
+    if (summary.payloadCount > 0) facts.push(`${executorInput.operationName}:userErrors=${summary.userErrorCount}`);
+    if (summary.topLevelErrorCount > 0) facts.push(`topLevelErrors=${summary.topLevelErrorCount}`);
+  }
+  if (executorInput.kind === "theme-push-unpublished") {
+    const theme = json?.theme ?? json;
+    if (theme?.id) facts.push(`themeId=${theme.id}`);
+    if (theme?.name) facts.push(`themeName=${theme.name}`);
+    if (themeHasWarning(theme)) facts.push(`themeWarning=${summarize(theme.warning)}`);
+    const errorCount = countThemeErrors(theme?.errors);
+    if (errorCount > 0) facts.push(`themeErrorCount=${errorCount}`);
+  }
+  return facts;
+}
+
+function themeHasWarning(theme) {
+  return typeof theme?.warning === "string" && theme.warning.trim().length > 0;
+}
+
+function countThemeErrors(errors) {
+  if (!errors) return 0;
+  if (Array.isArray(errors)) return errors.length;
+  if (typeof errors === "string") return errors.trim().length > 0 ? 1 : 0;
+  if (typeof errors !== "object") return 0;
+  return Object.values(errors).reduce((count, value) => {
+    if (Array.isArray(value)) return count + value.length;
+    if (typeof value === "string" && value.trim().length > 0) return count + 1;
+    if (value && typeof value === "object") return count + countThemeErrors(value);
+    return count;
+  }, 0);
+}
+
+function candidatePayloadEntries(json, operationName) {
+  const root = json?.data ?? json;
+  if (!root || typeof root !== "object" || Array.isArray(root)) return [];
+  const direct = root[operationName];
+  if (direct && typeof direct === "object") return [[operationName, direct]];
+  return Object.entries(root).filter(([, value]) => (
+    value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && Array.isArray(value.userErrors)
+  ));
+}
+
+function graphqlPayloadSummary({ json, operationName }) {
+  const payloadEntries = candidatePayloadEntries(json, operationName);
+  let userErrorCount = 0;
+  for (const [, payload] of payloadEntries) {
+    if (Array.isArray(payload.userErrors)) userErrorCount += payload.userErrors.length;
+  }
+  return {
+    payloadCount: payloadEntries.length,
+    userErrorCount,
+    topLevelErrorCount: Array.isArray(json?.errors) ? json.errors.length : 0
+  };
+}
+
+function hasGraphqlErrors({ executorInput, result }) {
+  if (executorInput.kind !== "admin-graphql") return false;
+  const json = parseJson(result.stdout);
+  const summary = graphqlPayloadSummary({ json, operationName: executorInput.operationName });
+  return summary.userErrorCount > 0 || summary.topLevelErrorCount > 0;
+}
+
+function hasThemePushIssues({ executorInput, result }) {
+  if (executorInput.kind !== "theme-push-unpublished") return false;
+  const json = parseJson(result.stdout);
+  const theme = json?.theme ?? json;
+  return themeHasWarning(theme) || countThemeErrors(theme?.errors) > 0;
+}
+
+function externalOperationStatus({ executorInput, result }) {
+  if (result.exitCode !== 0 || result.timedOut) return "failed";
+  if (hasGraphqlErrors({ executorInput, result })) return "failed";
+  if (hasThemePushIssues({ executorInput, result })) return "indeterminate";
+  return "succeeded";
+}
+
+function commandResultFromStatus(status) {
+  if (status === "succeeded") return "ok";
+  if (status === "indeterminate") return "indeterminate";
+  return "error";
+}
+
+function assertAllowedGraphqlOperation(actionId, executorInput) {
+  const allowed = allowedGraphqlOperationsByAction[actionId];
+  if (!allowed) {
+    throw new Error(`${actionId} does not support admin-graphql execution`);
+  }
+  if (!allowed.includes(executorInput.operationName)) {
+    throw new Error(`${executorInput.operationName} is not allowed for ${actionId}`);
+  }
+  if (!executorInput.query || typeof executorInput.query !== "string") {
+    throw new Error("executorInput.query is required for admin-graphql execution");
+  }
+}
+
+function assertValidExecutorInput(actionId, executorInput) {
+  if (!executorInput || typeof executorInput !== "object") {
+    throw new Error("executorInput is required");
+  }
+  if (executorInput.kind === "admin-graphql") {
+    assertAllowedGraphqlOperation(actionId, executorInput);
+    return;
+  }
+  if (executorInput.kind === "theme-push-unpublished") {
+    if (actionId !== "shopify.theme.pushUnpublished") {
+      throw new Error(`${executorInput.kind} is not allowed for ${actionId}`);
+    }
+    if (!executorInput.themeWorkspace) {
+      throw new Error("executorInput.themeWorkspace is required for theme push");
+    }
+    return;
+  }
+  throw new Error(`Unsupported executorInput.kind: ${executorInput.kind}`);
+}
+
+function assertExecutorMatchesRegistry({ actionRegistry, actionId }) {
+  const action = actionRegistry.actions?.[actionId];
+  if (!action) {
+    throw new Error(`Unknown action: ${actionId}`);
+  }
+  const expectedTool = expectedExecutorToolByAction[actionId];
+  if (!expectedTool) {
+    throw new Error(`${actionId} does not have a supported Shopify operation executor`);
+  }
+  if (action.executor?.server !== expectedExecutorServer) {
+    throw new Error(`${actionId} executor server must be ${expectedExecutorServer}`);
+  }
+  if (action.executor?.tool !== expectedTool) {
+    throw new Error(`${actionId} executor tool must be ${expectedTool}`);
+  }
+}
+
+function operationIdFromKey(operationKey) {
+  return createHash("sha256").update(operationKey).digest("hex").slice(0, 20);
+}
+
+async function writeGraphqlInputFiles({ runDir, stageId, attemptId, operationKey, executorInput }) {
+  const operationId = operationIdFromKey(operationKey);
+  const inputDir = join(runDir, "stages", stageId, "attempts", attemptId, "work", "operation-inputs");
+  const queryPath = join(inputDir, `${operationId}-query.graphql`);
+  const variablesPath = join(inputDir, `${operationId}-variables.json`);
+  await mkdir(inputDir, { recursive: true });
+  await writeFile(queryPath, `${executorInput.query}\n`);
+  await writeFile(variablesPath, `${JSON.stringify(executorInput.variables ?? {}, null, 2)}\n`);
+  return { queryPath, variablesPath };
+}
+
+async function commandForExecutor({ runDir, stageId, attemptId, operationKey, actionId, targetStore, apiVersion, executorInput }) {
+  assertValidExecutorInput(actionId, executorInput);
+  if (executorInput.kind === "admin-graphql") {
+    const inputFiles = await writeGraphqlInputFiles({ runDir, stageId, attemptId, operationKey, executorInput });
+    return {
+      command: "shopify",
+      args: [
+        "store",
+        "execute",
+        "--store",
+        targetStore,
+        "--allow-mutations",
+        "--json",
+        "--version",
+        apiVersion,
+        "--query-file",
+        inputFiles.queryPath,
+        "--variable-file",
+        inputFiles.variablesPath
+      ]
+    };
+  }
+
+  const args = [
+    "theme",
+    "push",
+    "--store",
+    targetStore,
+    "--unpublished",
+    "--json",
+    "--path",
+    executorInput.themeWorkspace
+  ];
+  if (executorInput.themeId || executorInput.themeName) {
+    args.push("--theme", String(executorInput.themeId ?? executorInput.themeName));
+  }
+  if (executorInput.nodelete) {
+    args.push("--nodelete");
+  }
+  return { command: "shopify", args };
+}
+
+async function writeRawOutput({ runDir, stageId, attemptId, operationId, command, args, result, parsedFacts: facts }) {
+  const rawOutputPath = `stages/${stageId}/attempts/${attemptId}/work/raw-external-operations/${operationId}-dispatch.json`;
+  const absolutePath = join(runDir, rawOutputPath);
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, `${JSON.stringify({
+    schemaVersion: "1.0.0",
+    command,
+    args,
+    exitCode: result.exitCode ?? 1,
+    timedOut: Boolean(result.timedOut),
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    parsedFacts: facts
+  }, null, 2)}\n`);
+  return rawOutputPath;
+}
+
+export async function executeShopifyOperation({
+  runDir,
+  stageId,
+  attemptId,
+  envelope,
+  actionRegistry,
+  actionId,
+  launchEnvelopeSha256,
+  grantedScopes = [],
+  approvalGrantPath = null,
+  operationKey,
+  targetStore,
+  apiVersion,
+  requestFingerprint,
+  naturalResourceKey,
+  providerIdempotencySupported = false,
+  resourceType,
+  executorInput,
+  runCommand = defaultRunCommand,
+  cwd = process.cwd(),
+  timeoutMs
+}) {
+  assertExecutorMatchesRegistry({ actionRegistry, actionId });
+  const commandPlan = await commandForExecutor({
+    runDir,
+    stageId,
+    attemptId,
+    operationKey,
+    actionId,
+    targetStore,
+    apiVersion,
+    executorInput
+  });
+  const prepared = await prepareExternalOperation({
+    runDir,
+    stageId,
+    attemptId,
+    envelope,
+    actionRegistry,
+    actionId,
+    launchEnvelopeSha256,
+    grantedScopes,
+    approvalGrantPath,
+    operationKey,
+    targetStore,
+    apiVersion,
+    requestFingerprint,
+    naturalResourceKey,
+    providerIdempotencySupported,
+    resourceType
+  });
+
+  await transitionExternalOperation({
+    runDir,
+    stageId,
+    attemptId,
+    operationId: prepared.operation.operationId,
+    status: "dispatched",
+    patch: {
+      actionId,
+      command: [commandPlan.command, ...commandPlan.args].join(" ")
+    }
+  });
+
+  const commandResult = await runCommand(commandPlan.command, commandPlan.args, { cwd, timeoutMs });
+  const facts = parsedFacts({ executorInput, result: commandResult });
+  const rawOutputPath = await writeRawOutput({
+    runDir,
+    stageId,
+    attemptId,
+    operationId: prepared.operation.operationId,
+    command: commandPlan.command,
+    args: commandPlan.args,
+    result: commandResult,
+    parsedFacts: facts
+  });
+  const status = externalOperationStatus({ executorInput, result: commandResult });
+
+  await transitionExternalOperation({
+    runDir,
+    stageId,
+    attemptId,
+    operationId: prepared.operation.operationId,
+    status,
+    patch: {
+      actionId,
+      rawOutputPath,
+      exitCode: commandResult.exitCode ?? 1,
+      stdoutSummary: summarize(commandResult.stdout),
+      stderrSummary: summarize(commandResult.stderr),
+      parsedFacts: facts
+    }
+  });
+
+  return {
+    status,
+    operationId: prepared.operation.operationId,
+    rawOutputPath,
+    commandAttempt: {
+      command: [commandPlan.command, ...commandPlan.args].join(" "),
+      exitCode: commandResult.exitCode ?? 1,
+      commandResult: commandResultFromStatus(status),
+      stdoutSummary: summarize(commandResult.stdout),
+      stderrSummary: summarize(commandResult.stderr),
+      parsedFacts: facts,
+      rawOutputPath
+    }
+  };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@storewright/cli",
+  "version": "0.14.0",
+  "description": "Storewright CLI bootstrap and deterministic helper commands.",
+  "type": "module",
+  "bin": {
+    "storewright": "bin/storewright.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/audit-run-state.mjs",
+    "scripts/execute-shopify-operation.mjs",
+    "scripts/generate-image-assets-openai.mjs",
+    "scripts/generate-media-assets.mjs",
+    "scripts/init-run-state.mjs",
+    "scripts/inspect-media-files.mjs",
+    "scripts/prepare-launch-envelope.mjs",
+    "scripts/shopify-access-preflight.mjs",
+    "scripts/upload-shopify-media.mjs",
+    "scripts/validate-agent-report.mjs",
+    "scripts/validate-artifact.mjs",
+    "scripts/validate-launch-envelope.mjs",
+    "scripts/validate-registries.mjs",
+    "scripts/validate-workflow-manifest.mjs",
+    "scripts/version.mjs",
+    "contracts/",
+    "schemas/",
+    "VERSION",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "playwright-core": "1.56.0"
+  }
+}

package/schemas/action-registry.schema.json

@@ -0,0 +1,11 @@
+{
+  "type": "object",
+  "required": ["schemaVersion", "actions"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "actions": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/agent-report.schema.json

@@ -0,0 +1,14 @@
+{
+  "type": "object",
+  "required": ["schemaVersion", "launchEnvelopeSha256", "inputArtifacts", "effectiveAllowedActions", "outputArtifacts"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "launchEnvelopeSha256": { "type": "string", "minLength": 1 },
+    "inputArtifacts": { "type": "array" },
+    "effectiveAllowedActions": { "type": "array" },
+    "outputArtifacts": { "type": "array" },
+    "observedRuntime": { "type": "object" },
+    "blocked_questions": { "type": "array" }
+  },
+  "additionalProperties": true
+}

package/schemas/approval-grant.schema.json

@@ -0,0 +1,16 @@
+{
+  "type": "object",
+  "required": ["schemaVersion", "approvalId", "runId", "actionId", "impactClass", "approvalRequirement", "approvedBy", "source", "grantedAt"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "approvalId": { "type": "string", "minLength": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "actionId": { "type": "string", "minLength": 1 },
+    "impactClass": { "enum": ["local-only", "remote-read", "remote-draft", "remote-public"] },
+    "approvalRequirement": { "enum": ["none", "workflow-gate", "explicit-user"] },
+    "approvedBy": { "type": "string", "minLength": 1 },
+    "source": { "type": "string", "minLength": 1 },
+    "grantedAt": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/schemas/base-theme-report.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/storewright/base-theme-report.schema.json",
+  "title": "Storewright Base Theme Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "baseTheme"],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "1.0.0" },
+    "runId": { "type": "string" },
+    "baseTheme": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "baseThemeDir", "created", "notes"],
+      "properties": {
+        "source": { "type": "string", "enum": ["existing", "shopify-live-theme"] },
+        "baseThemeDir": { "type": "string", "minLength": 1 },
+        "created": { "type": "boolean" },
+        "store": { "type": "string" },
+        "command": { "type": "string" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}