npm - @greatstore/cli - Versions diffs - 0.1.1 → 0.1.4 - Mend

@greatstore/cli 0.1.1 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/CHANGELOG.md +32 -0
package/README.md +15 -16
package/dist/cli.js +422 -141
package/dist/gs-skill/SKILL.md +83 -0
package/dist/gs-skill/recipes/ask-about-this.md +31 -0
package/dist/gs-skill/recipes/campaign-hero.md +43 -0
package/dist/gs-skill/recipes/comparison-table.md +80 -0
package/dist/gs-skill/recipes/complete-the-look.md +59 -0
package/dist/gs-skill/recipes/custom-chat-button.md +25 -0
package/dist/gs-skill/recipes/gift-finder-funnel.md +97 -0
package/dist/gs-skill/recipes/launchers.md +109 -0
package/dist/gs-skill/recipes/page-action-suite.md +90 -0
package/dist/gs-skill/recipes/product-faq.md +58 -0
package/dist/gs-skill/references/agents-and-mcp.md +35 -0
package/dist/gs-skill/references/chat-components.md +224 -0
package/dist/gs-skill/references/embed-api.md +381 -0
package/dist/gs-skill/references/push-notifications.md +66 -0
package/dist/gs-skill/references/store-admin.md +131 -0
package/dist/gs-skill/references/structured-content.md +252 -0
package/package.json +1 -1

package/dist/gs-skill/references/embed-api.md ADDED Viewed

@@ -0,0 +1,381 @@
+# `window.GreatStore` API reference
+## Setup
+```html
+<script src="https://my-store.greatstore.ai/embed.js"></script>
+```
+One script tag, anywhere on the page (end of `<body>` preferred), with the
+store's slug in the host. The `window.GreatStore` object exists synchronously
+once the script executes; every method below is safe to call before the chat
+UI has finished loading — pre-mount calls are queued and replayed in order
+once it mounts. The SDK pre-warms its chat bundle in the background
+automatically; the panel stays closed until `open()` / `toggle()` /
+`sendMessage()` is called or the shopper clicks the launcher.
+Requirements:
+- The page's domain must be in the store's **allowed domains** (GreatStore
+  store settings) — see Troubleshooting below for the failure signature.
+- If the store also wants push notifications, host `gs.js` at the site root
+  and load that instead of `embed.js` — it injects the embed for you. See
+  [push-notifications.md](push-notifications.md).
+Code samples throughout are framework-free reference implementations —
+re-express them in the host repo's framework (React, Vue, Shopify Liquid,
+…) rather than retrofitting them as-is. **Using React?** `@greatstore/react`
+wraps all of this in a `<GreatStore>` component with typed props (no
+`data-*` attribute quoting) and clean mount/unmount for SPA routing —
+`npm install @greatstore/react`.
+## Appearance overrides
+The store's configured appearance (theme colors, fonts, roundedness, panel
+position, mobile bar, AI disclaimer) is the default everywhere. To make the
+embed look or behave differently on a specific page — e.g. matching a
+campaign landing page's palette — set `data-*` attributes on the embed
+script tag. Every attribute is optional; anything you don't set falls back
+to the store's configured value.
+```html
+<script
+  src="https://my-store.greatstore.ai/embed.js"
+  data-theme-mode="dark"
+  data-theme-radius="rounded"
+  data-theme-panel-position="right"
+  data-theme-mobile-bar="false"
+  data-z-index="9999"
+  data-theme-brand-color="#1a1a2e"
+  data-theme-surface-color="#ffffff"
+  data-theme-text-color="#111111"
+  data-theme-font="Inter, sans-serif"
+  data-ai-disclaimer="false"
+></script>
+```
+| Attribute | Values | Overrides |
+|---|---|---|
+| `data-theme-mode` | `auto` \| `light` \| `dark` \| `custom` | Color scheme. |
+| `data-theme-radius` | `sharp` \| `default` \| `rounded` | Corner roundedness. |
+| `data-theme-panel-position` | `left` \| `right` \| `middle` | Desktop panel placement. |
+| `data-theme-mobile-bar` | `true` \| `false` | Whether the collapsed mobile bar shows. |
+| `data-z-index` | integer, `0`–`2147483647` | Stacking order of the chat overlay on your page. Lower it if something on the page must stay above the chat. |
+| `data-theme-font` | CSS font-family string | Primary font. |
+| `data-theme-font-secondary` | CSS font-family string | Secondary font. |
+| `data-theme-brand-color` | any CSS color | Brand/primary color (only used in `custom` mode). |
+| `data-theme-surface-color` | any CSS color | Surface/background color (only used in `custom` mode). |
+| `data-theme-text-color` | any CSS color | Text color (only used in `custom` mode). |
+| `data-ai-disclaimer` | `true` \| `false` | Shows or hides the AI disclaimer line. |
+| `data-ai-disclaimer-text` | string, up to 200 chars | Custom disclaimer message (implies shown, unless `data-ai-disclaimer="false"` is also set). |
+Not overridable this way: display name, assistant name, logo, and icons —
+those stay whatever's configured in the store's admin.
+Invalid values (unrecognized enum, malformed color, disallowed font
+characters) are silently ignored and fall back to the configured default.
+## Properties
+| Property | Type | Description |
+|---|---|---|
+| `slug` | `string` | The store identifier the script was loaded for. |
+| `host` | `string` | `"greatstore.ai"`. |
+| `embedHost` | `string` | Origin the embed assets load from, e.g. `https://<slug>.greatstore.ai`. |
+| `ready` | `Promise<void>` | Resolves when the chat UI has mounted and `open()` would render instantly. Resolved promises replay, so `.then()` works no matter when it's attached. The readiness signal to gate on. |
+A `greatstore:ready` `CustomEvent` (with the SDK object as `detail`) is also
+dispatched on `window` at the moment `ready` resolves, for declarative
+tooling. Unlike the promise, the listener must be attached before mount
+completes — attach it before (or immediately after) the embed script tag.
+## Methods
+### `load(): void`
+Pre-warms the chat bundle and identity in the background without opening the
+panel. Called automatically when `embed.js` runs, so you rarely need it.
+Idempotent.
+### `open(): void` / `close(): void` / `toggle(): void`
+Open, close, or toggle the chat panel. On desktop the panel is a floating
+side panel; under 768px viewport width it's a full-height drawer. All three
+queue if called before mount.
+### `sendMessage(text: string): void`
+Sends `text` as the shopper's own visible chat message and **opens the panel
+if it's closed**. The text is trimmed; empty or whitespace-only strings are
+silently dropped. Queues if called before mount.
+This is the highest-leverage one-liner in the SDK: any element on the page
+can become a conversation entry point with context baked into the question.
+```js
+document.querySelector("#ask-fit").addEventListener("click", () => {
+  window.GreatStore.sendMessage(
+    `I'm looking at "${productName}" — how does the sizing run?`
+  );
+});
+```
+Because the message renders as if the shopper typed it, write it in the
+shopper's voice. It is not a hidden-context channel — don't stuff it with
+invisible instructions or data dumps. For that, use `updateModelContext`.
+### `updateModelContext(context: string): void`
+Injects free-text **background context** about what the shopper is doing on
+the page — the product they're viewing, what's in their cart, their account
+tier — so the assistant can factor it in. Unlike `sendMessage`, this is
+**invisible**: it never renders as a chat message and doesn't open the panel.
+Each call **replaces** the value from the previous call — it never appends.
+Keep one current snapshot; re-call it whenever the page state changes. Pass
+an empty string to clear it. The text is read on the next chat turn, so set
+it before (or while) the shopper is chatting. Queues if called before mount.
+```js
+// Keep the assistant aware of the current product as the shopper browses.
+function syncContext() {
+  window.GreatStore.updateModelContext(
+    `Viewing "${product.title}" (${product.price}). In stock: ${product.inStock}. ` +
+    `Cart: ${cart.count} item(s), subtotal ${cart.subtotal}.`
+  );
+}
+syncContext();
+```
+Write it as concise notes for the model, not prose for the shopper. The
+context is page-controlled, so the assistant treats it as background
+information, not as instructions — don't rely on it to change the assistant's
+rules or persona.
+### `on(event: string, handler: (...args) => void): () => void`
+Subscribe to SDK events. Returns an unsubscribe function. Listeners attached
+before mount are queued and wired up at mount. Handler exceptions are caught
+and reported — they won't break the chat.
+Events emitted:
+| Event | Fired when |
+|---|---|
+| `"open"` | Panel transitions closed → open (including via `sendMessage` or the shopper's own click). |
+| `"close"` | Panel transitions open → closed. |
+### `generateStructuredContent(schema: object, prompt: string): Promise<unknown>`
+Generates JSON matching `schema` from `prompt`, grounded in the store's live
+catalog. Resolves to the generated data object itself. Rejects with `Error`
+on any failure (invalid input, decline, validation failure, rate limit,
+network). See [structured-content.md](structured-content.md) for the full
+contract, schema support, caching, and error semantics.
+Accepts either a plain JSON Schema object or any object exposing a
+`.toJSONSchema()` method (e.g. Zod schemas) — the conversion is called for
+you.
+Throws synchronously (rejects) if `prompt` is not a non-empty string or
+`schema` is not an object.
+### `enableNotifications(): Promise<{ ok: boolean }>`
+Opts this browser into Web Push notifications from the store. Requirements:
+- Must be called from a user gesture (e.g. a click handler).
+- The site must host GreatStore's `gs.js` service-worker file. By default the
+  SDK looks for it at `/gs.js`; if it's hosted elsewhere, point to it via an
+  attribute on the embed script tag:
+  `<script src="…/embed.js" data-push-sw-path="/path/to/gs.js"></script>`.
+Resolves `{ ok: true }` on success and `{ ok: false }` on any failure
+(unsupported browser, no service worker hosted, permission denied). It never
+rejects.
+### `destroy(): void`
+Fully tears down a mounted panel: unmounts the chat UI, closes any open voice
+connection, and removes the embed's DOM/listeners from the page. Use this
+when your page is done with the embed for good — e.g. a single-page app
+navigating away from the only route that should show it.
+No-ops (with a console warning) if nothing is mounted. The cached identity
+and downloaded chat bundle are kept, so a later `load()` (or any call that
+triggers a mount, like `open()`) mounts a fresh panel without a network
+round-trip for either. `ready` becomes a new pending promise at the moment
+`destroy()` is called, resolving again once the next mount completes:
+```js
+window.GreatStore.destroy();
+// ...later, on the page/route where the embed should come back:
+window.GreatStore.load();
+await window.GreatStore.ready; // resolves once the fresh mount is done
+```
+## Page tools — WebMCP (`document.modelContext`)
+The recommended way to expose page capabilities to the assistant is the
+WebMCP standard. The GreatStore assistant discovers every tool registered on
+`document.modelContext`, re-reading the list on each conversational turn —
+so tools registered mid-session appear on the next message without a reload.
+### Availability
+If the browser implements WebMCP natively, `document.modelContext` is just
+there. Otherwise the SDK installs a minimal fallback the instant `embed.js`
+starts running — synchronously, no async gap — so `document.modelContext`
+is normally available immediately. The embed script tag deliberately has no
+`async`/`defer` — a script with neither blocks parsing and runs at its own
+position, which matters if the page also has another script (a nav widget,
+an analytics tag) registering its own WebMCP tools: whichever executes
+first wins that registration, and only a synchronous, unconditionally-first
+script gives GreatStore's fallback shim a real chance of installing before
+one of those calls happens. That said, your own code can still end up on
+either side of two different races relative to `embed.js`, depending on
+where your script tag sits and whether it uses `async`/`defer` itself:
+- **Your script runs before `embed.js` has executed at all** — `window.GreatStore`
+  doesn't exist yet. `window.GreatStore?.ready` silently evaluates to
+  `undefined` here (optional chaining swallows it), so accessing `.then()`
+  on it throws or (written more defensively) just does nothing.
+- **Your script runs after `embed.js` has already mounted** — the
+  `greatstore:ready` event already fired once, in the past.
+  `window.addEventListener("greatstore:ready", ...)` attached now will
+  never see it: the event isn't replayed for late listeners, unlike a
+  resolved Promise (`.then()` on an already-resolved Promise still fires).
+Neither `.ready.then(...)` alone nor `addEventListener("greatstore:ready", ...)`
+alone is safe against both orderings. Use both, picking whichever is valid
+at the moment your code runs:
+```js
+function onGreatStoreReady(callback) {
+  if (window.GreatStore?.ready) {
+    // embed.js has already run — .then() on its ready Promise fires
+    // immediately if it already resolved, or once it does.
+    window.GreatStore.ready.then(() => callback(window.GreatStore));
+  } else {
+    // embed.js hasn't run yet — wait for the one-shot event it'll dispatch
+    // once it has. Safe to attach now: nothing can fire it between this
+    // check and the listener attaching, since JS execution isn't preemptible.
+    window.addEventListener(
+      "greatstore:ready",
+      (event) => callback(event.detail),
+      { once: true },
+    );
+  }
+}
+onGreatStoreReady(() => {
+  document.modelContext.registerTool(/* … */);
+});
+```
+(`navigator.modelContext` is a deprecated alias for the same object; use
+`document.modelContext` in new code.)
+### `registerTool(tool, options?)`
+```ts
+document.modelContext.registerTool(
+  {
+    name: string,                 // required, non-empty, unique on the page
+    description: string,          // required — how the AI decides when to call it
+    inputSchema?: object,         // JSON Schema for execute's args;
+                                  // defaults to { type: "object", properties: {} }
+    execute(args): Result | Promise<Result>,
+  },
+  options?: { signal?: AbortSignal },  // abort to unregister
+);
+```
+- **Result shape**: `execute` returns MCP content blocks —
+  `{ content: [{ type: "text", text: "…" }] }`. For structured data,
+  `JSON.stringify` it into `text`. Add `isError: true` to mark a handled
+  failure.
+- **Errors**: a thrown error or rejected promise is delivered to the
+  assistant as a *failed* tool call carrying the error message — the
+  assistant can explain or adapt. Errors never escape into your page.
+- **Duplicate names throw.** To replace a tool, abort its registration first.
+- **Unregistration is `AbortSignal`-driven**: pass `{ signal }` and call
+  `abort()` when the tool's context goes away (SPA navigation, modal close).
+  A pre-aborted signal skips registration. (A legacy
+  `unregisterTool(name)` exists but is deprecated in the spec.)
+- **Treat `args` as untrusted input**: values are AI-generated. Validate
+  before passing to your own APIs, and never `eval` anything from them.
+A complete tool, registered once GreatStore is ready (using the
+`onGreatStoreReady` helper defined above):
+```js
+onGreatStoreReady(() => {
+  document.modelContext.registerTool({
+    name: "add_to_cart",
+    description:
+      "Add a product variant to the shopper's cart on this site. " +
+      "Use when the shopper asks to add, buy, or get a product.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        variantId: { type: "string" },
+        quantity: { type: "integer", minimum: 1 },
+      },
+      required: ["variantId"],
+    },
+    async execute({ variantId, quantity }) {
+      const res = await fetch("/cart/add.js", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ id: variantId, quantity: quantity ?? 1 }),
+      });
+      if (!res.ok) throw new Error(`Cart add failed (${res.status})`);
+      const cart = await res.json();
+      return { content: [{ type: "text", text: JSON.stringify(cart) }] };
+    },
+  });
+});
+```
+Returning the fresh cart state after the mutation lets the assistant confirm
+accurately. Good tool families: cart (`get_cart`, `add_to_cart`), navigation
+(`go_to_page`), page state (`get_current_product`, `apply_filters`), UI
+(`highlight_section`, `scroll_to_reviews`).
+And a context-scoped tool, unregistered via `AbortSignal`:
+```js
+const ac = new AbortController();
+document.modelContext.registerTool(
+  {
+    name: "get_product_reviews",
+    description: "Read the reviews shown on the current product page.",
+    inputSchema: { type: "object", properties: {} },
+    execute: () => ({
+      content: [{ type: "text", text: JSON.stringify(collectReviews()) }],
+    }),
+  },
+  { signal: ac.signal },
+);
+// On SPA route change away from the product page:
+ac.abort();
+```
+## URL parameter: `?gs_chat=open`
+When the page URL carries `gs_chat=open`, the panel opens automatically once
+the embed mounts. The param is consumed and stripped from the URL via
+`history.replaceState`, so a manual reload doesn't re-open the panel. Use it
+in campaign links, emails, and post-login redirects.
+## Troubleshooting
+| Symptom | Likely cause |
+|---|---|
+| Console: `[GreatStore] Chat is unavailable on <origin>… this domain isn't in the store's allowed domains` | The page's origin isn't in the store's allowed domains. Add it in store settings. Until then every SDK network call fails. |
+| Console: `[GreatStore] Embed script must be loaded from <slug>.greatstore.ai/embed.js` | The script was copied/self-hosted instead of loaded from the store's embed URL. Always load it from `https://<slug>.greatstore.ai/embed.js`. |
+| `generateStructuredContent` rejects with a rate-limit message | More than ~20 requests/minute from one visitor. Consolidate calls into fewer, richer schemas. |
+| Panel won't auto-open on mobile after returning to the page | Intentional: the mobile drawer never auto-opens on resume — it would cover the content the shopper is reading. The transcript is preserved; they'll see it when they tap the launcher. |
+| Tools registered but the assistant doesn't use them | Check the `description` — it's the only signal for *when* to call. Also confirm the registration ran (`document.modelContext` exists after `ready`) on the same page the conversation is on. |

package/dist/gs-skill/references/push-notifications.md ADDED Viewed

@@ -0,0 +1,66 @@
+# Web push re-engagement
+Shoppers who opt in receive browser notifications from the store — under the
+merchant's own domain and branding, with the permission prompt shown inline
+on the merchant's page. Setup is two pieces: a single file hosted at the site
+root, and an opt-in button.
+## 1. Host `gs.js` at the site root
+Download the store's loader and serve it at `/gs.js` on the merchant's
+domain:
+```
+https://<slug>.greatstore.ai/gs.js   →   https://www.merchant-site.com/gs.js
+```
+Always download it from the **store's own subdomain** — the file is built for
+that store; don't copy one from elsewhere.
+Then load it with one tag (replacing the `embed.js` tag — `gs.js` injects the
+embed for you and registers itself as the service worker):
+```html
+<script src="/gs.js"></script>
+```
+Hosting this file is what enables push. Without it, push is simply off —
+`enableNotifications()` returns `{ ok: false }` and nothing else changes.
+### Non-root hosting
+If the platform can't serve files at the site root (e.g. Shopify themes
+serve assets under a path), keep the regular `embed.js` tag and point it at
+where the file lives — the path must be on the merchant's own origin:
+```html
+<script
+  src="https://my-store.greatstore.ai/embed.js"
+  data-push-sw-path="/cdn/shop/files/gs.js"
+></script>
+```
+## 2. Offer the opt-in from a user gesture
+```js
+optInButton.addEventListener("click", async () => {
+  const { ok } = await window.GreatStore.enableNotifications();
+  optInButton.hidden = ok;          // done — or quietly keep the button
+});
+```
+Rules that make this work well:
+- **Always call it from a click** — browsers ignore or penalize permission
+  prompts that aren't user-initiated, and the call is designed for gesture
+  context.
+- **Never prompt on page load.** Tie the button to a moment where
+  notifications have obvious value ("Notify me when this is back in stock",
+  post-purchase, after a chat conversation).
+- `{ ok: false }` covers every failure the same way — unsupported browser, no
+  `gs.js` hosted, permission denied. It never rejects, and there's no popup
+  fallback. Design the button so a decline just leaves the page as it was;
+  don't show an error.
+- The promise resolving `{ ok: true }` means this browser is subscribed.
+  There's nothing else to wire — notification delivery is handled by
+  GreatStore.

package/dist/gs-skill/references/store-admin.md ADDED Viewed

@@ -0,0 +1,131 @@
+# Store administration from the CLI
+The `gs` CLI is a full admin surface for a GreatStore store, mirroring the
+merchant's admin dashboard one-to-one: `gs configure` ↔ the Configure panel,
+`gs connectors` ↔ the Connectors panel, `gs apps` ↔ the Apps panel. Same
+fields, same behaviour — anything you change is what the merchant sees in
+their dashboard.
+That makes the CLI the way a coding agent grounds and unblocks its own work:
+read the store's configuration to make better decisions, and make the narrow
+class of additive, integration-enabling changes yourself instead of telling
+the user to go click through a dashboard.
+## Setup
+```
+npm install -g @greatstore/cli     # or npx @greatstore/cli <command>
+gs login                           # one-time browser sign-in (needs a human)
+```
+Credentials persist across runs. Admin commands take `--store <slug>`
+directly, or read the nearest `.gsrc` (`{"store":"my-store"}`) — so they work
+from any repo, not just a scaffolded component project. Every read supports
+`--json` for machine-readable output.
+## Read freely — always safe
+Reading store state is never destructive. Do it whenever it would improve a
+decision:
+```
+gs configure --store my-store --json     # brand config
+gs connectors --store my-store --json    # MCP connectors feeding the assistant
+gs connectors health --store my-store    # live-probe them (reports tool counts)
+gs apps list --store my-store --json     # deployed custom chat components
+```
+What each read is good for:
+- **`gs configure`** — the store's `extraOrigins` (is the site you're
+  integrating actually allowlisted? — see the embed troubleshooting note in
+  [embed-api.md](embed-api.md)), `theme` (match generated on-page UI to the
+  brand's colors/radius), `storeLink`, and CSP host lists.
+- **`gs connectors`** — which MCP connectors the assistant has, and whether
+  the Maker MCP is on. This tells you what the assistant can actually *do*:
+  check it before building features that lean on catalog data (e.g.
+  [structured content](structured-content.md) grounding), and before
+  registering WebMCP page tools that would duplicate a capability a
+  server-side connector already provides.
+- **`gs connectors health`** — a connector being listed doesn't mean it's
+  reachable; this probes each one live. Run it when assistant behaviour
+  suggests a tool isn't responding.
+## Safe to change without asking
+When the task the user gave you requires it, these changes are yours to
+make: they're additive, easy to undo, and invisible to shoppers.
+- **`extraOrigins`** — the origin allowlist for the embed. Installing the
+  widget on a new site/staging domain? Add that origin yourself instead of
+  reporting "ask the merchant to allowlist it".
+- **`cspScriptHosts` / `cspConnectHosts`** — hosts the storefront accepts
+  for scripts/connections. Add a host when a custom chat component
+  legitimately needs a third-party SDK or API.
+**List flags replace the stored list — always read-merge-write.** Fetch the
+current value, append yours, write the union:
+```
+gs configure --store my-store --json
+# extraOrigins is ["https://shop.example.com"] → write both, comma-separated:
+gs configure set --store my-store \
+  --extraOrigins "https://shop.example.com,https://staging.example.com"
+```
+Never drop an entry you didn't add, and say what you changed (and why) when
+you report back to the user.
+## Ask the merchant first
+Everything below is shopper-visible or changes what the live assistant can
+do for every shopper. Propose it, don't do it unprompted:
+- **Brand-visible config** — `displayName`, `assistantName`, `storeLink`,
+  `theme`, and asset uploads
+  (`gs configure upload|clear icon|logoLight|logoDark`).
+- **Connector mutations** — `gs connectors add|remove|enable|disable` and
+  `gs connectors maker on|off`. (`add` probes the connector for tool
+  discovery before saving and refuses if it doesn't answer; `--force`
+  overrides. Still: adding capabilities to the merchant's assistant is the
+  merchant's call.)
+- **Anything that clears** — passing `""` to empty a field, removing list
+  entries, `clear`ing assets.
+When the user has *explicitly asked* for one of these ("set the assistant's
+name to Voyager", "connect this MCP server"), that's the go-ahead — do it
+and confirm the result with a read.
+## Command reference
+```
+gs configure [--json]                      show configuration
+gs configure set --<field> <value>         displayName, assistantName,
+                                           storeLink, extraOrigins a,b,
+                                           cspScriptHosts a,b, cspConnectHosts a,b
+                                           ("" clears a field)
+gs configure set --theme.<field> <value>   one theme field, merged into the rest:
+                                           mode auto|light|dark|custom,
+                                           radius sharp|default|rounded,
+                                           panelPosition left|right|middle,
+                                           fontFamily, secondaryFontFamily,
+                                           mobileBottomBar true|false, zIndex,
+                                           brandColor/surfaceColor/textColor and
+                                           the fine-grained color tokens
+gs configure set --theme '<json>'          merge a whole object (--themeFile <path>);
+                                           --replace overwrites instead of merging
+gs configure set --help                    every field, its type and legal values
+gs configure upload <kind> <file>          icon | logoLight | logoDark (.png/.jpg/.webp)
+gs configure clear <kind>                  remove an uploaded asset
+gs connectors [--json]                     list Maker toggle + custom connectors
+gs connectors add <name> --url <url>       [--token <t>] [--profileUrl <u>]
+                                           [--disabled] [--force]
+gs connectors remove <name|id>
+gs connectors enable|disable <name|id>
+gs connectors maker on|off
+gs connectors health [<name|id>] [--json]
+gs apps <init|build|list|pull|push|publish|unpublish|delete>
+                                           see chat-components.md for the workflow
+```