@greatstore/cli 0.1.1 → 0.1.3

package/dist/gs-skill/recipes/product-faq.md

@@ -0,0 +1,58 @@
+# Product FAQ accordion
+
+> **Treat this code as a reference, not a drop-in.** Samples are
+> framework-free vanilla JS so they stay portable — re-express the same
+> logic in the conventions of the repo you're working in (React, Vue,
+> Shopify Liquid sections, Svelte, …) instead of retrofitting the sample
+> as-is.
+
+```js
+const data = await window.GreatStore.generateStructuredContent(
+  {
+    type: "object",
+    properties: {
+      faqs: {
+        type: "array", minItems: 3, maxItems: 5,
+        items: {
+          type: "object",
+          properties: {
+            question: { type: "string", maxLength: 90 },
+            answer: { type: "string", maxLength: 300 },
+          },
+          required: ["question", "answer"],
+        },
+      },
+    },
+    required: ["faqs"],
+  },
+  `Generate the questions shoppers most plausibly have before buying the ` +
+    `product "${productName}", with accurate answers grounded in the real ` +
+    `product details and store policies. Skip any question the store data ` +
+    `can't answer confidently.`
+);
+
+const wrap = document.getElementById("gs-faq");
+for (const { question, answer } of data.faqs) {
+  const details = document.createElement("details");
+  const summary = document.createElement("summary");
+  summary.textContent = question;
+  const p = document.createElement("p");
+  p.textContent = answer;
+  details.append(summary, p);
+  wrap.append(details);
+}
+wrap.hidden = false;
+```
+
+Engagement bonus — append a hand-off row so unanswered questions become
+conversations:
+
+```js
+const ask = document.createElement("button");
+ask.type = "button";
+ask.textContent = "Have a different question? Ask us";
+ask.addEventListener("click", () =>
+  window.GreatStore.sendMessage(`I have a question about "${productName}".`)
+);
+wrap.append(ask);
+```

package/dist/gs-skill/references/agents-and-mcp.md

@@ -0,0 +1,35 @@
+# AI agents and the store's MCP endpoint
+
+Every GreatStore store publishes a standard MCP server card, and the
+platform runs one MCP endpoint for coding agents — no authentication
+required for either:
+
+| URL | What it is |
+|---|---|
+| `https://<slug>.greatstore.ai/.well-known/mcp/server-card.json` | Standard MCP server card — machine-readable discovery document for the store. |
+| `https://admin.greatstore.ai/mcp` | A **documentation server for coding agents**: its tools return usage docs for the `gs` CLI. Same URL for every store. |
+
+## CLI docs for coding agents — `/mcp`
+
+A stateless HTTP MCP whose tools hand back markdown documentation for `gs`
+CLI commands.
+
+```
+claude mcp add --transport http greatstore-admin https://admin.greatstore.ai/mcp
+```
+
+Useful when a coding agent is shipping chat components
+([chat-components.md](chat-components.md)) and needs the exact command for
+the next step. If this skill is installed, the agent already has the
+workflow — the MCP is the self-serve alternative for agents that don't.
+
+## What to use when
+
+- **Building the merchant's site** → this skill's other references (the SDK,
+  structured content, page tools).
+- **A coding agent shipping chat components** → the `gs` CLI, with `/mcp`
+  as its built-in documentation.
+- **Reading or changing store settings** (origin allowlists, CSP hosts, MCP
+  connectors, brand config) → the `gs` CLI's admin commands —
+  [store-admin.md](store-admin.md), including which changes are safe to make
+  without asking the merchant.

package/dist/gs-skill/references/chat-components.md

@@ -0,0 +1,224 @@
+# Custom chat components — authoring with the `gs` CLI
+
+Remote components are React components the assistant renders **inside the
+conversation** — product configurators, quizzes, size guides, booking forms,
+anything richer than text. Each component is an AI-callable tool: the
+manifest's `description` tells the assistant *when* to show it, its
+`inputSchema` declares the props the assistant fills in, and a `displayMode`
+picks where it appears.
+
+Authoring requires store-owner access (`gs login` signs in with the store
+owner's account).
+
+## Workflow
+
+```
+npm install -g @greatstore/cli     # or npx @greatstore/cli <command>
+gs login                           # browser sign-in
+gs apps init --store my-store      # scaffold a project root
+cd <project> && npm install
+gs apps init size_guide            # scaffold components/size_guide/
+# … edit components/size_guide/{component.tsx,manifest.json} …
+gs apps build                      # bundle every component
+gs apps push                       # upload changed components as drafts
+gs apps publish size_guide         # promote to live
+```
+
+`gs apps list` shows what's deployed (with dashboard links); `gs apps pull`
+round-trips remote components back to disk. `gs apps push` hashes components
+and only uploads what changed. (The subcommands also work at the top level —
+`gs push` == `gs apps push`.)
+
+The scaffold writes an `AGENTS.md` into the project (with `CLAUDE.md` /
+`GEMINI.md` symlinked) containing the complete design rules and brand
+variable table — your coding agent picks it up automatically when working in
+the project. `https://admin.greatstore.ai/mcp` serves the same CLI docs to
+agents over MCP (see [agents-and-mcp.md](agents-and-mcp.md)).
+
+## `manifest.json`
+
+```json
+{
+  "name": "size_guide",
+  "displayName": "Size guide",
+  "description": "Interactive size guide. Show when the shopper asks about sizing or fit for apparel.",
+  "displayMode": "inline",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "productName": { "type": "string" },
+      "category": { "type": "string" }
+    },
+    "required": ["productName"]
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Tool name, snake_case (`^[a-z][a-z0-9_]*$`), matches the folder under `components/`. |
+| `displayName` | Friendly label shown in chat UI. |
+| `description` | **Load-bearing** — how the assistant decides when to render the component. Say what it shows *and* when to use it, like any good tool description. |
+| `displayMode` | Where it renders — see below. |
+| `inputSchema` | JSON Schema for the props the assistant fills. Keep it tight; required fields the AI can't infer cause bad calls. |
+| `async` | Set `true` for backend-backed components (see Async below). |
+
+### Display modes
+
+- `inline` — a bubble inside the chat transcript; persists with the message
+  log.
+- `over-input` — floats above the chat input (like a question overlay);
+  cleared by the next user turn or an explicit close.
+- `fullscreen` — takes over the full preview surface; persists until the
+  next widget-emitting tool call or an explicit close.
+
+## The component contract
+
+`component.tsx` default-exports a React component. Its props are the
+`inputSchema` fields the assistant filled, plus six GreatStore-injected
+lifecycle props (always present):
+
+| Prop | What it does |
+|---|---|
+| `onSendMessage(text)` | Send text into the chat as if the shopper typed it — lets the component drive the conversation ("Selected size M, what's the return policy?"). |
+| `onCallTool(name, args)` | Chain into another remote-component tool by name. |
+| `onUpdateModelContext(context)` | Inject **invisible** background context for the model — the variant the shopper selected, the options they configured, the step they're on. Replaces the prior value (never appends); pass `""` to clear. Read on the next chat turn. Use this instead of `onSendMessage` when the assistant should *know* state without a message appearing in the transcript. |
+| `onShowLightbox({ src, originRect? })` | Expand an image in the chat's shared full-screen lightbox — an on-brand zoom overlay you can't render yourself (your component is boxed inside its own bounds and shadow root). Pass the image `src`; for a smooth zoom, also pass the clicked element's `getBoundingClientRect()` as `originRect` (omit it and the image grows from the viewport centre). |
+| `onGenerateStructuredContent(schema, prompt, fallback)` | Ask the store's assistant for content matching a JSON Schema (or Zod schema) and get back the generated object. Personalized to the shopper. Works the same in the conversation on the storefront and every embed — no `window.GreatStore` needed. Best for async components that build their render from a generated payload. `fallback` is **required**: a schema-shaped object you provide that the component preview renders (no live store there), validated against the schema — a mismatch throws. |
+| `onClose()` | Dismiss the host slot. `over-input` clears the overlay, `fullscreen` reverts the pane, `inline` is a no-op. |
+
+Reach for `onUpdateModelContext` when the shopper changes something inside
+the component (picks a size, configures a build, advances a quiz) and you
+want the assistant to factor it into the *next* thing they ask — without
+spamming the chat with a visible "I selected M" message. Use `onSendMessage`
+when you actually want a turn to happen now.
+
+Reach for `onShowLightbox` whenever your component shows imagery the shopper
+might want to inspect closely — product photos, swatches, a size chart. A
+thumbnail's `onClick` handler is the natural place to call it. Don't build
+your own full-screen modal: a remote component is sandboxed inside its own
+bounds and shadow root, so a self-rendered overlay can't cover the chat. The
+shared lightbox escapes those bounds and themes itself from the store's CSS
+variables.
+
+```tsx
+import React from "react";
+
+interface Props {
+  productName: string;
+  category?: string;
+  onSendMessage: (text: string) => void;
+  onCallTool: (name: string, args: Record<string, unknown>) => void;
+  onUpdateModelContext: (context: string) => void;
+  onShowLightbox: (options: { src: string; originRect?: DOMRect }) => void;
+  onGenerateStructuredContent: <T = unknown>(
+    schema: object,
+    prompt: string,
+    fallback: T,
+  ) => Promise<T>;
+  onClose: () => void;
+}
+
+export default function SizeGuide({
+  productName,
+  onSendMessage,
+  onUpdateModelContext,
+  onShowLightbox,
+}: Props) {
+  return (
+    <div
+      style={{
+        padding: "1em",
+        border: "1px solid var(--color-border-default)",
+        borderRadius: "var(--radius-lg)",
+        background: "var(--color-surface)",
+        color: "var(--color-foreground)",
+        fontFamily: "var(--font-primary)",
+      }}
+    >
+      {/* … sizes for {productName} … */}
+      <img
+        src={`/size-charts/${productName}.png`}
+        alt={`${productName} size chart`}
+        style={{ cursor: "zoom-in", width: "100%" }}
+        onClick={(e) =>
+          onShowLightbox({
+            src: `/size-charts/${productName}.png`,
+            originRect: e.currentTarget.getBoundingClientRect(),
+          })
+        }
+      />
+      <button
+        onClick={() =>
+          // Silent: the assistant now knows the pick for the shopper's
+          // next question, with nothing added to the transcript.
+          onUpdateModelContext(`Shopper selected size M of "${productName}".`)
+        }
+      >
+        Select size M
+      </button>
+      <button onClick={() => onSendMessage(`Size M of "${productName}" — is it in stock?`)}>
+        Ask about size M
+      </button>
+    </div>
+  );
+}
+```
+
+## Design rules (non-negotiable)
+
+Components render inside arbitrary publisher pages *and* the GreatStore
+storefront; you control neither the host's root font size nor its colors.
+
+1. **Size in `em`, never `rem`** — `rem` resolves against the host page's
+   root font size, which is arbitrary (`html { font-size: 8px }` breaks every
+   `rem` dimension). `em` stays self-consistent anywhere. Borders may stay
+   `px`.
+2. **Never hardcode colors, fonts, or radii** — read the brand CSS variables
+   GreatStore injects (`--color-primary`, `--color-surface`,
+   `--color-foreground`, `--color-border-default`, `--font-primary`,
+   `--radius-lg`, …) so the component restyles itself with the store's
+   theme. The scaffolded `AGENTS.md` has the full variable table.
+
+## Async components (backend-backed data)
+
+If a component must load data before it can render correctly, don't render a
+shell and fetch in `useEffect` — set `"async": true` in the manifest and
+export an **async** default. GreatStore shows its own loading state, awaits
+your promise, and renders what it resolves to.
+
+A thrown error is a **retry signal**: the assistant sees it and usually
+re-calls the tool. So only throw when a *different* call could help:
+
+1. Validate the AI-passed props first and throw on bad input — the AI can
+   fix the args and retry. (Don't validate the API's *output* and throw: the
+   AI can't fix your backend, it'll just loop.)
+2. Throw on failures where retrying differently could succeed, and say what
+   to change (e.g. empty search → `"no results for X — try a broader keyword"`).
+3. For idempotent failures (500, timeout, missing record) render a graceful
+   fallback instead of throwing — re-running the same call changes nothing.
+
+```tsx
+export default async function Results(props: Props) {
+  if (!props.query?.trim()) throw new Error("missing required prop: query");
+  const res = await fetch(`/api/search?q=${encodeURIComponent(props.query)}`);
+  if (res.ok) {
+    const { results } = await res.json();
+    if (results.length === 0)
+      throw new Error(`no results for "${props.query}" — try a broader keyword`);
+    return <ul>{/* render results */}</ul>;
+  }
+  return <p>Couldn't load results right now.</p>; // idempotent: don't throw
+}
+```
+
+## When to build a component vs. the other facets
+
+- Content for the **merchant's page** → `window.GreatStore.generateStructuredContent`
+  ([structured-content.md](structured-content.md)). Inside a chat component, use
+  the injected `onGenerateStructuredContent` prop instead — same idea, but
+  personalized to the shopper and available on every surface without the global.
+- Letting the assistant **act on the page** → WebMCP page tools
+  ([embed-api.md](embed-api.md)).
+- Rich, interactive UI **inside the conversation itself**, available on the
+  storefront and every embed without page changes → a chat component.