@greatstore/cli 0.0.19 → 0.0.21

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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
+- `gs pull`, `gs push`, and `gs publish` now accept several component
+  names at once (e.g. `gs publish header footer cart`). Each component
+  is reported on its own line and one failure no longer stops the rest.
+
 ## 0.0.19 — 2026-05-28
 
 ### Fixed

package/dist/cli.js

@@ -632,21 +632,32 @@ function safeComputeHashes(componentDir) {
 async function pullCommand(args) {
   const slug = requireProjectStore();
   const force = flagBool(args.flags, "force");
-  const target = args.positional[0];
+  const targets = args.positional;
   const root = process.cwd();
-  if (!target || target === "*") {
+  if (targets.length === 0 || targets.length === 1 && targets[0] === "*") {
     return pullAll({ slug, root, args, force });
   }
+  if (targets.length > 1 && flagString(args.flags, "version")) {
+    throw new Error(
+      "--version is per-component; pass it together with a single `gs pull <name>`."
+    );
+  }
   ensureComponentsDir(root);
-  const outcome = await pullOne({
-    slug,
-    componentDir: path4.join(root, "components", target),
-    name: target,
-    revisionQuery: buildRevisionQuery(args),
-    force
-  });
-  printOutcome(outcome, force);
-  if (outcome.status === "failed") process.exitCode = 1;
+  const revisionQuery = buildRevisionQuery(args);
+  const outcomes = [];
+  for (const name of targets) {
+    const outcome = await pullOne({
+      slug,
+      componentDir: path4.join(root, "components", name),
+      name,
+      revisionQuery,
+      force
+    });
+    outcomes.push(outcome);
+    printOutcome(outcome, force);
+  }
+  if (outcomes.length > 1) printPullSummary(outcomes, slug);
+  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
 }
 async function pullAll(opts) {
   const { slug, root, args, force } = opts;
@@ -677,6 +688,10 @@ async function pullAll(opts) {
     outcomes.push(outcome);
     printOutcome(outcome, force);
   }
+  printPullSummary(outcomes, slug);
+  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
+}
+function printPullSummary(outcomes, slug) {
   const pulled = outcomes.filter((o) => o.status === "pulled").length;
   const skipped = outcomes.filter((o) => o.status === "skipped").length;
   const failed = outcomes.filter((o) => o.status === "failed").length;
@@ -687,7 +702,6 @@ async function pullAll(opts) {
 ${summary.join(", ")} (of ${outcomes.length}) \u2190 ${slug}
 `
   );
-  if (failed > 0) process.exitCode = 1;
 }
 async function pullOne(opts) {
   const { slug, componentDir, name, revisionQuery, force } = opts;
@@ -783,25 +797,30 @@ async function pushCommand(args) {
       "No components/ directory here. Run `gs init <name>` to scaffold the project root and your first component."
     );
   }
-  const named = args.positional[0];
+  const named = args.positional;
   const manifestOverride = flagString(args.flags, "manifest");
   const bundleOverride = flagString(args.flags, "bundle");
-  if (!named && (manifestOverride || bundleOverride)) {
+  if (named.length !== 1 && (manifestOverride || bundleOverride)) {
     throw new Error(
-      "--manifest / --bundle can only be used together with `gs push <name>`."
+      "--manifest / --bundle can only be used together with a single `gs push <name>`."
     );
   }
-  if (named) {
-    const outcome = await pushOne({
-      slug,
-      root,
-      name: named,
-      ...manifestOverride !== void 0 ? { manifestPath: manifestOverride } : {},
-      ...bundleOverride !== void 0 ? { bundlePath: bundleOverride } : {},
-      force: true
-    });
-    printOutcome2(outcome);
-    if (outcome.status === "failed") process.exitCode = 1;
+  if (named.length > 0) {
+    const outcomes2 = [];
+    for (const name of named) {
+      const outcome = await pushOne({
+        slug,
+        root,
+        name,
+        ...manifestOverride !== void 0 ? { manifestPath: manifestOverride } : {},
+        ...bundleOverride !== void 0 ? { bundlePath: bundleOverride } : {},
+        force: true
+      });
+      outcomes2.push(outcome);
+      printOutcome2(outcome);
+    }
+    if (outcomes2.length > 1) printPushSummary(outcomes2, slug);
+    if (outcomes2.some((o) => o.status === "failed")) process.exitCode = 1;
     return;
   }
   const names = listLocalComponents(componentsDir);
@@ -817,6 +836,10 @@ async function pushCommand(args) {
     outcomes.push(outcome);
     printOutcome2(outcome);
   }
+  printPushSummary(outcomes, slug);
+  if (outcomes.some((o) => o.status === "failed")) process.exitCode = 1;
+}
+function printPushSummary(outcomes, slug) {
   const pushed = outcomes.filter((o) => o.status === "pushed").length;
   const unchanged = outcomes.filter((o) => o.status === "unchanged").length;
   const failed = outcomes.filter((o) => o.status === "failed").length;
@@ -825,7 +848,6 @@ async function pushCommand(args) {
   process.stdout.write(`
 ${summary.join(", ")} (of ${outcomes.length}) \u2192 ${slug}
 `);
-  if (failed > 0) process.exitCode = 1;
 }
 async function pushOne(opts) {
   const { slug, root, name, force } = opts;
@@ -964,24 +986,83 @@ function printOutcome2(outcome) {
 
 // src/commands/publish.ts
 async function publishCommand(args) {
-  const name = args.positional[0];
-  if (!name) throw new Error("Usage: gs publish <name> [--version N]");
+  const names = args.positional;
+  if (names.length === 0) {
+    throw new Error("Usage: gs publish <name> [<name>...] [--version N]");
+  }
   const slug = requireProjectStore();
-  const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}/publish`;
   const versionFlag = flagString(args.flags, "version");
-  let body = void 0;
+  let version;
   if (versionFlag !== void 0) {
+    if (names.length > 1) {
+      throw new Error(
+        "--version is per-component; pass it together with a single `gs publish <name>`."
+      );
+    }
     const n = Number.parseInt(versionFlag, 10);
     if (!Number.isInteger(n) || n < 1) {
       throw new Error(`Invalid --version: ${versionFlag}`);
     }
-    body = { version: n };
-  } else {
-    body = {};
+    version = n;
   }
-  const data = await request(url, { method: "POST", body });
-  process.stdout.write(`Published ${name} (v${data.live_version}). ${data.permalink}
-`);
+  if (names.length === 1) {
+    const name = names[0];
+    const data = await publish(slug, name, version);
+    process.stdout.write(
+      `Published ${name} (v${data.live_version}). ${data.permalink}
+`
+    );
+    return;
+  }
+  const outcomes = [];
+  for (const name of names) {
+    let outcome;
+    try {
+      const data = await publish(slug, name, version);
+      outcome = {
+        name,
+        status: "published",
+        version: data.live_version,
+        permalink: data.permalink
+      };
+    } catch (err) {
+      outcome = {
+        name,
+        status: "failed",
+        message: err instanceof Error ? err.message : String(err)
+      };
+    }
+    outcomes.push(outcome);
+    printOutcome3(outcome);
+  }
+  const published = outcomes.filter((o) => o.status === "published").length;
+  const failed = outcomes.filter((o) => o.status === "failed").length;
+  const summary = [`${published} published`];
+  if (failed > 0) summary.push(`${failed} failed`);
+  process.stdout.write(
+    `
+${summary.join(", ")} (of ${outcomes.length}) \u2192 ${slug}
+`
+  );
+  if (failed > 0) process.exitCode = 1;
+}
+async function publish(slug, name, version) {
+  const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}/publish`;
+  const body = version !== void 0 ? { version } : {};
+  return request(url, { method: "POST", body });
+}
+function printOutcome3(outcome) {
+  if (outcome.status === "published") {
+    process.stdout.write(
+      `  published ${outcome.name} v${outcome.version} \u2192 ${outcome.permalink ?? ""}
+`
+    );
+    return;
+  }
+  process.stdout.write(
+    `  failed    ${outcome.name}: ${outcome.message ?? "unknown error"}
+`
+  );
 }
 
 // src/commands/unpublish.ts
@@ -1179,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 {
@@ -1196,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() {
@@ -1594,8 +1701,8 @@ function parseVer(v) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.0.19" : "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.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:
@@ -1608,9 +1715,9 @@ Commands:
   init [<name>]                  Scaffold project root; add \`components/<name>/\` if name given.
   build [<name>]                  Build component bundle(s) via the project's Vite. No args = all.
   list                           List components in the current store.
-  pull [<name>|*]                Download remote component(s) into \`components/<name>/\`. No args = all.
-  push [<name>]                  Upload changed components from \`components/\`. No args = all (skips unchanged).
-  publish <name>                 Promote the draft (or --version N) to live.
+  pull [<name>...|*]             Download remote component(s) into \`components/<name>/\`. No args = all.
+  push [<name>...]               Upload changed components from \`components/\`. No args = all (skips unchanged).
+  publish <name>...              Promote the draft(s) (or --version N) to live.
   unpublish <name>               Clear the live pointer.
   delete <name>                  Soft-delete the component.
 

package/package.json

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