shopify-agentic-dev-workflow 0.1.0

package/scripts/validate-graphql.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * validate-graphql.js
+ *
+ * Runs a minimal read-only probe for every query shape used by shopify-agent
+ * against the configured live store. Catches schema drift (renamed/removed
+ * fields) before they reach users.
+ *
+ * Usage:
+ *   node scripts/validate-graphql.js           # test all queries
+ *   node scripts/validate-graphql.js products  # test only matching labels
+ *
+ * Requirements:
+ *   - shopify-agent init completed in this directory
+ *   - shopify-agent store:auth completed (Admin API token stored)
+ *   - Shopify CLI 4.x  (npm install -g @shopify/cli@latest)
+ */
+
+"use strict";
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ─── Config loading (mirrors bin/shopify-agent.js) ───────────────────────────
+
+const root = process.cwd();
+const configDir = path.join(root, ".shopify-agent");
+const profilesDir = path.join(configDir, "profiles");
+const configPath = path.join(configDir, "config.json");
+
+function loadDotEnv() {
+  const envFile = path.join(root, ".env");
+  if (!fs.existsSync(envFile)) return {};
+  const out = {};
+  fs.readFileSync(envFile, "utf8").split(/\r?\n/).forEach((line) => {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) out[m[1]] = m[2].replace(/^['"]|['"]$/g, "");
+  });
+  return out;
+}
+
+function loadActiveProfile() {
+  const activePath = path.join(configDir, "active-profile");
+  let name = "default";
+  if (fs.existsSync(activePath)) name = fs.readFileSync(activePath, "utf8").trim();
+  else if (fs.existsSync(configPath)) {
+    try { name = JSON.parse(fs.readFileSync(configPath, "utf8")).profile || "default"; } catch {}
+  }
+  const profileFile = path.join(profilesDir, `${name}.json`);
+  if (fs.existsSync(profileFile)) {
+    try { return JSON.parse(fs.readFileSync(profileFile, "utf8")); } catch {}
+  }
+  return {};
+}
+
+function loadConfig() {
+  const env = { ...loadDotEnv(), ...process.env };
+  const profile = loadActiveProfile();
+  return {
+    store: env.SHOPIFY_STORE || profile.store || "",
+    apiVersion: env.SHOPIFY_API_VERSION || profile.apiVersion || "2026-04",
+  };
+}
+
+// ─── GraphQL runner ───────────────────────────────────────────────────────────
+
+function stripAnsi(str) {
+  return (str || "").replace(/\x1B\[[0-9;]*[mGKHF]/g, "");
+}
+
+function runQuery(store, queryStr) {
+  const tmp = path.join(os.tmpdir(), `shopify-validate-${Date.now()}.graphql`);
+  fs.writeFileSync(tmp, `query { ${queryStr} }`);
+  try {
+    const result = spawnSync(
+      "shopify",
+      ["store", "execute", "--store", store, "--query-file", tmp],
+      { encoding: "utf8", env: { ...process.env, FORCE_COLOR: "0" } }
+    );
+    const raw = stripAnsi(result.stdout || "");
+    const err = stripAnsi(result.stderr || "");
+
+    if (!result.ok && (err.includes("No stored app authentication") || raw.includes("No stored app authentication"))) {
+      return { ok: false, error: "NOT_AUTHED" };
+    }
+
+    const jsonStart = raw.indexOf("{");
+    if (jsonStart === -1) return { ok: false, error: err || raw || "No JSON in response" };
+
+    const parsed = JSON.parse(raw.slice(jsonStart));
+    if (parsed.errors && parsed.errors.length) {
+      return { ok: false, error: parsed.errors.map((e) => `${e.message} (${JSON.stringify(e.extensions || {})})`).join("; ") };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  } finally {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+// ─── Query catalogue ──────────────────────────────────────────────────────────
+// Each entry: { label, query }
+// query = the inner body (without the outer `query { }` wrapper)
+// All are read-only — no mutations tested here.
+
+const PROBES = [
+  // ── Setup / store ──────────────────────────────────────────────────────────
+  {
+    label: "shop info",
+    query: `shop { name currencyCode primaryDomain { url } }`,
+  },
+  {
+    label: "store:locations",
+    query: `locations(first: 1) { edges { node { id name isActive fulfillsOnlineOrders } } }`,
+  },
+
+  // ── Products ───────────────────────────────────────────────────────────────
+  {
+    label: "products:list",
+    query: `products(first: 1) { edges { node { id title status totalInventory vendor productType } } }`,
+  },
+  {
+    label: "products:variants",
+    query: `products(first: 1) { edges { node { variants(first: 1) { edges { node {
+      id title price sku inventoryQuantity
+      inventoryItem { id }
+    } } } } } }`,
+  },
+  {
+    label: "collections:list",
+    query: `collections(first: 1) { edges { node { id title handle productsCount { count } } } }`,
+  },
+
+  // ── Inventory ──────────────────────────────────────────────────────────────
+  {
+    label: "inventory:list (locations)",
+    query: `locations(first: 5) { edges { node { id name isActive } } }`,
+  },
+
+  // ── Orders ─────────────────────────────────────────────────────────────────
+  {
+    label: "orders:list",
+    query: `orders(first: 1, query: "status:any", sortKey: CREATED_AT, reverse: true) {
+      edges { node {
+        id name createdAt
+        displayFinancialStatus displayFulfillmentStatus
+        totalPriceSet { presentmentMoney { amount currencyCode } }
+        customer { displayName email }
+      } }
+    }`,
+  },
+  {
+    label: "orders:get (detail fields)",
+    query: `orders(first: 1, query: "status:any") { edges { node {
+      id name
+      lineItems(first: 3) { edges { node {
+        title quantity originalUnitPriceSet { presentmentMoney { amount currencyCode } }
+      } } }
+      shippingAddress { name address1 city country }
+      fulfillments(first: 1) { trackingInfo { number url } }
+    } } }`,
+  },
+
+  // ── Customers ─────────────────────────────────────────────────────────────
+  {
+    label: "customers:list",
+    query: `customers(first: 1) { edges { node {
+      id displayName email phone numberOfOrders
+      totalSpentV2 { amount currencyCode }
+      defaultAddress { city country }
+    } } }`,
+  },
+
+  // ── Discounts ─────────────────────────────────────────────────────────────
+  {
+    label: "discounts:list (usageCount on DiscountCodeBasic)",
+    query: `codeDiscountNodes(first: 1) { edges { node {
+      id
+      codeDiscount {
+        ... on DiscountCodeBasic {
+          title status usageCount appliesOncePerCustomer usageLimit startsAt endsAt
+          codes(first: 1) { edges { node { code } } }
+          customerGets { value {
+            ... on DiscountPercentage { percentage }
+            ... on DiscountAmount { amount { amount currencyCode } }
+          } }
+        }
+      }
+    } } }`,
+  },
+
+  // ── Gift cards ────────────────────────────────────────────────────────────
+  {
+    label: "gift-cards:list",
+    query: `giftCards(first: 1) { edges { node {
+      id lastCharacters maskedCode enabled expiresOn
+      initialValue { amount currencyCode }
+      balance { amount currencyCode }
+    } } }`,
+  },
+
+  // ── Content ───────────────────────────────────────────────────────────────
+  {
+    label: "pages:list",
+    query: `pages(first: 1) { edges { node { id title handle isPublished updatedAt } } }`,
+  },
+  {
+    label: "blogs:list",
+    query: `blogs(first: 1) { edges { node { id title handle } } }`,
+  },
+  {
+    label: "redirects:list",
+    query: `urlRedirects(first: 1) { edges { node { id path target } } }`,
+  },
+
+  // ── Metafields ────────────────────────────────────────────────────────────
+  {
+    label: "metafields (shop level)",
+    query: `shop { metafields(first: 1) { edges { node { id namespace key value type } } } }`,
+  },
+  {
+    label: "metafields (product level)",
+    query: `products(first: 1) { edges { node { metafields(first: 1) { edges { node { id namespace key value type } } } } } }`,
+  },
+
+  // ── Dashboard composite ───────────────────────────────────────────────────
+  {
+    label: "dashboard composite query",
+    query: `
+      shop { name currencyCode }
+      orders(first: 1, query: "status:open", sortKey: CREATED_AT, reverse: true) {
+        edges { node {
+          name createdAt displayFinancialStatus displayFulfillmentStatus
+          totalPriceSet { presentmentMoney { amount currencyCode } }
+          customer { displayName }
+        } }
+      }
+      products(first: 1, query: "status:active") {
+        edges { node { id title totalInventory } }
+      }
+      codeDiscountNodes(first: 1) { edges { node { codeDiscount {
+        ... on DiscountCodeBasic { title status usageCount codes(first: 1) { edges { node { code } } } }
+      } } } }
+    `,
+  },
+];
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+const filter = process.argv[2] ? process.argv[2].toLowerCase() : null;
+const probes = filter ? PROBES.filter((p) => p.label.toLowerCase().includes(filter)) : PROBES;
+
+const cfg = loadConfig();
+
+if (!cfg.store) {
+  console.error("No store configured. Run: shopify-agent init");
+  process.exit(1);
+}
+
+console.log(`\nShopify GraphQL Schema Validator`);
+console.log(`Store:    ${cfg.store}`);
+console.log(`API:      ${cfg.apiVersion}`);
+console.log(`Probes:   ${probes.length}${filter ? ` (filtered: "${filter}")` : ""}`);
+console.log("─".repeat(60));
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+for (const probe of probes) {
+  process.stdout.write(`  ${probe.label.padEnd(48)}`);
+  const result = runQuery(cfg.store, probe.query);
+  if (result.ok) {
+    process.stdout.write("✓ PASS\n");
+    passed++;
+  } else if (result.error === "NOT_AUTHED") {
+    process.stdout.write("⚠ SKIP (run: shopify-agent store:auth)\n");
+    failed++;
+    failures.push({ label: probe.label, error: "Admin API token not found — run shopify-agent store:auth" });
+    break; // all will fail, no point continuing
+  } else {
+    process.stdout.write("✗ FAIL\n");
+    failed++;
+    failures.push({ label: probe.label, error: result.error });
+  }
+}
+
+console.log("─".repeat(60));
+console.log(`Result: ${passed} passed, ${failed} failed out of ${probes.length} probes\n`);
+
+if (failures.length) {
+  console.log("Failures:\n");
+  failures.forEach((f) => {
+    console.log(`  ✗ ${f.label}`);
+    console.log(`    ${f.error}\n`);
+  });
+  process.exit(1);
+} else {
+  console.log("All queries validated against the live schema.\n");
+}

package/templates/.env.example

@@ -0,0 +1,20 @@
+# Store domain, for example quickstart-abc123.myshopify.com
+SHOPIFY_STORE=
+
+# Theme Access password or a custom app token with read_themes/write_themes.
+SHOPIFY_CLI_THEME_TOKEN=
+
+# Optional default staging theme id or theme name.
+SHOPIFY_THEME_ID=
+
+# Optional app config name used by `shopify app ... --config`.
+SHOPIFY_APP_CONFIG=
+
+# Optional app client id used by Shopify CLI app commands.
+SHOPIFY_APP_CLIENT_ID=
+
+# Scopes used by Shopify CLI 4.x `shopify store auth`.
+SHOPIFY_STORE_SCOPES=read_products,write_products,read_orders,write_orders,read_inventory,write_inventory,read_customers,write_customers,read_discounts,write_discounts,read_price_rules,write_price_rules,read_content,write_content,read_online_store_navigation,write_online_store_navigation,read_gift_cards,write_gift_cards,read_locations,read_metaobjects,write_metaobjects,read_metaobject_definitions
+
+# Optional API version for Admin GraphQL.
+SHOPIFY_API_VERSION=2026-04

package/templates/codex-config.toml

@@ -0,0 +1,3 @@
+[mcp_servers.shopify-dev-mcp]
+command = "npx"
+args = ["-y", "@shopify/dev-mcp@latest"]

package/templates/github-actions/deploy-theme.yml

@@ -0,0 +1,32 @@
+name: Theme deploy
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Shopify CLI
+        run: npm install -g @shopify/cli@latest
+
+      - name: Theme Check
+        run: shopify theme check
+
+      - name: Push staging theme
+        run: |
+          shopify theme push \
+            --json \
+            --store "${{ secrets.SHOPIFY_FLAG_STORE }}" \
+            --theme "${{ secrets.SHOPIFY_STAGING_THEME_ID }}" \
+            --password "${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}"
+

package/templates/graphql/content/pages-list.graphql

@@ -0,0 +1,12 @@
+query PagesList {
+  pages(first: 50, sortKey: TITLE) {
+    edges {
+      node {
+        id title handle isPublished
+        bodySummary
+        createdAt updatedAt
+        seo { title description }
+      }
+    }
+  }
+}

package/templates/graphql/content/redirects-list.graphql

@@ -0,0 +1,9 @@
+query RedirectsList {
+  urlRedirects(first: 100) {
+    edges {
+      node {
+        id path target
+      }
+    }
+  }
+}

package/templates/graphql/customers/new-customers.graphql

@@ -0,0 +1,15 @@
+# Customers created in the last 30 days
+query NewCustomers {
+  customers(first: 50, sortKey: CREATED_AT, reverse: true, query: "created_at:>2026-04-23") {
+    edges {
+      node {
+        id displayName numberOfOrders
+        defaultEmailAddress { emailAddress }
+        defaultPhoneNumber { phoneNumber }
+        amountSpent { amount currencyCode }
+        defaultAddress { city country }
+        createdAt
+      }
+    }
+  }
+}

package/templates/graphql/customers/top-spenders.graphql

@@ -0,0 +1,16 @@
+# Customer spend overview
+query CustomerSpendOverview {
+  customers(first: 30) {
+    edges {
+      node {
+        id displayName numberOfOrders
+        defaultEmailAddress { emailAddress }
+        defaultPhoneNumber { phoneNumber }
+        amountSpent { amount currencyCode }
+        tags
+        defaultAddress { city country }
+        createdAt
+      }
+    }
+  }
+}

package/templates/graphql/discounts/active-discounts.graphql

@@ -0,0 +1,27 @@
+query ActiveDiscounts {
+  codeDiscountNodes(first: 30, query: "status:active") {
+    edges {
+      node {
+        id
+        codeDiscount {
+          ... on DiscountCodeBasic {
+            title status appliesOncePerCustomer usageLimit startsAt endsAt
+            codes(first: 5) { edges { node { code asyncUsageCount } } }
+            customerGets {
+              value {
+                ... on DiscountPercentage { percentage }
+                ... on DiscountAmount { amount { amount currencyCode } }
+              }
+              items {
+                ... on AllDiscountItems { allItems }
+              }
+            }
+            customerSelection {
+              ... on DiscountCustomers { customers { id displayName } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/graphql/discounts-list.graphql

@@ -0,0 +1,40 @@
+query DiscountsList {
+  codeDiscountNodes(first: 20) {
+    edges {
+      node {
+        id
+        codeDiscount {
+          ... on DiscountCodeBasic {
+            title
+            status
+            codes(first: 5) {
+              edges {
+                node {
+                  code
+                  asyncUsageCount
+                }
+              }
+            }
+            startsAt
+            endsAt
+            usageLimit
+            appliesOncePerCustomer
+            customerGets {
+              value {
+                ... on DiscountPercentage {
+                  percentage
+                }
+                ... on DiscountAmount {
+                  amount {
+                    amount
+                    currencyCode
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/graphql/inventory-audit.graphql

@@ -0,0 +1,38 @@
+query InventoryAudit {
+  products(first: 50) {
+    edges {
+      node {
+        id
+        title
+        status
+        variants(first: 20) {
+          edges {
+            node {
+              id
+              title
+              sku
+              inventoryItem {
+                id
+                tracked
+              }
+              inventoryQuantity
+            }
+          }
+        }
+      }
+    }
+  }
+  locations(first: 10) {
+    edges {
+      node {
+        id
+        name
+        isActive
+        address {
+          city
+          countryCode
+        }
+      }
+    }
+  }
+}

package/templates/graphql/metafields/product-metafields.graphql

@@ -0,0 +1,14 @@
+# Replace PRODUCT_GID with the actual product global ID, e.g. gid://shopify/Product/123
+query ProductMetafields {
+  product(id: "PRODUCT_GID") {
+    id title
+    metafields(first: 20) {
+      edges {
+        node {
+          id namespace key value type
+          createdAt updatedAt
+        }
+      }
+    }
+  }
+}

package/templates/graphql/orders/list-open.graphql

@@ -0,0 +1,30 @@
+query OpenOrders {
+  orders(first: 50, query: "status:open", sortKey: CREATED_AT, reverse: true) {
+    edges {
+      node {
+        id name createdAt displayFinancialStatus displayFulfillmentStatus
+        totalPriceSet { presentmentMoney { amount currencyCode } }
+        customer {
+          displayName
+          defaultEmailAddress { emailAddress }
+          defaultPhoneNumber { phoneNumber }
+        }
+        shippingAddress { address1 city province country zip }
+        lineItems(first: 5) {
+          edges {
+            node {
+              title quantity
+              originalUnitPriceSet { presentmentMoney { amount currencyCode } }
+              variant { sku }
+            }
+          }
+        }
+        fulfillments {
+          status
+          trackingInfo { number url company }
+        }
+        note tags
+      }
+    }
+  }
+}

package/templates/graphql/orders/revenue-summary.graphql

@@ -0,0 +1,15 @@
+# Revenue and order summary — use with admin:query for a quick snapshot
+query RevenueSummary {
+  orders(first: 250, query: "created_at:>2026-01-01 financial_status:paid") {
+    edges {
+      node {
+        id name createdAt
+        totalPriceSet { presentmentMoney { amount currencyCode } }
+        subtotalPriceSet { presentmentMoney { amount currencyCode } }
+        totalShippingPriceSet { presentmentMoney { amount currencyCode } }
+        displayFulfillmentStatus
+        customer { displayName }
+      }
+    }
+  }
+}

package/templates/graphql/products/list.graphql

@@ -0,0 +1,16 @@
+query ProductsList {
+  products(first: 50, query: "status:active") {
+    edges {
+      node {
+        id title status productType vendor totalInventory
+        priceRangeV2 {
+          minVariantPrice { amount currencyCode }
+          maxVariantPrice { amount currencyCode }
+        }
+        images(first: 1) { edges { node { url } } }
+        variants(first: 1) { edges { node { sku } } }
+        createdAt updatedAt
+      }
+    }
+  }
+}

package/templates/graphql/products/low-inventory.graphql

@@ -0,0 +1,18 @@
+# Lists active products where total inventory is below 5 — useful for restocking alerts
+query LowInventoryProducts {
+  products(first: 100, query: "status:active") {
+    edges {
+      node {
+        id title totalInventory vendor
+        variants(first: 10) {
+          edges {
+            node {
+              title sku inventoryQuantity
+              inventoryItem { id tracked }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/graphql/products-seo-audit.graphql

@@ -0,0 +1,14 @@
+query ProductsSeoAudit {
+  products(first: 50) {
+    nodes {
+      id
+      title
+      handle
+      status
+      seo {
+        title
+        description
+      }
+    }
+  }
+}

package/templates/graphql/shop-query.graphql

@@ -0,0 +1,9 @@
+query ShopInfo {
+  shop {
+    name
+    myshopifyDomain
+    primaryDomain {
+      url
+    }
+  }
+}

package/templates/graphql/store/full-info.graphql

@@ -0,0 +1,23 @@
+query StoreFullInfo {
+  shop {
+    id name myshopifyDomain
+    primaryDomain { url sslEnabled }
+    plan { displayName }
+    currencyCode weightUnit ianaTimezone
+    email
+    shopAddress { address1 address2 city province country zip phone }
+    enabledPresentmentCurrencies
+    checkoutApiSupported
+    features { storefront }
+    contactEmail
+    createdAt
+  }
+  locations(first: 10) {
+    edges {
+      node {
+        id name isActive fulfillsOnlineOrders
+        address { address1 city country }
+      }
+    }
+  }
+}