@greatstore/cli 0.0.20 → 0.0.21

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to `@greatstore/cli` are recorded here. The format
 follows [Keep a Changelog](https://keepachangelog.com/).
 
+## 0.0.21 — 2026-05-31
+
+### Changed
+- The `gs init` component scaffold now shows how to write **async**
+  components that load data before they render — including validating
+  inputs up front and signalling a failure by throwing. The scaffolded
+  component no longer includes an `onError` prop; throw from an async
+  component to report a failure instead.
+
 ## 0.0.20 — 2026-05-29
 
 ### Added

package/dist/cli.js

@@ -1260,14 +1260,6 @@ interface Props {
   // Dismiss the host slot (over-input clears the overlay, fullscreen
   // reverts the pane, inline is a no-op).
   onClose: () => void;
-  // Tell the in-store AI something went wrong so it can apologize or
-  // self-correct on its next turn. Use for *expected* failures inside
-  // async handlers (failed fetch, host-page action rejected, invalid
-  // host state). Render-time crashes are caught and reported for you
-  // \u2014 you don't need a try/catch just to forward exceptions. The
-  // message is read by the AI, not the shopper, so write it like a
-  // short engineering note.
-  onError: (message: string) => void;
 }
 
 export default function ${pascal(name)}(_props: Props): React.ReactElement {
@@ -1277,6 +1269,40 @@ export default function ${pascal(name)}(_props: Props): React.ReactElement {
     </div>
   );
 }
+
+// ---- Async components (backend-backed, render-blocking data) ----
+// If this component must load data from a backend/API before it can
+// render correctly, make it async \u2014 don't render an empty shell and
+// fetch in a useEffect. Set "async": true in manifest.json and export
+// an async default. GreatStore waits for your promise (showing a normal
+// loading state, so you don't render your own placeholder), then renders
+// what it resolves to.
+//
+// A thrown error is a RETRY SIGNAL: the in-store AI sees it and usually
+// re-calls the tool. So only throw when a *different* call could help.
+//   1. await the backend call, then return the finished JSX.
+//   2. Validate the AI-passed props first and throw on bad input \u2014 the
+//      AI can fix the args and retry. (Don't validate the API's output
+//      and throw: the AI can't fix the backend, it'll just loop.)
+//   3. Broadcast a backend failure ONLY when retrying differently could
+//      succeed, and say what to change (e.g. empty search \u2192 "try a
+//      broader keyword"). For idempotent failures (500, timeout, missing
+//      record) re-running the same call changes nothing \u2014 render a
+//      graceful fallback instead of throwing.
+//
+//   export default async function ${pascal(name)}(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}" \u2014 try a broader keyword\`);
+//       return <ul>{/* render results */}</ul>;
+//     }
+//     return <p>Couldn't load results right now.</p>; // idempotent: don't throw
+//   }
+//
+// Components that render purely from their props stay synchronous.
 `;
 }
 function viteEditorConfig() {
@@ -1675,8 +1701,8 @@ function parseVer(v) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.0.20" : "0.0.0-dev";
-var CHANGELOG = true ? '# Changelog\n\nAll notable changes to `@greatstore/cli` are recorded here. The format\nfollows [Keep a Changelog](https://keepachangelog.com/).\n\n## 0.0.20 \u2014 2026-05-29\n\n### Added\n- `gs pull`, `gs push`, and `gs publish` now accept several component\n  names at once (e.g. `gs publish header footer cart`). Each component\n  is reported on its own line and one failure no longer stops the rest.\n\n## 0.0.19 \u2014 2026-05-28\n\n### Fixed\n- `gs login` on Windows no longer opens a sign-in URL with parameters\n  stripped, which surfaced as a "Missing redirect_uri or state\n  parameter" page in the browser.\n\n## 0.0.18 \u2014 2026-05-28\n\n### Changed\n- Push and publish errors now name the specific reason \u2014 including\n  every failing field in `manifest.json` \u2014 instead of the previous\n  generic message.\n\n## 0.0.17 \u2014 2026-05-28\n\n### Added\n- Each command now prints a one-line upgrade notice when a newer\n  `@greatstore/cli` is available on npm.\n\n## 0.0.16 \u2014 2026-05-28\n\n### Changed\n- Simplified error messages.\n\n## 0.0.15 \u2014 2026-05-24\n\n### Added\n- Scaffolded `component.tsx` now declares the four injected lifecycle\n  props (`onSendMessage`, `onCallTool`, `onClose`, `onError`) on\n  `Props`. Use `onError(message)` to report expected failures (failed\n  fetch, host action rejected, invalid host state) so the AI can\n  recover on its next turn. Render-time crashes are reported for you.\n\n## 0.0.14 \u2014 2026-05-24\n\n### Changed\n- `gs build` output is now whitespace-minified \u2014 typically ~50% smaller.\n\n## 0.0.13 \u2014 2026-05-24\n\n### Changed\n- `gs build` prints the next-step hint (`gs push`, then `gs publish`).\n\n## 0.0.12 \u2014 2026-05-24\n\n### Fixed\n- `gs build` failing to load Vite in some setups.\n\n## 0.0.11 \u2014 2026-05-24\n\n### Added\n- Multi-component projects. `gs init` (no args) scaffolds the project\n  root; `gs init <name>` adds a component under `components/<name>/`.\n- `gs build [<name>]` \u2014 compiles every `components/<name>/bundle.js`.\n- `gs push` (no args) uploads only the components that changed.\n- `gs pull` (no args, or `*`) downloads every component. Locally\n  edited components are skipped; pass `--force` to overwrite.\n- Public `CHANGELOG.md`; `gs --version` prints recent entries.\n\n### Changed\n- A project folder ships to exactly one store. Only `gs init` accepts\n  `--store`; every other command reads the slug from `.gsrc`. The old\n  single-component layout is rejected with a migration hint.\n- `gs init` requires `--store <slug>` for a fresh root, and rejects\n  `--store` on an existing root.\n- `gs init` no longer writes `build.mjs` \u2014 scripts call `gs build`.\n\n## 0.0.10 \u2014 2026-05-23\n\n### Changed\n- The sign-in browser tab auto-closes once `gs login` finishes.\n\n## 0.0.9 \u2014 2026-05-23\n\n### Changed\n- Scaffolded manifests include a `displayName` so the admin UI has a\n  friendlier label.\n\n## 0.0.8 \u2014 2026-05-23\n\n### Changed\n- `gs push` and `gs publish` print a link to view the component.\n\n## 0.0.6 \u2014 2026-05-23\n\n### Changed\n- `gs --version` reads from the published package version.\n\n## 0.0.4 \u2014 2026-05-23\n\n### Changed\n- Scaffolded projects produce browser-ready bundles out of the box.\n\n## 0.0.3 \u2014 2026-05-23\n\n### Changed\n- Trimmed public README to the essentials.\n\n## 0.0.2 \u2014 2026-05-23\n\n### Fixed\n- Sign-in callback parameter handling.\n' : "";
+var VERSION = true ? "0.0.21" : "0.0.0-dev";
+var CHANGELOG = true ? '# Changelog\n\nAll notable changes to `@greatstore/cli` are recorded here. The format\nfollows [Keep a Changelog](https://keepachangelog.com/).\n\n## 0.0.21 \u2014 2026-05-31\n\n### Changed\n- The `gs init` component scaffold now shows how to write **async**\n  components that load data before they render \u2014 including validating\n  inputs up front and signalling a failure by throwing. The scaffolded\n  component no longer includes an `onError` prop; throw from an async\n  component to report a failure instead.\n\n## 0.0.20 \u2014 2026-05-29\n\n### Added\n- `gs pull`, `gs push`, and `gs publish` now accept several component\n  names at once (e.g. `gs publish header footer cart`). Each component\n  is reported on its own line and one failure no longer stops the rest.\n\n## 0.0.19 \u2014 2026-05-28\n\n### Fixed\n- `gs login` on Windows no longer opens a sign-in URL with parameters\n  stripped, which surfaced as a "Missing redirect_uri or state\n  parameter" page in the browser.\n\n## 0.0.18 \u2014 2026-05-28\n\n### Changed\n- Push and publish errors now name the specific reason \u2014 including\n  every failing field in `manifest.json` \u2014 instead of the previous\n  generic message.\n\n## 0.0.17 \u2014 2026-05-28\n\n### Added\n- Each command now prints a one-line upgrade notice when a newer\n  `@greatstore/cli` is available on npm.\n\n## 0.0.16 \u2014 2026-05-28\n\n### Changed\n- Simplified error messages.\n\n## 0.0.15 \u2014 2026-05-24\n\n### Added\n- Scaffolded `component.tsx` now declares the four injected lifecycle\n  props (`onSendMessage`, `onCallTool`, `onClose`, `onError`) on\n  `Props`. Use `onError(message)` to report expected failures (failed\n  fetch, host action rejected, invalid host state) so the AI can\n  recover on its next turn. Render-time crashes are reported for you.\n\n## 0.0.14 \u2014 2026-05-24\n\n### Changed\n- `gs build` output is now whitespace-minified \u2014 typically ~50% smaller.\n\n## 0.0.13 \u2014 2026-05-24\n\n### Changed\n- `gs build` prints the next-step hint (`gs push`, then `gs publish`).\n\n## 0.0.12 \u2014 2026-05-24\n\n### Fixed\n- `gs build` failing to load Vite in some setups.\n\n## 0.0.11 \u2014 2026-05-24\n\n### Added\n- Multi-component projects. `gs init` (no args) scaffolds the project\n  root; `gs init <name>` adds a component under `components/<name>/`.\n- `gs build [<name>]` \u2014 compiles every `components/<name>/bundle.js`.\n- `gs push` (no args) uploads only the components that changed.\n- `gs pull` (no args, or `*`) downloads every component. Locally\n  edited components are skipped; pass `--force` to overwrite.\n- Public `CHANGELOG.md`; `gs --version` prints recent entries.\n\n### Changed\n- A project folder ships to exactly one store. Only `gs init` accepts\n  `--store`; every other command reads the slug from `.gsrc`. The old\n  single-component layout is rejected with a migration hint.\n- `gs init` requires `--store <slug>` for a fresh root, and rejects\n  `--store` on an existing root.\n- `gs init` no longer writes `build.mjs` \u2014 scripts call `gs build`.\n\n## 0.0.10 \u2014 2026-05-23\n\n### Changed\n- The sign-in browser tab auto-closes once `gs login` finishes.\n\n## 0.0.9 \u2014 2026-05-23\n\n### Changed\n- Scaffolded manifests include a `displayName` so the admin UI has a\n  friendlier label.\n\n## 0.0.8 \u2014 2026-05-23\n\n### Changed\n- `gs push` and `gs publish` print a link to view the component.\n\n## 0.0.6 \u2014 2026-05-23\n\n### Changed\n- `gs --version` reads from the published package version.\n\n## 0.0.4 \u2014 2026-05-23\n\n### Changed\n- Scaffolded projects produce browser-ready bundles out of the box.\n\n## 0.0.3 \u2014 2026-05-23\n\n### Changed\n- Trimmed public README to the essentials.\n\n## 0.0.2 \u2014 2026-05-23\n\n### Fixed\n- Sign-in callback parameter handling.\n' : "";
 var HELP = `gs \u2014 GreatStore CLI (v${VERSION})
 
 Usage:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@greatstore/cli",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "CLI for authoring and shipping GreatStore custom components.",
   "license": "UNLICENSED",
   "type": "module",