shopify-agentic-dev-workflow 0.1.0

package/docs/08-product-design.md

@@ -0,0 +1,168 @@
+# Product Design: Shopify Agent CLI
+
+## Goal
+
+A one-command CLI that any Shopify developer can install globally, point at a store, and immediately start working in an AI-agent-centered workflow — without touching Shopify Admin for day-to-day theme and app development.
+
+```bash
+npm install -g github:sagarchauhan005/shopify-agentic-dev-workflow
+shopify-agent init
+```
+
+## Principles
+
+**1. Wrap Shopify CLI, never replace it.**
+Auth, theme operations, app dev, and Admin GraphQL all flow through the `shopify` binary. This keeps the package Shopify-supported and avoids extracting internal tokens.
+
+**2. Guardrails are injected, not assumed.**
+Each project gets its own `AGENTS.md`, `CLAUDE.md`, Cursor rules, or `GEMINI.md` written by `agents:install`. The agent reads the rules from the project folder, so each store can have different publish policies.
+
+**3. Live theme operations are never silent.**
+Any command that would affect a live storefront — `theme:dev`, `theme:push` — displays consequences and requires explicit confirmation. The staging-first path is always option 1.
+
+**4. State is local and project-scoped.**
+Profiles live in `.shopify-agent/` and `.env` in the project folder. There is no global config file. Switching projects means switching folders.
+
+**5. Theme folders are isolated by theme ID.**
+Theme files live under `themes/<theme-name>-<theme-id>/`, with `.shopify-theme.json` metadata to prove which store/theme the folder belongs to. This prevents a pull from one Shopify theme overwriting another theme's code.
+
+**6. Git is part of the safety model.**
+Pull, push, and publish operations require a clean worktree. The CLI should force a commit or stash before exchanging theme files with Shopify.
+
+**7. Tools should fail loudly with fix instructions.**
+`doctor` shows install hints for every missing dependency. `theme:push` on a live theme names the consequence, shows the store domain, and requires typing it back.
+
+## User Journey (tested end-to-end 2025-05-23)
+
+```
+npm install -g github:sagarchauhan005/shopify-agentic-dev-workflow
+
+cd my-shopify-project
+shopify-agent init
+  → Detects existing Shopify CLI login (organization list probe)
+  → Asks for store domain (org list shown as hints)
+  → Optional Theme Access token
+  → Fetches themes — live themes marked ⚠, consequences shown before selecting one
+  → Saves profile to .shopify-agent/profiles/<name>.json
+  → Writes .env with 7 managed SHOPIFY_* keys
+  → Installs AGENTS.md / CLAUDE.md / Cursor rules / GEMINI.md
+
+shopify-agent doctor
+  → Checks Node 18+, npm, git, Shopify CLI 4.x, gh
+  → Shows install hint for each missing tool
+  → Shows active store, theme, API version
+
+shopify-agent theme:pull
+  → Downloads theme files to themes/<theme-name>-<theme-id>/
+  → Writes .shopify-theme.json metadata
+  → Tells the user to commit the pull before the next theme operation
+
+shopify-agent theme:dev
+  → Hot-reload server on 127.0.0.1:9292
+  → --open launches browser automatically
+  → Changes sync to Shopify's dev theme preview in real time
+
+[AI agent edits Liquid, CSS, JS]
+
+shopify-agent theme:check
+  → Theme Check linting
+
+shopify-agent theme:push
+  → If live theme: 3-option guard
+       1. Push to NEW staging theme (--unpublished) [RECOMMENDED]
+       2. Push to live (type store domain to confirm)
+       3. Cancel
+  → If unpublished: direct push
+
+shopify-agent theme:publish
+  → Shows theme name + store + consequences, prompts for confirmation → Goes live
+```
+
+## CLI Architecture
+
+Single-file Node.js CLI at `bin/shopify-agent.js`. No external dependencies — stdlib only (`fs`, `path`, `readline`, `child_process`). This keeps install fast and the package self-contained.
+
+Command routing is a `if/else` chain in `main()`. Each command is a named function.
+
+Key internal utilities:
+
+| Function | Purpose |
+|---|---|
+| `loadConfig()` | Merge `.env` + profile + process.env into a single config object |
+| `fetchThemes()` | `shopify theme list --json`, strip ANSI, trim to first `[` or `{`, parse |
+| `writeLocalEnv()` | Merge-update `.env` — preserve user keys, update managed SHOPIFY_* keys |
+| `hasShopifyCommand()` | Probe `shopify <command> --help`, cache result, return bool |
+| `capture()` | `spawnSync` with `FORCE_COLOR=0`, returns `{ ok, stdout, stderr, output }` |
+| `run()` | `spawnSync` with `stdio: inherit` — for interactive commands |
+| `agentInstructions()` | Generate guardrail markdown for a given tool (codex/claude/cursor/gemini) |
+
+## Agent Guardrail Design
+
+The guardrail files (`AGENTS.md` etc.) are the interface between this CLI and the AI agent. They must:
+
+1. State hard rules clearly at the top (no ambiguity)
+2. List consequences so the agent can explain them to users, not just block
+3. Include the recommended workflow step-by-step
+4. Script the agent's exact response for the most dangerous request (live push)
+
+Current hard rules:
+- Never push to live without showing consequences + offering staging
+- Never publish a theme without an inline confirmation prompt (shows theme + store + consequences)
+- Never run Admin mutations without an inline confirmation prompt
+- Never commit or print secrets
+- Never mix theme folders or pull into the project root
+- Require a clean Git worktree before pull, push, and publish
+- `--yes` / `-y` flag bypasses all prompts — only use when user has already reviewed the operation
+
+## Design-to-Code Lessons
+
+Figma implementation should be treated as both a design task and a Shopify data task:
+
+- Build real Dawn sections/templates for home, PLP, PDP, cart, header, and footer instead of static mockup pages.
+- Make content dynamic through schema settings where merchants will reasonably need control.
+- Preserve a design-preview mode until the real catalog is ready. Demo products can make a correct Figma implementation look broken.
+- Add explicit section settings such as `Use live collection products` or `Use live product data` before Shopify catalog data replaces Figma assets.
+- Verify desktop and mobile screenshots after `theme:check`, especially for header alignment, PLP product grids, PDP media layout, footer links, and horizontal overflow.
+
+## Admin GraphQL Lessons
+
+Shopify Admin GraphQL query templates are API-version dependent. Package defaults should not assume fields from memory.
+
+- If Shopify returns `undefinedField`, treat the template as stale and update it against `SHOPIFY_API_VERSION`.
+- Run the smallest read-only query first before expanding a dashboard or operational command.
+- Keep mutations routed through `admin:mutate` so store context and confirmation are visible.
+- Prefer capability detection and schema-safe templates over hard-coded payload assumptions.
+
+## Shopify CLI Boundary
+
+CLI 4.0.0 new capabilities used:
+
+| Command | Used for |
+|---|---|
+| `organization list --json` | Auth probe (auth whoami does not exist) |
+| `store auth` | Admin API token creation with selected scopes |
+| `store execute` | Read-only and guarded Admin GraphQL execution |
+| `theme preview` | Detected in capabilities (future use) |
+
+Not yet possible via CLI:
+- `store list` — no stable scriptable command; domains must be entered manually
+- Partners API store enumeration — requires separate OAuth/API call
+
+## .env Merge-Update Logic
+
+On every `init` or `theme:select`, `writeLocalEnv()`:
+1. Reads existing `.env` line by line
+2. Updates keys that are in the managed set (`SHOPIFY_STORE`, `SHOPIFY_CLI_THEME_TOKEN`, `SHOPIFY_THEME_ID`, `SHOPIFY_APP_CONFIG`, `SHOPIFY_APP_CLIENT_ID`, `SHOPIFY_STORE_SCOPES`, `SHOPIFY_API_VERSION`)
+3. Preserves any other keys the developer added
+4. Appends managed keys that were not already present
+5. Writes back atomically
+
+This means running `init` again after `theme:select` won't lose a manually added `DEBUG=true`.
+
+## Known Gaps
+
+- No automated test suite — all verification is smoke/manual
+- `store list` requires manual domain entry (Shopify CLI limitation)
+- Admin mutation dry-run artifacts not yet implemented
+- Windows not smoke-tested (bootstrap.sh is bash-only; CLI itself should work)
+- npm not yet published (install via GitHub URL for now)

package/docs/09-shopify-cli-4-capabilities.md

@@ -0,0 +1,48 @@
+# Shopify CLI 4 Capabilities
+
+Checked on May 23, 2026 with:
+
+```bash
+npm view @shopify/cli version
+npx -y @shopify/cli@latest commands
+```
+
+Latest npm version checked: `4.0.0`.
+
+## Useful New or Notable Commands
+
+- `organization list`: lists Shopify organizations available to the account.
+- `store auth`: authenticates an app against a store for store commands and stores an online access token.
+- `store execute`: runs Admin GraphQL queries and mutations against a store using stored auth.
+- `app execute`: runs Admin GraphQL queries and mutations through an installed app. Mutations are only allowed on dev stores.
+- `app bulk execute`: runs bulk Admin GraphQL operations.
+- `app bulk status`: checks bulk operation status.
+- `app bulk cancel`: cancels a bulk operation.
+- `app config validate`: validates app configuration and extensions.
+- `app import-custom-data-definitions`: imports metafield and metaobject definitions.
+- `theme preview`: applies JSON overrides to a theme and returns a preview URL.
+
+## Package Strategy
+
+The wrapper should feature-detect Shopify CLI commands instead of assuming a version:
+
+```bash
+shopify-agent capabilities
+```
+
+If `store execute` exists, Admin GraphQL should use it.
+
+If not, the wrapper can fall back to `app execute` where possible, but production-store mutations should remain blocked unless Shopify CLI and the project policy both allow them.
+
+## GraphQL Template Strategy
+
+Admin GraphQL payloads must be treated as versioned package assets, not timeless snippets.
+
+- Keep query templates compatible with `SHOPIFY_API_VERSION`.
+- If Shopify returns `undefinedField`, update the template and integration test before retrying operational commands.
+- Prefer narrower read-only probes before expanding a dashboard query.
+- Avoid fields that have moved between concrete discount, inventory, product, or customer types unless the query uses the correct inline fragments for the current API version.
+
+## Store Selection Limitation
+
+The checked CLI exposes `organization list`, but not a stable `store list` command. For now, setup asks for the store domain, validates access, then fetches themes from that store.

package/docs/10-field-learnings.md

@@ -0,0 +1,66 @@
+# Field Learnings
+
+These notes come from an end-to-end local setup: connecting a Shopify store, pulling Dawn, patching Admin GraphQL templates, building Figma-designed home/PLP/PDP pages, and verifying the local theme preview.
+
+## Local Setup
+
+- A quick-start project should live adjacent to the package repo, not inside it. This keeps package source changes separate from merchant theme work.
+- Node/npm availability is a first-class prerequisite. If `npm` is missing, setup should point users to install Node before running package commands.
+- Storefront passwords are runtime configuration for preview/dev only. Never commit them into theme files, docs, screenshots, or agent instructions.
+
+## Theme Pulls and Version Control
+
+- `theme:pull` must always write into `themes/<theme-name>-<theme-id>/`.
+- Pulling directly into the project root makes multi-theme work unsafe because Theme A and Theme B can overwrite the same files.
+- Every theme folder needs metadata that records store, theme ID, theme name, role, and pull time.
+- Pull, push, and publish should require a clean Git worktree. This makes every Shopify exchange intentional and recoverable.
+- Commit immediately after a successful pull. Commit again before pushing.
+
+## Multi-Theme Strategy
+
+Use folder isolation as the default strategy:
+
+```text
+themes/dawn-169809707321/
+themes/dawn-copy-170000000000/
+themes/brand-refresh-170000000001/
+```
+
+Branches can still be used for feature work, but they should not be the only safety mechanism. Theme identity belongs in both the folder path and the folder metadata.
+
+## Admin GraphQL
+
+- Shopify Admin GraphQL changes by API version. A query that worked earlier can fail with `undefinedField`.
+- Dashboard, discount, inventory, customer, and product queries should be verified against the configured `SHOPIFY_API_VERSION`.
+- Read-only queries should be tested before wiring them into dashboard commands.
+- Mutations must remain behind explicit confirmation and should show the store, target resource, and planned change.
+
+## Figma-to-Dawn Build
+
+- Build actual Shopify sections and templates, not static HTML pasted into Dawn.
+- Map Figma frames to Shopify surfaces: header, home, collection, product, cart, footer.
+- Use schema settings for editable content and links.
+- Keep Figma design-preview data separate from live Shopify catalog data. Demo products can make a good design implementation look broken.
+- Add section settings to switch from fallback/design content to live product data once the real catalog is ready.
+
+## Visual QA Checklist
+
+Run `shopify-agent theme:check`, then inspect:
+
+- Home, collection, product, cart, search, header, and footer.
+- Desktop and mobile viewports.
+- Header logo/nav/icon alignment.
+- PLP filters, sort, product grid, image aspect ratios, and card links.
+- PDP media gallery, product info, options, quantity, CTA state, dynamic checkout, accordions, and recommendations.
+- Footer policy/support links.
+- Horizontal overflow and text overlap.
+
+## Agent Behavior
+
+Agents should:
+
+- Read local project state before acting: `.env`, active profile, selected theme, theme folder metadata, and Git status.
+- Prefer `shopify-agent` commands over raw Shopify CLI calls so package guardrails run.
+- Stop when the worktree is dirty before a theme pull/push/publish.
+- Never assume a Figma-looking PLP/PDP should use random demo catalog products.
+- Report verification clearly: command run, result, preview URL, and any remaining risk.

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "shopify-agentic-dev-workflow",
+  "version": "0.1.0",
+  "description": "Codex-first Shopify development workflow toolkit for themes, apps, and guarded store operations.",
+  "bin": {
+    "shopify-agent": "bin/shopify-agent.js"
+  },
+  "scripts": {
+    "prepublishOnly": "npm test",
+    "release:check": "npm test && npm pack --dry-run",
+    "pack:dry": "npm pack --dry-run",
+    "validate": "node ./scripts/validate-graphql.js",
+    "test": "node --test --test-concurrency=1 tests/unit/*.test.js tests/integration/*.test.js tests/safety/*.test.js",
+    "test:unit": "node --test --test-concurrency=1 tests/unit/*.test.js",
+    "test:integration": "node --test --test-concurrency=1 tests/integration/*.test.js",
+    "test:safety": "node --test --test-concurrency=1 tests/safety/*.test.js",
+    "test:e2e": "SHOPIFY_TEST_STORE=your-store.myshopify.com node --test tests/e2e/*.test.js",
+    "doctor": "node ./bin/shopify-agent.js doctor",
+    "setup": "node ./bin/shopify-agent.js init",
+    "auth": "node ./bin/shopify-agent.js auth",
+    "capabilities": "node ./bin/shopify-agent.js capabilities",
+    "mcp:install": "node ./bin/shopify-agent.js mcp:install",
+    "agents:install": "node ./bin/shopify-agent.js agents:install",
+    "profile:list": "node ./bin/shopify-agent.js profile:list",
+    "profile:use": "node ./bin/shopify-agent.js profile:use",
+    "store:auth": "node ./bin/shopify-agent.js store:auth",
+    "theme:list": "node ./bin/shopify-agent.js theme:list",
+    "theme:select": "node ./bin/shopify-agent.js theme:select",
+    "theme:check": "node ./bin/shopify-agent.js theme:check",
+    "theme:pull": "node ./bin/shopify-agent.js theme:pull",
+    "theme:dev": "node ./bin/shopify-agent.js theme:dev",
+    "theme:push": "node ./bin/shopify-agent.js theme:push",
+    "theme:publish": "node ./bin/shopify-agent.js theme:publish",
+    "app:dev": "node ./bin/shopify-agent.js app:dev",
+    "app:deploy": "node ./bin/shopify-agent.js app:deploy",
+    "admin:query": "node ./bin/shopify-agent.js admin:query",
+    "admin:mutate": "node ./bin/shopify-agent.js admin:mutate"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "shopify",
+    "shopify-cli",
+    "shopify-theme",
+    "shopify-admin-api",
+    "liquid",
+    "theme-development",
+    "codex",
+    "claude",
+    "cursor",
+    "gemini",
+    "agentic-workflow",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sagarchauhan005/shopify-agentic-dev-workflow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sagarchauhan005/shopify-agentic-dev-workflow/issues"
+  },
+  "homepage": "https://github.com/sagarchauhan005/shopify-agentic-dev-workflow#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".cursor/rules",
+    "AGENTS.md",
+    "bin",
+    "CLAUDE.md",
+    "docs",
+    "GEMINI.md",
+    "scripts",
+    "templates",
+    "CHANGELOG.md",
+    "HANDOFF.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT"
+}

package/scripts/bootstrap.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Node.js 18+ is required."
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "npm is required."
+  exit 1
+fi
+
+echo "Running Shopify agentic workflow setup..."
+npm run setup
+npm run doctor
+
+echo
+read -r -p "Install Shopify Dev MCP into Codex now? [y/N] " answer
+case "$answer" in
+  y|Y|yes|YES)
+    npm run mcp:install
+    echo "Restart Codex after this script finishes."
+    ;;
+  *)
+    echo "Skipped Codex MCP install. Run 'npm run mcp:install' later."
+    ;;
+esac
+
+echo
+echo "Bootstrap complete."
+echo "Next: run 'npm run theme:pull' or open docs/01-onboarding.md."