Shopify theme

/shopify-theme

In-place Shopify theme file edits, the way that actually works. Born from a session that burned ~6 turns fighting push channels: the MCP themeFilesUpsert expires mid-session, and the Shopify CLI theme push 404s with a Theme Access token (even though theme list/pull work). The reliable channel is the Theme Access proxy Asset API via curl/urllib — that's what this skill defaults to.

Engine: scripts/theme_proxy.py (stdlib only). Recipe + history: memory [[shopify-theme-edit-via-api]], [[ExampleBrand-theme-numbered]], [[ExampleBrand-3for100-bundle]].

---

Guardrails (read first)

• Unpublished theme only. Never write the live/MAIN theme. Re-verify role every time (roles + the copy's id change): python3 scripts/theme_proxy.py list.
• No em/en dashes, ever ([[no-em-en-dashes]]). push refuses if it finds — – — – (override --force only if truly intentional).
• Verify it renders, don't just trust the 200 ([[feedback-verify-render-before-claiming-done]]). A successful PUT means the bytes landed, not that it looks right. Give Will the ?preview_theme_id=<id> link.
• Never echo the token. Write it to /tmp/.th_env (chmod 600), use, delete. It's a shptka_ Theme Access password generated from the TARGET store's "Theme Access" app — a token from another store 404s on every call.
• Per-product-template gotcha ([[ExampleBrand-theme-numbered]]): ExampleBrand products use templateSuffix → templates/product.<suffix>.json. Editing the default templates/product.json does NOTHING. To change a PDP block you must edit ALL templates/product.*.json. Self-scoping snippets (render only if product in a collection) make it safe to add a block to every template.

Setup each run

1. Token: ask Will to paste the shptka_... password (Settings → Apps → Theme Access, in the target store). Save it: write /tmp/.th_env, chmod 600. The script reads it from there (or $SHOPIFY_CLI_THEME_TOKEN, or --token).
2. Store: default is ExampleBrand qk6w18-bw.myshopify.com. Override with --shop <handle>.myshopify.com or $SHOPIFY_SHOP. Confirm the handle via the admin URL admin.shopify.com/store/<handle>.
3. Confirm the unpublished theme id: python3 scripts/theme_proxy.py list.

Pipeline

1. LIST     theme_proxy.py list                          -> pick the UNPUBLISHED theme id
2. GET      theme_proxy.py get <id> <key> /tmp/f         -> pull the file to edit (or use the working copy)
3. EDIT     edit /tmp/f locally:
              - JSON templates: strip leading /* ... */ header -> json.loads -> mutate
                blocks / block_order -> json.dumps(indent=2, ensure_ascii=False) -> re-prepend header
              - snippets / *.liquid / *.css: edit directly
4. CHECK    grep -c -e '—' -e '–' -e '&mdash;' -e '&ndash;' /tmp/f   (must be 0; push also enforces)
5. PUSH     theme_proxy.py push <id> <key> /tmp/f         -> expect "OK HTTP 200"
6. VERIFY   give Will https://<domain>/products/<handle>?preview_theme_id=<id> and ask him to hard-refresh
7. CLEAN    rm -f /tmp/.th_env

Run the engine with dangerouslyDisableSandbox (it needs network).

Commands

python3 scripts/theme_proxy.py list
python3 scripts/theme_proxy.py get  <theme_id> snippets/foo.liquid /tmp/foo.liquid
python3 scripts/theme_proxy.py push <theme_id> snippets/foo.liquid /tmp/foo.liquid

key is the theme-relative path (snippets/…, templates/…, assets/…, sections/…).

Errors

• 401 "Invalid API key" = missing/wrong token, or the X-Shopify-Shop header is absent (the script always sends it).
• 404 on every call = the token is for a different store, or the Theme Access app isn't installed on this store. NOT a handle problem if admin.shopify.com/store/<handle> resolves. Regenerate the password from THIS store's Theme Access app.
• Bulk edits (many templates/product.*.json): loop get→edit→push per file, or edit the local pulled copies then push each. For a brand-new snippet you can push it without a prior get.

Handoffs

• Offer/discount economics → [[midas-ecomcfo-skill|/midas]]. Native discount setup (BXGY, free-ship) is Admin API, not this skill. Checkout branding has no API ([[ExampleBrand-checkout-branding-no-api]]).