@greatstore/cli 0.0.10 → 0.0.11-beta.1

package/README.md

@@ -11,6 +11,13 @@ gs push
 gs publish my-widget
 ```
 
+## Release channels
+
+- `npm install -g @greatstore/cli` — the stable production release (`@latest`).
+- `npm install -g @greatstore/cli@beta` — the prerelease channel for testing in-flight changes before they cut over to `@latest`.
+
+Cut a beta by bumping `cli/package.json` to `<x.y.z>-beta.<n>` (e.g. `0.0.12-beta.0`), then push tag `cli-v0.0.12-beta.0`. The publish workflow extracts the prerelease identifier from the version and publishes under that dist-tag, so `@latest` is unaffected. Drop the `-beta.<n>` suffix and tag again to promote to `@latest`.
+
 ## Commands
 
 | Command                                       | What it does                                                  |

package/dist/cli.js

@@ -92,7 +92,7 @@ async function captureLoopbackToken(options) {
   const open = options.openBrowser ?? ((url) => openInBrowser(url, options.browserCmdEnv));
   const server = http.createServer();
   try {
-    await new Promise((resolve5) => server.listen(0, "127.0.0.1", resolve5));
+    await new Promise((resolve4) => server.listen(0, "127.0.0.1", resolve4));
     const address = server.address();
     const redirectUri = `http://127.0.0.1:${address.port}${CALLBACK_PATH}`;
     const authUrl = `${options.navBaseUrl}/connect_oauth_done?redirect_uri=${encodeURIComponent(redirectUri)}&state=${encodeURIComponent(state)}`;
@@ -104,7 +104,7 @@ async function captureLoopbackToken(options) {
   }
 }
 function waitForCallback(server, expectedState, timeoutMs) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve4, reject) => {
     let settled = false;
     const settle = (fn) => {
       if (settled) return;
@@ -150,7 +150,7 @@ function waitForCallback(server, expectedState, timeoutMs) {
       res.writeHead(200, { "content-type": "text/html" });
       res.end(SUCCESS_HTML);
       clearTimeout(timer);
-      settle(() => resolve5({ token }));
+      settle(() => resolve4({ token }));
     });
   });
 }
@@ -273,16 +273,11 @@ var StoreResolutionError = class extends Error {
     this.name = "StoreResolutionError";
   }
 };
-function resolveStore(input = {}) {
-  const flag = input.flag?.trim();
-  if (flag) return flag;
+function requireProjectStore(input = {}) {
   const fromRc = findGsrc(input.cwd ?? process.cwd());
   if (fromRc) return fromRc;
-  const env = input.env ?? process.env;
-  const fromEnv = env.GS_STORE?.trim();
-  if (fromEnv) return fromEnv;
   throw new StoreResolutionError(
-    'No store selected. Pass `--store <slug>`, set GS_STORE, or create a .gsrc file with {"store":"..."}.'
+    "No .gsrc found in this directory or any ancestor. Run `gs init --store <slug>` first to scaffold a GreatStore project."
   );
 }
 function findGsrc(cwd) {
@@ -479,7 +474,7 @@ function whoamiCommand() {
 
 // src/commands/list.ts
 async function listCommand(args) {
-  const slug = resolveStore({ flag: flagString(args.flags, "store") });
+  const slug = requireProjectStore();
   const url = `${apiBaseFor(slug)}/api/builder/components`;
   const data = await request(url);
   if (flagBool(args.flags, "json")) {
@@ -516,34 +511,181 @@ function pad(s, width) {
 }
 
 // src/commands/pull.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+
+// src/sync.ts
+import * as crypto2 from "crypto";
 import * as fs3 from "fs";
 import * as path3 from "path";
-async function pullCommand(args) {
-  const name = args.positional[0];
-  if (!name) {
-    throw new Error("Usage: gs pull <name> [--draft|--live|--version N] [-o <dir>]");
+var SYNC_FILE = ".gssync.json";
+function hashString(text) {
+  return crypto2.createHash("sha256").update(text).digest("hex");
+}
+function hashFile(filePath) {
+  if (!fs3.existsSync(filePath)) return null;
+  return hashString(fs3.readFileSync(filePath, "utf8"));
+}
+function computeComponentHashes(componentDir) {
+  const manifestHash = hashFile(path3.join(componentDir, "manifest.json"));
+  if (manifestHash === null) {
+    throw new Error(`Missing manifest.json in ${componentDir}`);
   }
-  const slug = resolveStore({ flag: flagString(args.flags, "store") });
-  const out = flagString(args.flags, "out") ?? ".";
-  const query = buildRevisionQuery(args);
-  const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}${query}`;
-  const data = await request(url);
-  fs3.mkdirSync(out, { recursive: true });
+  return {
+    manifestHash,
+    sourceHash: hashFile(path3.join(componentDir, "component.tsx"))
+  };
+}
+function readSyncState(componentDir) {
+  const file = path3.join(componentDir, SYNC_FILE);
+  if (!fs3.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs3.readFileSync(file, "utf8"));
+    if (typeof parsed.version === "number" && typeof parsed.manifestHash === "string" && typeof parsed.sourceHash === "string") {
+      return {
+        version: parsed.version,
+        manifestHash: parsed.manifestHash,
+        sourceHash: parsed.sourceHash
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeSyncState(componentDir, state) {
   fs3.writeFileSync(
-    path3.join(out, "manifest.json"),
-    JSON.stringify(data.manifest, null, 2) + "\n"
+    path3.join(componentDir, SYNC_FILE),
+    JSON.stringify(state, null, 2) + "\n"
   );
-  fs3.writeFileSync(path3.join(out, "bundle.js"), data.bundle);
-  const wrote = ["manifest.json", "bundle.js"];
-  if (data.source !== null) {
-    fs3.writeFileSync(path3.join(out, "component.tsx"), data.source);
-    wrote.push("component.tsx");
+}
+function hasLocalChanges(componentDir, state) {
+  const hashes = safeComputeHashes(componentDir);
+  if (!hashes) return false;
+  if (state === null) return true;
+  if (hashes.manifestHash !== state.manifestHash) return true;
+  const localSource = hashes.sourceHash ?? "";
+  const storedSource = state.sourceHash ?? "";
+  return localSource !== storedSource;
+}
+function safeComputeHashes(componentDir) {
+  try {
+    return computeComponentHashes(componentDir);
+  } catch {
+    return null;
+  }
+}
+
+// src/commands/pull.ts
+async function pullCommand(args) {
+  const slug = requireProjectStore();
+  const force = flagBool(args.flags, "force");
+  const target = args.positional[0];
+  const root = process.cwd();
+  if (!target || target === "*") {
+    return pullAll({ slug, root, args, force });
   }
-  const sourceNote = data.source === null ? " (no source \u2014 this version was pushed without component.tsx)" : "";
+  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;
+}
+async function pullAll(opts) {
+  const { slug, root, args, force } = opts;
+  if (flagString(args.flags, "version")) {
+    throw new Error(
+      "--version is per-component; pass it together with `gs pull <name>`."
+    );
+  }
+  ensureComponentsDir(root);
+  const revisionQuery = buildRevisionQuery(args);
+  const listUrl = `${apiBaseFor(slug)}/api/builder/components`;
+  const list = await request(listUrl);
+  if (list.components.length === 0) {
+    process.stdout.write(`(no components in ${slug})
+`);
+    return;
+  }
+  const outcomes = [];
+  for (const entry of list.components) {
+    const componentDir = path4.join(root, "components", entry.name);
+    const outcome = await pullOne({
+      slug,
+      componentDir,
+      name: entry.name,
+      revisionQuery,
+      force
+    });
+    outcomes.push(outcome);
+    printOutcome(outcome, force);
+  }
+  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;
+  const summary = [`${pulled} pulled`, `${skipped} skipped`];
+  if (failed > 0) summary.push(`${failed} failed`);
   process.stdout.write(
-    `Pulled ${name} v${data.version} \u2192 ${path3.resolve(out)}/{${wrote.join(", ")}}${sourceNote}
+    `
+${summary.join(", ")} (of ${outcomes.length}) \u2190 ${slug}
 `
   );
+  if (failed > 0) process.exitCode = 1;
+}
+async function pullOne(opts) {
+  const { slug, componentDir, name, revisionQuery, force } = opts;
+  if (!force && fs4.existsSync(componentDir)) {
+    const sync = readSyncState(componentDir);
+    if (hasLocalChanges(componentDir, sync)) {
+      return {
+        name,
+        status: "skipped",
+        message: "local has uncommitted changes; pass --force to overwrite"
+      };
+    }
+  }
+  const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}${revisionQuery}`;
+  let data;
+  try {
+    data = await request(url);
+  } catch (err) {
+    return {
+      name,
+      status: "failed",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+  fs4.mkdirSync(componentDir, { recursive: true });
+  const manifestText = JSON.stringify(data.manifest, null, 2) + "\n";
+  fs4.writeFileSync(path4.join(componentDir, "manifest.json"), manifestText);
+  fs4.writeFileSync(path4.join(componentDir, "bundle.js"), data.bundle);
+  const wrote = ["manifest.json", "bundle.js"];
+  let sourceHash = "";
+  if (data.source !== null) {
+    fs4.writeFileSync(path4.join(componentDir, "component.tsx"), data.source);
+    wrote.push("component.tsx");
+    sourceHash = hashString(data.source);
+  }
+  writeSyncState(componentDir, {
+    version: data.version,
+    manifestHash: hashString(manifestText),
+    sourceHash
+  });
+  const onDisk = computeComponentHashes(componentDir);
+  writeSyncState(componentDir, {
+    version: data.version,
+    manifestHash: onDisk.manifestHash,
+    sourceHash: onDisk.sourceHash ?? ""
+  });
+  return { name, status: "pulled", version: data.version, wrote };
+}
+function ensureComponentsDir(root) {
+  fs4.mkdirSync(path4.join(root, "components"), { recursive: true });
 }
 function buildRevisionQuery(args) {
   const version = flagString(args.flags, "version");
@@ -552,65 +694,227 @@ function buildRevisionQuery(args) {
   if (flagBool(args.flags, "live")) return `?revision=live`;
   return "";
 }
+function printOutcome(outcome, force) {
+  switch (outcome.status) {
+    case "pulled": {
+      const files = outcome.wrote ? `{${outcome.wrote.join(", ")}}` : "";
+      process.stdout.write(
+        `  pulled    ${outcome.name} v${outcome.version} ${files}
+`
+      );
+      return;
+    }
+    case "skipped":
+      process.stdout.write(`  skipped   ${outcome.name}: ${outcome.message}
+`);
+      return;
+    case "failed":
+      process.stdout.write(
+        `  failed    ${outcome.name}: ${outcome.message ?? "unknown error"}
+`
+      );
+      return;
+  }
+  void force;
+}
 
 // src/commands/push.ts
-import * as fs4 from "fs";
-import * as path4 from "path";
+import * as fs5 from "fs";
+import * as path5 from "path";
 async function pushCommand(args) {
-  const slug = resolveStore({ flag: flagString(args.flags, "store") });
-  const manifestPath = path4.resolve(flagString(args.flags, "manifest") ?? "manifest.json");
-  const bundlePath = path4.resolve(flagString(args.flags, "bundle") ?? "bundle.js");
-  const sourcePath = path4.resolve(flagString(args.flags, "source") ?? "component.tsx");
-  if (!fs4.existsSync(manifestPath)) {
-    throw new Error(`Manifest not found: ${manifestPath}`);
+  const slug = requireProjectStore();
+  const root = process.cwd();
+  rejectLegacyLayout(root);
+  const componentsDir = path5.join(root, "components");
+  if (!fs5.existsSync(componentsDir)) {
+    throw new Error(
+      "No components/ directory here. Run `gs init <name>` to scaffold the project root and your first component."
+    );
+  }
+  const named = args.positional[0];
+  const manifestOverride = flagString(args.flags, "manifest");
+  const bundleOverride = flagString(args.flags, "bundle");
+  if (!named && (manifestOverride || bundleOverride)) {
+    throw new Error(
+      "--manifest / --bundle can only be used together with `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;
+    return;
   }
-  if (!fs4.existsSync(bundlePath)) {
-    throw new Error(`Bundle not found: ${bundlePath} (did you run \`npm run build\`?)`);
+  const names = listLocalComponents(componentsDir);
+  if (names.length === 0) {
+    process.stdout.write(
+      "(no components in ./components \u2014 run `gs init <name>` to add one)\n"
+    );
+    return;
   }
-  const manifestText = fs4.readFileSync(manifestPath, "utf8");
+  const outcomes = [];
+  for (const name of names) {
+    const outcome = await pushOne({ slug, root, name, force: false });
+    outcomes.push(outcome);
+    printOutcome2(outcome);
+  }
+  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;
+  const summary = [`${pushed} pushed`, `${unchanged} unchanged`];
+  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 pushOne(opts) {
+  const { slug, root, name, force } = opts;
+  const componentDir = path5.join(root, "components", name);
+  if (!fs5.existsSync(componentDir)) {
+    return {
+      name,
+      status: "failed",
+      message: `components/${name}/ does not exist`
+    };
+  }
+  const manifestPath = opts.manifestPath ? path5.resolve(opts.manifestPath) : path5.join(componentDir, "manifest.json");
+  const bundlePath = opts.bundlePath ? path5.resolve(opts.bundlePath) : path5.join(componentDir, "bundle.js");
+  const sourcePath = path5.join(componentDir, "component.tsx");
+  if (!fs5.existsSync(manifestPath)) {
+    return { name, status: "failed", message: `manifest not found: ${manifestPath}` };
+  }
+  if (!fs5.existsSync(bundlePath)) {
+    return {
+      name,
+      status: "failed",
+      message: `bundle not found: ${bundlePath} (did you run \`npm run build\`?)`
+    };
+  }
+  const manifestText = fs5.readFileSync(manifestPath, "utf8");
   let manifestName;
   try {
     const parsed = JSON.parse(manifestText);
     if (typeof parsed.name === "string") manifestName = parsed.name;
   } catch (err) {
-    throw new Error(`Manifest is not valid JSON: ${err.message}`);
-  }
-  const name = args.positional[0] ?? manifestName;
-  if (!name) {
-    throw new Error("Could not determine component name. Pass it positionally or set `name` in manifest.json.");
+    return {
+      name,
+      status: "failed",
+      message: `manifest is not valid JSON: ${err.message}`
+    };
   }
   if (manifestName && manifestName !== name) {
-    throw new Error(
-      `Manifest name "${manifestName}" does not match argument "${name}". The server will reject this.`
-    );
+    return {
+      name,
+      status: "failed",
+      message: `manifest name "${manifestName}" does not match folder name "${name}"`
+    };
+  }
+  if (!force) {
+    const hashes2 = computeComponentHashes(componentDir);
+    const sync = readSyncState(componentDir);
+    const unchanged = sync !== null && sync.manifestHash === hashes2.manifestHash && sync.sourceHash === (hashes2.sourceHash ?? "");
+    if (unchanged) {
+      return { name, status: "unchanged" };
+    }
   }
-  const bundleText = fs4.readFileSync(bundlePath, "utf8");
-  const sourceText = fs4.existsSync(sourcePath) ? fs4.readFileSync(sourcePath, "utf8") : null;
+  const bundleText = fs5.readFileSync(bundlePath, "utf8");
+  const sourceText = fs5.existsSync(sourcePath) ? fs5.readFileSync(sourcePath, "utf8") : null;
   const form = new FormData();
-  form.append("manifest", new Blob([manifestText], { type: "application/json" }), "manifest.json");
-  form.append("bundle", new Blob([bundleText], { type: "text/javascript" }), "bundle.js");
+  form.append(
+    "manifest",
+    new Blob([manifestText], { type: "application/json" }),
+    "manifest.json"
+  );
+  form.append(
+    "bundle",
+    new Blob([bundleText], { type: "text/javascript" }),
+    "bundle.js"
+  );
   if (sourceText !== null) {
     form.append(
       "source",
       new Blob([sourceText], { type: "text/plain; charset=utf-8" }),
-      path4.basename(sourcePath)
+      "component.tsx"
     );
   }
   const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}`;
-  const data = await request(url, { method: "POST", multipart: form });
-  const sourceNote = sourceText === null ? " (no source uploaded \u2014 `component.tsx` not found in cwd)" : "";
-  process.stdout.write(
-    `Pushed ${name} v${data.version} (draft) to ${slug}${sourceNote}. View: ${data.permalink}
-Run \`gs publish ${name}\` to promote.
+  let data;
+  try {
+    data = await request(url, { method: "POST", multipart: form });
+  } catch (err) {
+    return {
+      name,
+      status: "failed",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+  const hashes = computeComponentHashes(componentDir);
+  writeSyncState(componentDir, {
+    version: data.version,
+    manifestHash: hashes.manifestHash,
+    sourceHash: hashes.sourceHash ?? ""
+  });
+  return {
+    name,
+    status: "pushed",
+    version: data.version,
+    permalink: data.permalink
+  };
+}
+function listLocalComponents(componentsDir) {
+  return fs5.readdirSync(componentsDir).filter((entry) => {
+    const dir = path5.join(componentsDir, entry);
+    return fs5.statSync(dir).isDirectory() && fs5.existsSync(path5.join(dir, "manifest.json"));
+  }).sort();
+}
+function rejectLegacyLayout(root) {
+  const rootManifest = path5.join(root, "manifest.json");
+  const componentsDir = path5.join(root, "components");
+  if (fs5.existsSync(rootManifest) && !fs5.existsSync(componentsDir)) {
+    throw new Error(
+      [
+        "Detected the old single-component layout (manifest.json at the project root).",
+        "The Builder CLI now uses a multi-component layout: scaffold a fresh dir with",
+        "`gs init`, then move your component into `components/<name>/`. Re-run `gs push`",
+        "from the new project root."
+      ].join(" ")
+    );
+  }
+}
+function printOutcome2(outcome) {
+  switch (outcome.status) {
+    case "pushed":
+      process.stdout.write(
+        `  pushed    ${outcome.name} v${outcome.version} \u2192 ${outcome.permalink ?? ""}
 `
-  );
+      );
+      return;
+    case "unchanged":
+      process.stdout.write(`  unchanged ${outcome.name}
+`);
+      return;
+    case "failed":
+      process.stdout.write(
+        `  failed    ${outcome.name}: ${outcome.message ?? "unknown error"}
+`
+      );
+      return;
+  }
 }
 
 // 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 slug = resolveStore({ flag: flagString(args.flags, "store") });
+  const slug = requireProjectStore();
   const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}/publish`;
   const versionFlag = flagString(args.flags, "version");
   let body = void 0;
@@ -634,7 +938,7 @@ async function publishCommand(args) {
 async function unpublishCommand(args) {
   const name = args.positional[0];
   if (!name) throw new Error("Usage: gs unpublish <name>");
-  const slug = resolveStore({ flag: flagString(args.flags, "store") });
+  const slug = requireProjectStore();
   const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}/unpublish`;
   await request(url, { method: "POST", body: {} });
   process.stdout.write(`Unpublished ${name}. The draft and version history are retained.
@@ -646,7 +950,7 @@ import * as readline from "readline";
 async function deleteCommand(args) {
   const name = args.positional[0];
   if (!name) throw new Error("Usage: gs delete <name> [--yes]");
-  const slug = resolveStore({ flag: flagString(args.flags, "store") });
+  const slug = requireProjectStore();
   if (!flagBool(args.flags, "yes")) {
     const confirmed = await prompt(
       `Soft-delete component "${name}" in store "${slug}"? Type "yes" to confirm: `
@@ -662,71 +966,131 @@ async function deleteCommand(args) {
 `);
 }
 function prompt(question) {
-  return new Promise((resolve5) => {
+  return new Promise((resolve4) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     rl.question(question, (answer) => {
       rl.close();
-      resolve5(answer);
+      resolve4(answer);
     });
   });
 }
 
 // src/commands/init.ts
-import * as fs5 from "fs";
-import * as path5 from "path";
+import * as fs6 from "fs";
+import * as path6 from "path";
 var NAME_REGEX = /^[a-z][a-z0-9_]*$/;
 function initCommand(args) {
   const name = args.positional[0];
-  if (!name) {
-    throw new Error("Usage: gs init <name> [--out <dir>] [--store <slug>] [--force]");
-  }
-  if (!NAME_REGEX.test(name)) {
+  if (name !== void 0 && !NAME_REGEX.test(name)) {
     throw new Error(`Invalid component name: "${name}" (must match ${NAME_REGEX}).`);
   }
-  const outRel = flagString(args.flags, "out") ?? name;
-  const out = path5.resolve(outRel);
   const force = flagBool(args.flags, "force");
   const storeFlag = flagString(args.flags, "store");
-  ensureWritable(out, force);
-  fs5.mkdirSync(out, { recursive: true });
-  for (const [relPath, content] of files({ name, store: storeFlag })) {
-    const full = path5.join(out, relPath);
-    fs5.mkdirSync(path5.dirname(full), { recursive: true });
-    fs5.writeFileSync(full, content);
+  const outRel = flagString(args.flags, "out") ?? ".";
+  const root = path6.resolve(outRel);
+  const rootExisted = hasRootScaffold(root);
+  if (rootExisted) {
+    if (storeFlag !== void 0) {
+      throw new Error(
+        `Project at ${root} is already pinned to a store via .gsrc. Drop --store; a project folder ships to exactly one store.`
+      );
+    }
+  } else if (storeFlag === void 0) {
+    const example = name ? `gs init ${name} --store <slug>` : `gs init --store <slug>`;
+    throw new Error(
+      `--store <slug> is required when scaffolding a new project root. Run \`${example}\`.`
+    );
+  }
+  ensureRoot(root, rootExisted, force, { store: storeFlag });
+  if (!name) {
+    const created = rootExisted ? "Updated" : "Scaffolded";
+    process.stdout.write(
+      [
+        `${created} GreatStore project root in ${root}.`,
+        "",
+        "Next steps:",
+        `  cd ${path6.relative(process.cwd(), root) || "."}`,
+        "  npm install",
+        "  gs init <component_name>     # add your first component",
+        ""
+      ].join("\n")
+    );
+    return;
   }
+  const componentDir = path6.join(root, "components", name);
+  ensureComponent(componentDir, name, force);
+  const projectLabel = path6.relative(process.cwd(), root) || ".";
   process.stdout.write(
     [
-      `Scaffolded "${name}" in ${out}.`,
+      `Added component "${name}" at components/${name}/.`,
       "",
       "Next steps:",
-      `  cd ${path5.relative(process.cwd(), out) || "."}`,
-      "  npm install",
+      ...rootExisted ? [] : [`  cd ${projectLabel}`, "  npm install"],
+      `  # edit components/${name}/component.tsx and manifest.json`,
       "  npm run build",
       "  gs push",
       ""
     ].join("\n")
   );
 }
-function ensureWritable(dir, force) {
-  if (!fs5.existsSync(dir)) return;
-  const entries = fs5.readdirSync(dir);
-  if (entries.length === 0) return;
-  if (force) return;
-  throw new Error(
-    `Refusing to scaffold into non-empty directory ${dir}. Pass --force to override.`
-  );
+function hasRootScaffold(dir) {
+  return fs6.existsSync(path6.join(dir, "package.json")) && fs6.existsSync(path6.join(dir, "build.mjs"));
+}
+function ensureRoot(root, rootExisted, force, opts) {
+  fs6.mkdirSync(root, { recursive: true });
+  if (rootExisted) {
+    fs6.mkdirSync(path6.join(root, "components"), { recursive: true });
+    return;
+  }
+  if (!force) {
+    const entries = fs6.readdirSync(root).filter((e) => e !== ".gsrc");
+    if (entries.length > 0) {
+      throw new Error(
+        `Refusing to scaffold project root into non-empty directory ${root}. Pass --force to override.`
+      );
+    }
+  }
+  for (const [relPath, content] of rootFiles({ store: opts.store })) {
+    const full = path6.join(root, relPath);
+    fs6.mkdirSync(path6.dirname(full), { recursive: true });
+    if (force || !fs6.existsSync(full)) {
+      fs6.writeFileSync(full, content);
+    }
+  }
+  fs6.mkdirSync(path6.join(root, "components"), { recursive: true });
 }
-function files(opts) {
-  const { name, store } = opts;
+function ensureComponent(componentDir, name, force) {
+  if (fs6.existsSync(componentDir) && !force) {
+    const entries = fs6.readdirSync(componentDir);
+    if (entries.length > 0) {
+      throw new Error(
+        `Refusing to overwrite existing components/${name}/. Pass --force to override.`
+      );
+    }
+  }
+  fs6.mkdirSync(componentDir, { recursive: true });
+  for (const [relPath, content] of componentFiles(name)) {
+    fs6.writeFileSync(path6.join(componentDir, relPath), content);
+  }
+}
+function rootFiles(opts) {
+  if (!opts.store) {
+    throw new Error("internal: rootFiles called without a store slug");
+  }
   return [
-    ["manifest.json", manifest(name)],
-    ["component.tsx", component(name)],
-    ["vite.config.ts", viteConfig()],
-    ["tsconfig.json", tsconfig()],
-    ["package.json", packageJson(name)],
-    [".gsrc", gsrc(store)],
+    ["package.json", rootPackageJson()],
+    ["build.mjs", buildScript()],
+    ["vite.config.ts", viteEditorConfig()],
+    ["tsconfig.json", rootTsconfig()],
+    [".gsrc", gsrc(opts.store)],
     [".gitignore", gitignore()],
-    ["README.md", readme(name)]
+    ["README.md", rootReadme()]
+  ];
+}
+function componentFiles(name) {
+  return [
+    ["manifest.json", manifest(name)],
+    ["component.tsx", component(name)]
   ];
 }
 function manifest(name) {
@@ -767,51 +1131,86 @@ export default function ${pascal(name)}(_props: Props): React.ReactElement {
 }
 `;
 }
-function viteConfig() {
-  return `import { defineConfig } from "vite";
+function buildScript() {
+  return `import { build } from "vite";
 import react from "@vitejs/plugin-react";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
-// Builds a single ESM bundle suitable for \`gs push\`.
-//
-// React / react-dom / react/jsx-runtime are EXTERNALIZED and rewritten
-// at build time to point at GreatStore's runtime shim at
-// \`/assets/remote-components/_runtime.js\`. The shim re-exports the host
-// chat tree's React instance off \`window.__GS_REMOTE_RUNTIME__\`, so
-// the component and the host share one React. Bundling React in
-// instead would crash on the first hook call because the bundled-in
-// React's dispatcher is null when the chat tree drives the render.
-//
-// Do NOT remove the \`paths\` mapping \u2014 without it the browser tries to
-// resolve a bare \`react\` specifier and fails before the component
-// renders.
-export default defineConfig({
-  plugins: [react()],
-  build: {
-    lib: {
-      entry: "component.tsx",
-      formats: ["es"],
-      fileName: () => "bundle.js",
-    },
-    outDir: ".",
-    emptyOutDir: false,
-    rollupOptions: {
-      external: ["react", "react-dom", "react/jsx-runtime"],
-      output: {
-        entryFileNames: "bundle.js",
-        paths: {
-          react: "/assets/remote-components/_runtime.js",
-          "react-dom": "/assets/remote-components/_runtime.js",
-          "react/jsx-runtime": "/assets/remote-components/_runtime.js",
+const COMPONENTS_DIR = path.resolve("components");
+
+function listComponents() {
+  if (!fs.existsSync(COMPONENTS_DIR)) return [];
+  return fs
+    .readdirSync(COMPONENTS_DIR)
+    .filter((entry) => {
+      const dir = path.join(COMPONENTS_DIR, entry);
+      return (
+        fs.statSync(dir).isDirectory() &&
+        fs.existsSync(path.join(dir, "component.tsx"))
+      );
+    })
+    .sort();
+}
+
+const components = listComponents();
+if (components.length === 0) {
+  console.log("(no components in ./components \u2014 run \`gs init <name>\` to add one)");
+  process.exit(0);
+}
+
+const target = process.argv[2];
+const queue = target ? components.filter((c) => c === target) : components;
+if (target && queue.length === 0) {
+  console.error(\`No component named "\${target}" in ./components\`);
+  process.exit(1);
+}
+
+for (const name of queue) {
+  const dir = path.join(COMPONENTS_DIR, name);
+  await build({
+    plugins: [react()],
+    logLevel: "warn",
+    build: {
+      lib: {
+        entry: path.join(dir, "component.tsx"),
+        formats: ["es"],
+        fileName: () => "bundle.js",
+      },
+      outDir: dir,
+      emptyOutDir: false,
+      rollupOptions: {
+        external: ["react", "react-dom", "react/jsx-runtime"],
+        output: {
+          entryFileNames: "bundle.js",
+          paths: {
+            react: "/assets/remote-components/_runtime.js",
+            "react-dom": "/assets/remote-components/_runtime.js",
+            "react/jsx-runtime": "/assets/remote-components/_runtime.js",
+          },
         },
       },
+      minify: true,
+      sourcemap: false,
     },
-    minify: true,
-    sourcemap: false,
-  },
+  });
+  console.log(\`built components/\${name}/bundle.js\`);
+}
+`;
+}
+function viteEditorConfig() {
+  return `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// Real builds happen in build.mjs (one Vite invocation per component).
+// This file exists only so editors / language servers can resolve the
+// React plugin when inspecting components/*/component.tsx.
+export default defineConfig({
+  plugins: [react()],
 });
 `;
 }
-function tsconfig() {
+function rootTsconfig() {
   return JSON.stringify(
     {
       compilerOptions: {
@@ -826,22 +1225,22 @@ function tsconfig() {
         isolatedModules: true,
         noEmit: true
       },
-      include: ["component.tsx", "vite.config.ts"]
+      include: ["components/**/component.tsx", "vite.config.ts", "build.mjs"]
     },
     null,
     2
   ) + "\n";
 }
-function packageJson(name) {
+function rootPackageJson() {
   return JSON.stringify(
     {
-      name,
+      name: "greatstore-components",
       version: "0.0.1",
       private: true,
       type: "module",
       scripts: {
-        build: "vite build",
-        push: "vite build && gs push"
+        build: "node build.mjs",
+        push: "node build.mjs && gs push"
       },
       dependencies: {
         react: "^19.0.0",
@@ -860,25 +1259,37 @@ function packageJson(name) {
   ) + "\n";
 }
 function gsrc(store) {
-  return JSON.stringify({ store: store ?? "<your-store-slug>" }, null, 2) + "\n";
+  return JSON.stringify({ store }, null, 2) + "\n";
 }
 function gitignore() {
-  return ["node_modules/", "bundle.js", "*.tsbuildinfo", ".DS_Store", ""].join("\n");
+  return [
+    "node_modules/",
+    "components/*/bundle.js",
+    "components/*/.gssync.json",
+    "*.tsbuildinfo",
+    ".DS_Store",
+    ""
+  ].join("\n");
 }
-function readme(name) {
-  return `# ${name}
+function rootReadme() {
+  return `# GreatStore components
 
-A GreatStore custom component scaffolded with \`gs init\`.
+Custom React components published to your GreatStore tenant. Each
+component lives in its own folder under \`components/\`.
 
 \`\`\`
 npm install
-npm run build   # produces bundle.js
-gs push          # uploads as a draft revision
-gs publish ${name}
+gs init <component_name>      # add a new component
+npm run build                 # builds every component/<name>/bundle.js
+gs push                       # uploads every changed component as a draft
+gs publish <component_name>   # promote a specific component to live
 \`\`\`
 
-Edit \`component.tsx\` for the UI and \`manifest.json\` for the metadata
-that the LLM sees (especially \`description\` and \`inputSchema\`).
+- \`gs push\` (no args) hashes each component and only uploads the ones
+  that have changed since the last sync.
+- \`gs pull\` (no args) refreshes every remote component into
+  \`components/<name>/\`. Components with unsaved local edits are skipped
+  with a warning; pass \`--force\` to overwrite.
 `;
 }
 function pascal(name) {
@@ -886,7 +1297,7 @@ function pascal(name) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.0.10" : "0.0.0-dev";
+var VERSION = true ? "0.0.11-beta.1" : "0.0.0-dev";
 var HELP = `gs \u2014 GreatStore CLI (v${VERSION})
 
 Usage:
@@ -896,28 +1307,27 @@ Commands:
   login                          Open browser, capture nav token, persist credentials.
   logout                         Wipe ~/.greatstore/credentials.json.
   whoami                         Print the identity stored locally.
-  init <name>                    Scaffold a component project.
+  init [<name>]                  Scaffold project root; add \`components/<name>/\` if name given.
   list                           List components in the current store.
-  pull <name>                    Download manifest.json + bundle.js.
-  push [<name>]                  Upload manifest.json + bundle.js as a new draft.
+  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.
   unpublish <name>               Clear the live pointer.
   delete <name>                  Soft-delete the component.
 
 Common flags:
-  --store <slug>                 Target store (else .gsrc or GS_STORE).
+  --store <slug>                 \`init\` only \u2014 writes the slug into .gsrc. Other commands read .gsrc.
   --json                         Machine-readable output for \`list\`.
   --draft | --live | --version N Revision selector for \`pull\`.
   -o, --out <dir>                Output directory for \`pull\` / \`init\`.
   --manifest <path>              Path to manifest for \`push\`.
   --bundle <path>                Path to bundle for \`push\`.
-  --force                        Overwrite for \`init\`; skip confirmation for \`delete\`.
+  --force                        Overwrite for \`init\` / \`pull\`; skip confirmation for \`delete\`.
   --yes                          Skip confirmation for \`delete\`.
   -h, --help                     Show this help.
   -v, --version                  Print version.
 
 Environment:
-  GS_STORE                       Fallback for --store.
   GS_API_BASE                    Override API base (full URL, no trailing slash).
   GS_NAV_BASE                    Override nav OAuth base.
   GS_BROWSER_CMD                 Override the browser-open command.

package/package.json

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