shopify-agentic-dev-workflow 0.1.0

package/HANDOFF.md

@@ -0,0 +1,351 @@
+# Agent Handoff: Shopify Agentic Development Workflow
+
+## Goal
+
+A reusable npm/npx CLI package that enables the **entire Shopify team** — developers, catalogers, marketing teams, and business admins — to operate their Shopify stores entirely from the terminal through an AI-agent-centered workflow. Shopify CLI 4.x runs under the hood. Guardrail files injected into the project control how Codex, Claude, Cursor, or Gemini behave.
+
+No one on the team should need to live inside Shopify Admin for day-to-day work. Admin is only needed for first-time approvals, OAuth, app installs, collaborator access, and UI-only checks (drag-and-drop theme editor).
+
+## Repository
+
+- GitHub: `https://github.com/sagarchauhan005/shopify-agentic-dev-workflow`
+- Local path: `/Users/sagar/Documents/Development/Shopify/Shopify Automation`
+- Package name: `shopify-agentic-dev-workflow`
+- Binary name: `shopify-agent`
+- Runtime: Node.js 18+
+- License: MIT
+
+## End-to-End Test Status
+
+Fully tested on 2026-05-23 against `quickstart-3485ea1e.myshopify.com` (Dawn theme, unpublished):
+
+```
+npm install -g github:sagarchauhan005/shopify-agentic-dev-workflow
+shopify-agent init          ✓ auth detected, org list probe, theme fetch, profile saved
+shopify-agent doctor        ✓ all tools OK, config shown
+shopify-agent theme:list    ✓ 3 themes returned with roles
+shopify-agent theme:select  ✓ live ⚠ warning shown, switched to Dawn (unpublished)
+shopify-agent theme:pull    ✓ Dawn files pulled to ./quick-start/
+shopify-agent theme:dev     ✓ dev server started, browser opened at 127.0.0.1:9292
+shopify-agent theme:check   ✓ no new errors
+shopify-agent theme:push    ✓ live-theme guard shown, staging option offered
+```
+
+Theme changes deployed during test:
+- Color scheme: blue buttons (`#2563EB`), rounded corners, card shadows, hover animations
+- Homepage: hero copy, brand story section, feature-cards section
+- New custom section: `agentic-features.liquid` (schema-driven feature cards grid)
+- `assets/custom-overrides.css`: button transitions, card hover lift, header polish
+
+## Current File Layout
+
+```
+bin/shopify-agent.js        Core CLI — all 60+ commands, single file, stdlib only
+docs/
+  00-prerequisites.md       Zero-to-working install guide (macOS, Windows, Linux)
+  01-onboarding.md
+  02-theme-sdlc.md
+  03-app-sdlc.md
+  04-admin-api-ops.md
+  05-codex-prompts.md
+  06-security-guardrails.md
+  07-github-rollout.md
+  08-product-design.md      Product decisions and design notes
+  09-shopify-cli-4-capabilities.md
+scripts/bootstrap.sh        Local repo bootstrap helper
+templates/
+  .env.example
+  codex-config.toml
+  github-actions/deploy-theme.yml
+  graphql/
+    products/               list.graphql, low-inventory.graphql
+    orders/                 list-open.graphql, revenue-summary.graphql
+    customers/              top-spenders.graphql, new-customers.graphql
+    discounts/              active-discounts.graphql
+    store/                  full-info.graphql, webhooks.graphql
+    content/                pages-list.graphql, redirects-list.graphql
+    metafields/             product-metafields.graphql
+    shop-query.graphql
+    inventory-audit.graphql
+    discounts-list.graphql
+    products-seo-audit.graphql
+  prompts/admin-operation.md
+  prompts/theme-task.md
+HANDOFF.md                  This file
+README.md                   Team-facing quick start
+package.json                npm/npx package config
+```
+
+---
+
+## Full Command Surface
+
+### Setup & Diagnostics
+
+| Command | What it does |
+|---|---|
+| `shopify-agent init` | Full wizard: auth check → org probe → store domain → theme token → theme select (live ⚠ warning) → app config → profile save → .env write → guardrail install |
+| `shopify-agent auth` | `shopify auth login` |
+| `shopify-agent doctor` | Check Node 18+, npm, git, Shopify CLI, gh. Show install hints + active config. |
+| `shopify-agent capabilities` | Feature-detect Shopify CLI 4.x commands |
+| `shopify-agent mcp:install` | Add Shopify Dev MCP to `~/.codex/config.toml` |
+| `shopify-agent agents:install` | Write `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/shopify-agentic-dev.mdc`, `GEMINI.md` |
+| `shopify-agent profile:list` | List local profiles with active marker |
+| `shopify-agent profile:use` | Switch active profile |
+| `shopify-agent store:list` | `shopify organization list` — orgs + dev stores |
+| `shopify-agent store:auth` | `shopify store auth` — create Admin API token with selected scopes |
+
+### Theme
+
+| Command | What it does |
+|---|---|
+| `shopify-agent theme:list` | List themes with role |
+| `shopify-agent theme:select` | Interactive picker — live ⚠ warning, offers to switch to unpublished |
+| `shopify-agent theme:pull` | `shopify theme pull` with stored theme ID |
+| `shopify-agent theme:dev` | Hot-reload dev server — `--open --allow-live --theme <id>` |
+| `shopify-agent theme:check` | Liquid linter |
+| `shopify-agent theme:push` | Live theme: 3-option guard (staging / live+type-domain / cancel). Unpublished: direct push. |
+| `shopify-agent theme:publish` | Shows theme + store + consequences, prompts before going live |
+
+### App
+
+| Command | What it does |
+|---|---|
+| `shopify-agent app:dev` | `shopify app dev` |
+| `shopify-agent app:deploy` | `shopify app deploy` |
+
+### Raw GraphQL
+
+| Command | What it does |
+|---|---|
+| `shopify-agent admin:query <file>` | Read-only GraphQL via `store execute` (CLI 4.x) or `app execute` |
+| `shopify-agent admin:mutate <file>` | Mutation — shows filename + store, prompts before executing |
+
+### Products & Catalog
+
+| Command | What it does |
+|---|---|
+| `shopify-agent products:list` | Table of products with status, inventory, price `[--status] [--limit]` |
+| `shopify-agent products:get` | Interactive picker → full detail with all variants |
+| `shopify-agent products:create` | Wizard: title, type, vendor, price, SKU, initial inventory, status |
+| `shopify-agent products:publish` | Set selected product status to ACTIVE |
+| `shopify-agent products:archive` | Set selected product status to ARCHIVED |
+| `shopify-agent products:draft` | Set selected product status to DRAFT |
+| `shopify-agent products:delete` | Delete product with confirmation |
+| `shopify-agent variants:list` | Pick product → table of variants with SKU, price, inventory |
+| `shopify-agent variants:update` | Pick product → variant → update price / SKU / barcode |
+| `shopify-agent collections:list` | Table of collections with type (smart/manual) and product count |
+| `shopify-agent collections:create` | Wizard: title, type, and smart rule builder (column / relation / condition) |
+
+### Inventory
+
+| Command | What it does |
+|---|---|
+| `shopify-agent inventory:list` | All inventory items × all active locations with stock levels |
+| `shopify-agent inventory:set <qty>` | Bulk-set ALL product variants to qty (with preview + confirm) |
+| `shopify-agent inventory:adjust` | Pick variant → `+5`, `-3`, or `=10` (delta or absolute) |
+
+### Orders
+
+| Command | What it does |
+|---|---|
+| `shopify-agent orders:list` | Table of orders `[--status open|closed|cancelled|any] [--limit]` |
+| `shopify-agent orders:get` | Pick order → full detail: line items, tracking, subtotal/shipping/tax/total |
+| `shopify-agent orders:cancel` | Pick order → choose reason → refund? → restock? → confirm |
+| `shopify-agent orders:close` | Pick order → confirm → close |
+
+### Customers
+
+| Command | What it does |
+|---|---|
+| `shopify-agent customers:list` | Table of customers with spend + location `[--limit]` |
+| `shopify-agent customers:search` | Search by name, email, phone, or tag → table |
+| `shopify-agent customers:get` | Search → pick → full profile with order history |
+| `shopify-agent customers:create` | Wizard: name, email, phone, tags, marketing opt-in |
+| `shopify-agent customers:tags` | Search → pick customer → add or remove tags |
+
+### Discounts & Gift Cards
+
+| Command | What it does |
+|---|---|
+| `shopify-agent discounts:list` | Table: code, value, usage, limit, 1×/customer, status, expiry |
+| `shopify-agent discounts:create` | Wizard: code, % or fixed, once-per-customer, start/end, usage limit |
+| `shopify-agent discounts:delete` | Pick discount → confirm → delete |
+| `shopify-agent discounts:enable` | Re-activate a disabled discount |
+| `shopify-agent discounts:disable` | Deactivate without deleting |
+| `shopify-agent gift-cards:list` | Table: masked code, initial value, balance, customer, expiry, status |
+| `shopify-agent gift-cards:create` | Wizard: amount, note, expiry, optional customer assignment |
+
+### Store
+
+| Command | What it does |
+|---|---|
+| `shopify-agent store:info` | Name, domain, plan, currency, timezone, multi-currency |
+| `shopify-agent store:locations` | All locations with active/fulfills status |
+| `shopify-agent store:dashboard` / `dashboard` | Snapshot: 5 open orders + active product inventory + active discounts |
+
+### Content
+
+| Command | What it does |
+|---|---|
+| `shopify-agent pages:list` | Table of pages with handle, published status, last updated |
+| `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 blog → table of articles with author + published date |
+| `shopify-agent redirects:list` | All URL redirects (from → to) |
+| `shopify-agent redirects:create` | Create a URL redirect |
+
+### Metafields
+
+| Command | What it does |
+|---|---|
+| `shopify-agent metafields:list` | Pick resource type → pick resource → list all metafields |
+| `shopify-agent metafields:set` | Pick resource → namespace, key, type, value → create or update |
+| Supported resource types | Product, Collection, Customer, Order, Shop |
+
+### Global Flags
+
+| Flag | Effect |
+|---|---|
+| `--yes` / `-y` | Auto-confirm all prompts (scripting / CI) |
+| `--status <s>` | Filter by status (products:list, orders:list) |
+| `--limit <n>` | Limit result count (products:list, orders:list, customers:list) |
+
+---
+
+## Local State Model
+
+All state is project-local and git-ignored:
+
+```
+.env                              SHOPIFY_* env vars (7 managed keys, user keys preserved)
+.shopify-agent/
+  profiles/<name>.json            Store domain, theme ID/name/role, token, app config, API version
+  active-profile                  Active profile name pointer
+  config.json                     { profile: "<name>" }
+```
+
+Profile fields: `name`, `store`, `themeId`, `themeName`, `themeRole`, `themeToken`, `appConfig`, `appClientId`, `storeScopes`, `apiVersion`.
+
+`.env` merge-update: managed `SHOPIFY_*` keys are updated in-place; user-added keys are preserved.
+
+---
+
+## Key Design Decisions
+
+1. **Wrap Shopify CLI, don't replace it.**
+   Auth, theme ops, app dev, and Admin GraphQL all go through the `shopify` binary. This keeps the package aligned with Shopify-supported workflows and avoids extracting internal tokens.
+
+2. **All mutations prompt inline — no env var gates.**
+   Commands ask for confirmation at the moment of execution. The `--yes` / `-y` flag skips prompts for scripting. The single `confirm()` function checks `YES_FLAG` so every command benefits automatically.
+
+3. **Single-file, stdlib only.**
+   `bin/shopify-agent.js` uses only `fs`, `path`, `readline`, `child_process`, `os`. No `npm install` beyond the package itself. Keeps installs fast and avoids supply-chain risk.
+
+4. **Feature-detect CLI version at runtime.**
+   `hasShopifyCommand("store execute")` probes each command before use so the package works on CLI 3.x (degraded) and 4.x (full).
+
+5. **Auth probe via `organization list`.**
+   `shopify auth whoami` does not exist in CLI 4.x. Login state is detected by probing `shopify organization list --json` — success = logged in.
+
+6. **Live theme push is a 3-option explicit gate.**
+   Option 1: push to NEW unpublished staging theme (recommended). Option 2: push to live (requires typing store domain). Option 3: cancel. `themeRole` is stored in profile at select/init time so guards work without a network call.
+
+7. **ANSI stripped from all captured CLI output.**
+   `FORCE_COLOR=0` in env + `stripAnsi()` regex so `JSON.parse` never breaks on colored terminal output.
+
+8. **Dynamic mutations via temp files.**
+   Smart commands (inventory:set, discount:create, products:create, etc.) build GraphQL mutation strings from user input, write to a temp file in `os.tmpdir()`, pass to `store execute --allow-mutations`, then delete the temp file in a `finally` block.
+
+9. **Shared admin helpers.**
+   `captureAdminQuery(queryStr, cfg)` — run a query, parse JSON, return `data`.
+   `runAdminMutation(mutationStr, cfg)` — run a mutation, display output.
+   `printTable(rows)` — render ASCII table with borders.
+   `parseCliFlags()` — parse `--key value` flags from argv.
+   `extractId(gid)` — strip `gid://shopify/Type/` prefix.
+   `esc(str)` — escape for GraphQL string literals.
+
+10. **Agent guardrail files are project-local.**
+    `AGENTS.md`, `CLAUDE.md`, Cursor rules, `GEMINI.md` are written per project folder. They include the full command surface, hard rules, live theme consequences, and team-specific workflow examples.
+
+---
+
+## Shopify CLI 4.x Findings
+
+- Installed at: `/Users/sagar/Library/Application Support/Herd/config/nvm/versions/node/v20.19.5/bin/shopify`
+- Version: `4.0.0`
+- Key new commands: `organization list`, `store auth`, `store execute`
+- `auth whoami` does NOT exist — use `organization list` as auth probe
+- `store execute` supports `--allow-mutations` flag for Admin writes
+- `store execute` help text is probed for `--query-file` vs `--query` flag support
+- Theme list JSON may have informational text before the JSON array — parser trims to first `[` or `{`
+- `FORCE_COLOR=0` set in all captured calls defensively
+
+---
+
+## Agent Guardrail Content (summary)
+
+Written to `AGENTS.md`, `CLAUDE.md`, Cursor rules, `GEMINI.md` by `agents:install`.
+
+**Hard rules:**
+1. Never push to a live theme without explicit user confirmation — always offer staging first
+2. Never publish a theme without inline confirmation — show consequences first
+3. Never run Admin mutations without inline confirmation — show what will change first
+4. Never commit or print secrets (`.env`, tokens, client secrets)
+5. `--yes` flag only when user has already reviewed and explicitly approved
+
+**Live theme consequences (agent must recite before any live push):**
+- Storefront updates immediately for all visitors
+- Broken Liquid/CSS is customer-visible instantly
+- No auto-revert — must manually republish previous theme
+- A single typo in a section template can blank pages for real customers
+
+**Recommended workflow per team (as written in guardrail files):**
+- Developers: `theme:dev` → edit → `theme:check` → `theme:push` → preview → `theme:publish`
+- Catalogers: `products:list` → `products:create/update` → `inventory:adjust` → `collections:*`
+- Marketing: `discounts:list` → `discounts:create` → `gift-cards:*` → `metafields:set`
+- Business admins: `dashboard` → `orders:list` → `orders:get` → `customers:search`
+
+---
+
+## Verification Completed
+
+```bash
+node --check bin/shopify-agent.js      # syntax OK (2310 lines)
+npm pack --dry-run                     # files listed, no secrets included
+shopify version                        # 4.0.0
+shopify-agent capabilities             # all CLI 4.x commands available
+shopify-agent init                     # full flow tested against quickstart store
+shopify-agent theme:pull               # Dawn theme pulled to ./quick-start/
+shopify-agent theme:dev                # hot-reload confirmed, browser opened
+shopify-agent theme:push               # live-push guard confirmed
+```
+
+---
+
+## Known Gaps / Recommended Next Steps
+
+1. **Publish to npm.** Package is ready — run `npm publish` with a scoped or unscoped name.
+2. **Automated tests.** No test suite yet. Priority: profile loading, `.env` merge, ANSI stripping, mutation confirmation gate, live-theme guard logic, `printTable` formatting.
+3. **`store list` via Shopify Partners API.** `organization list` returns orgs but not store domains. A Partners API OAuth call could enumerate stores properly.
+4. **Dry-run artifacts for mutations.** Before executing, write `.shopify-agent/runs/<timestamp>/plan.md` showing the operation and expected effect.
+5. **Order fulfillment commands.** `orders:fulfill`, `orders:refund` — not yet implemented.
+6. **Draft orders.** `draft-orders:list`, `draft-orders:create` — useful for wholesale flows.
+7. **`theme:push` target flag.** Currently pushes to profile-stored theme ID. Add `--to <theme-id>` for one-off pushes.
+8. **Scope picker for `store:auth`.** Currently free-text comma-separated. Could be an interactive multiselect.
+9. **Windows smoke test.** CLI uses `path.join` correctly but `bootstrap.sh` is bash-only.
+10. **metafields:delete.** Deletion not yet implemented (`metafieldDelete` mutation).
+11. **articles:create.** Content creation wizard not yet implemented.
+12. **Bulk operations.** `inventoryBulkAdjust`, `productBulkCreate` for large catalogues.
+
+---
+
+## External Sources
+
+- https://shopify.dev/docs/api/shopify-cli/store/store-auth
+- https://shopify.dev/docs/api/shopify-cli/store/store-execute
+- https://shopify.dev/docs/api/shopify-cli/app/app-execute
+- https://shopify.dev/docs/api/shopify-cli/theme
+- https://shopify.dev/docs/storefronts/themes/tools/cli
+- https://shopify.dev/docs/apps/build/ai-toolkit
+- https://shopify.dev/docs/api/admin-graphql

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.