shopify-agentic-dev-workflow 0.1.0

package/README.md

@@ -0,0 +1,370 @@
+# shopify-agentic-dev-workflow
+
+A terminal-first agentic toolkit for Shopify stores. One command connects your store, sets up your local workspace, configures your AI coding agent, and gives your entire team — developers, catalogers, marketers, and business admins — a full CLI to operate Shopify without living in the Admin panel.
+
+Works with **Codex, Claude Code, Cursor, and Gemini**. Shopify CLI 4.x runs under the hood.
+
+## Quick start
+
+```bash
+# Install globally from npm
+npm install -g shopify-agentic-dev-workflow
+
+# In your project folder
+shopify-agent init       # connect store, configure auth, select theme, write guardrails
+shopify-agent doctor     # verify all tools and show active config
+shopify-agent dashboard  # snapshot of open orders, low stock, active discounts
+```
+
+## Who this is for
+
+| Role | What they can do |
+|---|---|
+| **Developers** | Theme dev (hot-reload, lint, push, publish), app dev, raw GraphQL |
+| **Catalogers** | Manage products, variants, collections, inventory |
+| **Marketing teams** | Discount codes, gift cards, pages, blog articles, redirects, metafields |
+| **Business admins** | Orders, customers, store info, dashboard |
+
+All of it from the terminal. All mutations prompt for confirmation before touching live data.
+
+## What still needs Shopify Admin
+
+- Add collaborator or staff access
+- Create or install a custom app and approve OAuth scopes
+- Connect GitHub theme sync
+- Theme editor UI (drag-and-drop sections)
+
+---
+
+## Commands
+
+### Setup & diagnostics
+
+```bash
+shopify-agent init              # Full interactive setup wizard
+shopify-agent doctor            # Check tools, show active config + install hints
+shopify-agent capabilities      # Detect which Shopify CLI 4.x commands are available
+shopify-agent auth              # shopify auth login
+
+shopify-agent agents:install    # Write AGENTS.md / CLAUDE.md / Cursor rules / GEMINI.md
+shopify-agent mcp:install       # Add Shopify Dev MCP to ~/.codex/config.toml
+
+shopify-agent profile:list      # List saved profiles
+shopify-agent profile:use       # Switch active profile
+
+shopify-agent store:list        # Show Shopify orgs linked to your account
+shopify-agent store:auth        # Create Admin API token with selected scopes (CLI 4.x)
+```
+
+### Theme development
+
+```bash
+shopify-agent theme:list        # List themes with roles
+shopify-agent theme:select      # Pick active theme (live ⚠ warning included)
+shopify-agent theme:pull        # Download theme files locally
+shopify-agent theme:dev         # Hot-reload dev server — opens browser automatically
+shopify-agent theme:check       # Liquid linting via Theme Check
+shopify-agent theme:push        # Push to staging (3-option guard if theme is live)
+shopify-agent theme:publish     # Prompts for confirmation before going live
+```
+
+### App development
+
+```bash
+shopify-agent app:dev           # shopify app dev
+shopify-agent app:deploy        # shopify app deploy
+```
+
+### Raw GraphQL
+
+```bash
+shopify-agent admin:query  <file.graphql>   # Read-only Admin GraphQL
+shopify-agent admin:mutate <file.graphql>   # Mutation (prompts for confirmation)
+```
+
+---
+
+### 📦 Products & Catalog
+
+```bash
+shopify-agent products:list                  # List products  [--status active|draft|archived] [--limit N]
+shopify-agent products:get                   # Interactive full product detail viewer
+shopify-agent products:create                # Wizard: title, type, vendor, price, SKU, inventory, status
+shopify-agent products:publish               # Set a product to Active (visible in store)
+shopify-agent products:archive               # Set a product to Archived
+shopify-agent products:draft                 # Set a product back to Draft
+shopify-agent products:delete                # Delete a product (with confirmation)
+
+shopify-agent variants:list                  # Pick a product → see all variants with price/SKU/qty
+shopify-agent variants:update                # Update price, SKU, barcode for a variant
+
+shopify-agent collections:list               # List all collections (manual + smart)
+shopify-agent collections:create             # Wizard: manual or smart (with rule builder)
+```
+
+### 🏷️ Inventory
+
+```bash
+shopify-agent inventory:list                 # List all inventory levels across locations
+shopify-agent inventory:set <qty>            # Set ALL variants to <qty> in bulk
+shopify-agent inventory:adjust               # Adjust one variant: +5, -3, or =10
+```
+
+### 📋 Orders
+
+```bash
+shopify-agent orders:list                    # List orders  [--status open|closed|cancelled|any] [--limit N]
+shopify-agent orders:get                     # Full order detail: line items, tracking, totals
+shopify-agent orders:cancel                  # Cancel an open order (choose reason, refund, restock)
+shopify-agent orders:close                   # Mark an order as closed
+```
+
+### 👥 Customers
+
+```bash
+shopify-agent customers:list                 # List customers  [--limit N]
+shopify-agent customers:search               # Search by name, email, phone, or tag
+shopify-agent customers:get                  # Full customer profile + recent order history
+shopify-agent customers:create               # Wizard: name, email, phone, tags, marketing opt-in
+shopify-agent customers:tags                 # Add or remove tags on a customer
+```
+
+### 🎟️ Discounts & Gift Cards
+
+```bash
+shopify-agent discounts:list                 # List all discount codes with usage stats
+shopify-agent discounts:create               # Wizard: % off, fixed amount, per-customer, expiry, usage limit
+shopify-agent discounts:delete               # Delete a discount code
+shopify-agent discounts:enable               # Re-activate a disabled discount
+shopify-agent discounts:disable              # Deactivate without deleting
+
+shopify-agent gift-cards:list                # List all gift cards with balance
+shopify-agent gift-cards:create              # Create a gift card (with optional customer assignment)
+```
+
+### 🏪 Store
+
+```bash
+shopify-agent store:info                     # Name, plan, currency, timezone, multi-currency
+shopify-agent store:locations                # List locations with fulfillment status
+shopify-agent store:dashboard                # Snapshot: open orders + low-stock + active discounts
+shopify-agent dashboard                      # Alias for store:dashboard
+```
+
+### 📝 Content
+
+```bash
+shopify-agent pages:list                     # List all pages
+shopify-agent pages:create                   # Wizard: title, body HTML, publish immediately
+shopify-agent blogs:list                     # List blogs with 5 recent articles each
+shopify-agent articles:list                  # Pick a blog → list articles with author + status
+shopify-agent redirects:list                 # List all URL redirects
+shopify-agent redirects:create               # Create a URL redirect (from → to)
+```
+
+### 🔧 Metafields
+
+```bash
+shopify-agent metafields:list                # List metafields for any resource
+shopify-agent metafields:set                 # Create or update a metafield on any resource
+# Works with: Product, Collection, Customer, Order, Shop
+```
+
+---
+
+## Flags
+
+```bash
+--yes, -y       Auto-confirm all prompts (for scripting / CI)
+--status <s>    Filter by status where supported
+--limit <n>     Limit result count where supported
+```
+
+Examples:
+```bash
+shopify-agent products:list --status active --limit 100
+shopify-agent orders:list --status open
+shopify-agent inventory:set 10 --yes
+shopify-agent discounts:list
+```
+
+---
+
+## GraphQL template files
+
+Pre-built query/mutation files in `templates/graphql/` for use with `admin:query` and `admin:mutate`:
+
+```
+templates/graphql/
+  products/
+    list.graphql               Active products with variants and pricing
+    low-inventory.graphql      Products with < 5 units (restocking alert)
+  orders/
+    list-open.graphql          Open orders with line items + tracking
+    revenue-summary.graphql    Paid orders with totals for a date range
+  customers/
+    top-spenders.graphql       Customers ranked by total spend
+    new-customers.graphql      Customers created in the last 30 days
+  discounts/
+    active-discounts.graphql   Active discount codes with usage counts
+  store/
+    full-info.graphql          Complete shop info + locations
+    webhooks.graphql           All registered webhook subscriptions
+  content/
+    pages-list.graphql         All pages with SEO fields
+    redirects-list.graphql     All URL redirects
+  metafields/
+    product-metafields.graphql Metafields for a specific product (edit GID)
+  shop-query.graphql           Shop name + domain
+  inventory-audit.graphql      Inventory levels across all locations
+  discounts-list.graphql       All discount codes
+  products-seo-audit.graphql   Products with SEO title/description gaps
+```
+
+---
+
+## Live theme safety
+
+Every operation that touches a live theme requires explicit confirmation. `theme:push` on a live theme shows:
+
+```
+1. Push to a NEW staging theme (safe — preview before publishing)  [RECOMMENDED]
+2. Push directly to LIVE theme  (type store domain to confirm)
+3. Cancel
+```
+
+`theme:publish` shows the theme name, store domain, and consequences before asking.
+
+The AI guardrail files installed by `agents:install` enforce the same rules inside Codex/Claude/Cursor/Gemini.
+
+---
+
+## Theme dev workflow
+
+```bash
+# One-time setup per project
+shopify-agent init              # connect store, select unpublished theme
+shopify-agent theme:pull        # download theme files to themes/<theme-name>-<theme-id>/
+
+# Daily loop
+shopify-agent theme:dev         # hot-reload server, browser opens automatically
+# edit sections/*.liquid, assets/*.css, etc.
+shopify-agent theme:check       # lint after changes
+shopify-agent theme:push        # push to unpublished staging theme
+# preview in Shopify Admin → Themes → Preview
+
+shopify-agent theme:publish     # prompts for confirmation — go live after review
+```
+
+### Theme folders and Git guardrails
+
+The CLI keeps each Shopify theme isolated under `themes/<theme-name>-<theme-id>/` and writes `.shopify-theme.json` metadata inside that folder. This prevents a developer from pulling Theme A over Theme B or dumping theme files into the project root.
+
+`theme:pull`, `theme:push`, and `theme:publish` require a clean Git worktree. Commit after every pull and before every push so every Shopify operation has a visible rollback point.
+
+### Figma-to-Dawn workflow
+
+When building a storefront from Figma, treat design fidelity and live Shopify data as two separate concerns:
+
+- Map Figma frames to real Dawn sections and templates: home, collection, product, cart, header, and footer.
+- Use section schema settings for merchant-editable content.
+- Keep design-preview fallback content until the real catalog is ready; demo store products can make a correct layout look broken.
+- Add explicit toggles such as `Use live collection products` and `Use live product data` before letting Shopify catalog data override Figma visuals.
+- Verify with `shopify-agent theme:check` and desktop/mobile preview screenshots for home, PLP, PDP, header, footer, links, and horizontal overflow.
+
+---
+
+## Configuration
+
+`init` creates two local files (both git-ignored):
+
+| File | Contents |
+|---|---|
+| `.env` | 7 managed `SHOPIFY_*` keys — user-added keys are never overwritten |
+| `.shopify-agent/profiles/<name>.json` | Store domain, theme ID/name/role, token, app config, API version |
+
+Key `.env` values:
+
+```
+SHOPIFY_STORE=your-store.myshopify.com
+SHOPIFY_CLI_THEME_TOKEN=         # Theme Access token (optional; blank = Shopify CLI session)
+SHOPIFY_THEME_ID=                # Active staging theme ID
+SHOPIFY_API_VERSION=2026-04
+```
+
+## Auth model
+
+| Method | How | Best for |
+|---|---|---|
+| Shopify CLI session | `shopify auth login` (browser OAuth) | Local dev with Partners/staff access |
+| Theme Access token | Password from Theme Access app | Theme-only work, CI, agencies |
+
+The toolkit never reads or copies Shopify CLI's internal session tokens.
+
+## Requirements
+
+- Node.js 18+ (checked at startup — error includes install URL)
+- Shopify CLI 4.x (`npm install -g @shopify/cli@latest`)
+- Git
+
+Optional:
+- GitHub CLI (`gh`) for repo/PR workflow
+- Codex, Claude Code, Cursor, or Gemini for AI-assisted development
+
+## Install guides
+
+- macOS: `brew install node && npm install -g @shopify/cli@latest`
+- Windows/Linux: see [docs/00-prerequisites.md](docs/00-prerequisites.md)
+
+## Publishing to npm
+
+The public npm package name is currently intended to be:
+
+```bash
+shopify-agentic-dev-workflow
+```
+
+Release checklist:
+
+```bash
+npm login
+npm test
+npm pack --dry-run
+npm publish
+```
+
+After publishing, users can install it with:
+
+```bash
+npm install -g shopify-agentic-dev-workflow
+shopify-agent init
+```
+
+## Repository layout
+
+```
+bin/shopify-agent.js            CLI entrypoint — all 60+ commands, single file, no deps
+docs/                           Onboarding, SDLC, security, product design notes
+scripts/bootstrap.sh            Local dev bootstrap helper
+templates/
+  .env.example
+  codex-config.toml
+  github-actions/deploy-theme.yml
+  graphql/                      Pre-built GraphQL query + mutation files by category
+  prompts/                      Reusable agent task prompts
+HANDOFF.md                      Full technical handoff for agents and new contributors
+```
+
+## Security defaults
+
+- Secrets are never committed — `.env` and `.shopify-agent/` are git-ignored
+- All mutation commands prompt for confirmation before modifying live store data
+- `theme:publish` shows consequences and asks before going live
+- Live `theme:push` requires typing the store domain
+- `--yes` / `-y` flag bypasses prompts — only for scripts where user has already reviewed
+- Agent guardrail files enforce all rules inside Codex/Claude/Cursor/Gemini
+
+## For the team
+
+See [HANDOFF.md](HANDOFF.md) for full architecture, all design decisions, and implementation details.
+See [docs/10-field-learnings.md](docs/10-field-learnings.md) for lessons from a full store connection, theme pull, Figma build, and local QA session.