@greatstore/cli 0.0.1

package/README.md

@@ -0,0 +1,95 @@
+# @greatstore/cli
+
+Author and ship GreatStore custom remote components from the command line.
+
+```
+npm install -g @greatstore/cli
+gs login
+gs init my-widget
+cd my-widget && npm install && npm run build
+gs push
+gs publish my-widget
+```
+
+> **Status — MVP.** Authentication today targets a nav-side OAuth bounce
+> at `nav.maker.co/connect_oauth_done` and a short-lived JWT stored at
+> `~/.greatstore/credentials.json`. Bearer acceptance on the worker is a
+> separate planned change (see
+> `tasks/backburner/builder-cli-bearer-auth.md` in the main repo); until
+> that lands, push/publish/list etc. will 401 against the live API.
+
+## Commands
+
+| Command                                       | What it does                                                  |
+| --------------------------------------------- | ------------------------------------------------------------- |
+| `gs login [--store <slug>]`                   | Open the browser, capture a nav token, persist credentials.   |
+| `gs logout`                                   | Wipe `~/.greatstore/credentials.json`.                        |
+| `gs whoami`                                   | Print the identity stored in your credentials file.           |
+| `gs init <name> [--out <dir>] [--store <s>]`  | Scaffold a working component project.                         |
+| `gs list [--json]`                            | List the components in the current store.                     |
+| `gs pull <name> [--draft\|--live\|--version N] [-o <dir>]` | Download manifest + bundle to disk.            |
+| `gs push [<name>] [--manifest path] [--bundle path]` | Upload a new draft revision.                          |
+| `gs publish <name> [--version N]`             | Promote a draft (or rollback to a historical version) to live.|
+| `gs unpublish <name>`                         | Clear the live pointer; the draft and history stay.           |
+| `gs delete <name> [--yes]`                    | Soft-delete the component (R2 objects are retained).          |
+
+## Store selection
+
+Every command except `login`, `logout`, and `whoami` needs a store. The
+CLI resolves it with this precedence:
+
+1. `--store <slug>` flag.
+2. `.gsrc` in the current directory or any ancestor: `{"store":"demo"}`.
+3. `GS_STORE` environment variable.
+4. Error.
+
+`gs init` writes a `.gsrc` for you so commands inside a scaffolded
+project don't need a flag.
+
+## Environment
+
+- `GS_API_BASE` — override the API base URL (default
+  `https://<slug>.greatstore.ai`). Used for local dev:
+  `GS_API_BASE=http://demo.localhost:8787`.
+- `GS_NAV_BASE` — override the nav OAuth base (default
+  `https://nav.maker.co`). Used for testing against a non-prod Clerk
+  tenant.
+- `GS_BROWSER_CMD` — override the command used to open the browser
+  during `gs login`. Defaults to `open` on macOS, `xdg-open` on Linux,
+  `start` on Windows.
+
+## Credentials storage
+
+`~/.greatstore/credentials.json` is created with mode `0700` on its
+directory and `0600` on the file. The CLI verifies this on every read
+and refuses to use a file with broader permissions.
+
+The credentials file holds a single short-lived JWT plus its decoded
+identity claims. There is no refresh token; when the JWT expires, the
+next command prompts for re-auth and re-runs the browser flow.
+
+## Development
+
+```
+cd cli
+npm install
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+```
+
+To exercise against local `wrangler dev`, point at the tenant host:
+
+```
+GS_API_BASE=http://demo.localhost:8787 \
+GS_NAV_BASE=https://nav.maker.co \
+node dist/cli.js list --store demo
+```
+
+## Release flow
+
+1. Bump `cli/package.json` version.
+2. Tag: `git tag cli-v0.0.2 && git push origin cli-v0.0.2`.
+3. `cli-publish` GitHub Actions workflow runs typecheck + test + build,
+   then `npm publish --access public` with `NPM_TOKEN`.

package/dist/cli.js

@@ -0,0 +1,950 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+var SHORT_ALIASES = {
+  h: "help",
+  v: "version",
+  o: "out"
+};
+function parseArgs(argv) {
+  const out = { command: null, positional: [], flags: {} };
+  if (argv.length === 0) return out;
+  let i = 0;
+  const first = argv[0];
+  if (first && !first.startsWith("-")) {
+    out.command = first;
+    i = 1;
+  }
+  for (; i < argv.length; i++) {
+    const token = argv[i] ?? "";
+    if (token.startsWith("--")) {
+      const eq = token.indexOf("=");
+      let key;
+      let value;
+      if (eq !== -1) {
+        key = token.slice(2, eq);
+        value = token.slice(eq + 1);
+      } else {
+        key = token.slice(2);
+        const next = argv[i + 1];
+        if (next === void 0 || next.startsWith("--") || next.startsWith("-")) {
+          value = true;
+        } else {
+          value = next;
+          i++;
+        }
+      }
+      if (key) out.flags[key] = value;
+    } else if (token.startsWith("-") && token.length > 1) {
+      const short = token.slice(1);
+      const aliased = SHORT_ALIASES[short];
+      if (!aliased) continue;
+      const next = argv[i + 1];
+      if (next === void 0 || next.startsWith("-")) {
+        out.flags[aliased] = true;
+      } else {
+        out.flags[aliased] = next;
+        i++;
+      }
+    } else {
+      out.positional.push(token);
+    }
+  }
+  return out;
+}
+function flagString(flags, key) {
+  const v = flags[key];
+  return typeof v === "string" ? v : void 0;
+}
+function flagBool(flags, key) {
+  const v = flags[key];
+  return v === true || v === "true";
+}
+
+// src/loopback.ts
+import * as crypto from "crypto";
+import * as http from "http";
+import { spawn } from "child_process";
+var CALLBACK_PATH = "/callback";
+var SUCCESS_HTML = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>GreatStore CLI</title>
+<style>body{font:14px/1.5 system-ui;margin:4rem auto;max-width:32rem;color:#222;text-align:center}
+h1{font-size:1.4rem}code{background:#f4f4f4;padding:.1em .3em;border-radius:.2em}</style></head>
+<body><h1>You're signed in.</h1>
+<p>You can close this window and return to your terminal.</p></body></html>`;
+var FAILURE_HTML = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>GreatStore CLI</title>
+<style>body{font:14px/1.5 system-ui;margin:4rem auto;max-width:32rem;color:#222;text-align:center}
+h1{font-size:1.4rem;color:#a40000}code{background:#f4f4f4;padding:.1em .3em;border-radius:.2em}</style></head>
+<body><h1>Sign-in failed.</h1>
+<p>Return to your terminal for details.</p></body></html>`;
+var LoopbackError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LoopbackError";
+  }
+};
+async function captureLoopbackToken(options) {
+  const state = (options.generateState ?? defaultState)();
+  const timeoutMs = options.timeoutMs ?? 5 * 60 * 1e3;
+  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));
+    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)}`;
+    const tokenPromise = waitForCallback(server, state, timeoutMs);
+    open(authUrl);
+    return await tokenPromise;
+  } finally {
+    server.close();
+  }
+}
+function waitForCallback(server, expectedState, timeoutMs) {
+  return new Promise((resolve5, reject) => {
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    const timer = setTimeout(() => {
+      settle(() => reject(new LoopbackError("Timed out waiting for sign-in. Re-run `gs login`.")));
+    }, timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+    server.on("request", (req, res) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== CALLBACK_PATH) {
+        res.writeHead(404, { "content-type": "text/plain" });
+        res.end("Not found");
+        return;
+      }
+      const params = url.searchParams;
+      const error = params.get("error");
+      const token = params.get("token");
+      const returnedState = params.get("state");
+      if (returnedState !== expectedState) {
+        res.writeHead(400, { "content-type": "text/html" });
+        res.end(FAILURE_HTML);
+        clearTimeout(timer);
+        settle(() => reject(new LoopbackError("State mismatch on OAuth callback \u2014 possible CSRF, login aborted.")));
+        return;
+      }
+      if (error) {
+        res.writeHead(400, { "content-type": "text/html" });
+        res.end(FAILURE_HTML);
+        clearTimeout(timer);
+        settle(() => reject(new LoopbackError(`Sign-in failed: ${error}`)));
+        return;
+      }
+      if (!token) {
+        res.writeHead(400, { "content-type": "text/html" });
+        res.end(FAILURE_HTML);
+        clearTimeout(timer);
+        settle(() => reject(new LoopbackError("Callback missing `token` query parameter.")));
+        return;
+      }
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end(SUCCESS_HTML);
+      clearTimeout(timer);
+      settle(() => resolve5({ token }));
+    });
+  });
+}
+function defaultState() {
+  return crypto.randomBytes(16).toString("hex");
+}
+function openInBrowser(url, overrideCmd) {
+  const override = overrideCmd?.trim();
+  const cmd = override ?? defaultBrowserCommand();
+  if (!cmd) {
+    return;
+  }
+  try {
+    const args = cmd === "start" ? ["", url] : [url];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true, shell: cmd === "start" });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function defaultBrowserCommand() {
+  switch (process.platform) {
+    case "darwin":
+      return "open";
+    case "win32":
+      return "start";
+    case "linux":
+      return "xdg-open";
+    default:
+      return null;
+  }
+}
+
+// src/credentials.ts
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var DIR_NAME = ".greatstore";
+var FILE_NAME = "credentials.json";
+function credentialsDir(home = os.homedir()) {
+  return path.join(home, DIR_NAME);
+}
+function credentialsPath(home = os.homedir()) {
+  return path.join(credentialsDir(home), FILE_NAME);
+}
+function read(home = os.homedir()) {
+  const file = credentialsPath(home);
+  let raw;
+  try {
+    const stat = fs.statSync(file);
+    if (process.platform !== "win32") {
+      const mode = stat.mode & 511;
+      if (mode & 63) {
+        throw new Error(
+          `Refusing to read ${file}: permissions are ${mode.toString(8)} (should be 600). Run \`chmod 600 ${file}\`.`
+        );
+      }
+    }
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (isENOENT(err)) return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.access_token !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function write(creds, home = os.homedir()) {
+  const dir = credentialsDir(home);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  if (process.platform !== "win32") {
+    try {
+      fs.chmodSync(dir, 448);
+    } catch {
+    }
+  }
+  const file = credentialsPath(home);
+  fs.writeFileSync(file, `${JSON.stringify(creds, null, 2)}
+`, {
+    mode: 384
+  });
+  if (process.platform !== "win32") {
+    fs.chmodSync(file, 384);
+  }
+}
+function clear(home = os.homedir()) {
+  fs.rmSync(credentialsPath(home), { force: true });
+}
+function decodeJwtPayload(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid JWT: expected three dot-separated segments");
+  }
+  const segment = parts[1];
+  if (!segment) throw new Error("Invalid JWT: empty payload segment");
+  const padded = segment + "=".repeat((4 - segment.length % 4) % 4);
+  const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+  const json = Buffer.from(base64, "base64").toString("utf8");
+  return JSON.parse(json);
+}
+function isExpired(creds, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  return creds.expires_at <= nowSeconds;
+}
+function isENOENT(err) {
+  return typeof err === "object" && err !== null && err.code === "ENOENT";
+}
+
+// src/config.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+var NAV_BASE_DEFAULT = "https://nav.maker.co";
+var StoreResolutionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StoreResolutionError";
+  }
+};
+function resolveStore(input = {}) {
+  const flag = input.flag?.trim();
+  if (flag) return flag;
+  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":"..."}.'
+  );
+}
+function findGsrc(cwd) {
+  let dir = path2.resolve(cwd);
+  const root = path2.parse(dir).root;
+  while (true) {
+    const candidate = path2.join(dir, ".gsrc");
+    if (fs2.existsSync(candidate)) {
+      try {
+        const raw = fs2.readFileSync(candidate, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.store === "string" && parsed.store.trim()) {
+          return parsed.store.trim();
+        }
+      } catch {
+      }
+    }
+    if (dir === root) return null;
+    const parent = path2.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function apiBaseFor(slug, env = process.env) {
+  const override = env.GS_API_BASE?.trim();
+  if (override) return stripTrailingSlash(override);
+  return `https://${slug}.greatstore.ai`;
+}
+function navBase(env = process.env) {
+  const override = env.GS_NAV_BASE?.trim();
+  if (override) return stripTrailingSlash(override);
+  return NAV_BASE_DEFAULT;
+}
+function stripTrailingSlash(s) {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+// src/http.ts
+var HttpError = class extends Error {
+  constructor(status, message, code, detail) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+    this.name = "HttpError";
+  }
+};
+var AuthRequiredError = class extends Error {
+  constructor(message = "Not logged in. Run `gs login`.") {
+    super(message);
+    this.name = "AuthRequiredError";
+  }
+};
+async function request(url, options = {}) {
+  const interactive = options.interactive ?? true;
+  const stored = read();
+  if (!stored) throw new AuthRequiredError();
+  try {
+    return await sendOnce(url, options, stored.access_token);
+  } catch (err) {
+    if (!interactive || !(err instanceof HttpError) || err.status !== 401) {
+      throw err;
+    }
+    const refreshed = await reauthenticate();
+    return await sendOnce(url, options, refreshed.access_token);
+  }
+}
+async function sendOnce(url, options, accessToken) {
+  const headers = {
+    accept: "application/json",
+    authorization: `Bearer ${accessToken}`,
+    ...options.headers ?? {}
+  };
+  let body;
+  if (options.multipart && options.body !== void 0) {
+    throw new Error("request(): pass either `body` or `multipart`, not both");
+  }
+  if (options.multipart) {
+    body = options.multipart;
+    delete headers["content-type"];
+  } else if (options.body !== void 0) {
+    body = JSON.stringify(options.body);
+    headers["content-type"] = "application/json";
+  }
+  const init = {
+    method: options.method ?? "GET",
+    headers
+  };
+  if (body !== void 0) init.body = body;
+  const res = await fetch(url, init);
+  if (res.status >= 200 && res.status < 300) {
+    if (res.status === 204) return void 0;
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      return await res.json();
+    }
+    return await res.text();
+  }
+  const text = await res.text();
+  let parsed = {};
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+  }
+  const message = parsed.error?.trim() || parsed.detail?.trim() || text.trim() || `HTTP ${res.status}`;
+  throw new HttpError(res.status, message, parsed.code, parsed.detail);
+}
+async function reauthenticate() {
+  process.stderr.write("Access token expired \u2014 re-running sign-in.\n");
+  try {
+    const { token } = await captureLoopbackToken({ navBaseUrl: navBase() });
+    const next = buildCredentials(token);
+    write(next);
+    return next;
+  } catch (err) {
+    if (err instanceof LoopbackError) {
+      throw new AuthRequiredError(err.message);
+    }
+    throw err;
+  }
+}
+function buildCredentials(token) {
+  const claims = decodeJwtPayload(token);
+  const sub = readString(claims, "sub");
+  if (!sub) throw new Error("Token is missing a `sub` claim.");
+  const exp = readNumber(claims, "exp");
+  return {
+    access_token: token,
+    expires_at: exp ?? Math.floor(Date.now() / 1e3) + 60 * 60,
+    sub,
+    ...maybeString(claims, "email", "email"),
+    ...maybeString(claims, "accountId", "accountId"),
+    ...maybeString(claims, "name", "name"),
+    ...maybeString(claims, "surname", "surname"),
+    ...maybeBool(claims, "superUser", "superUser")
+  };
+}
+function readString(obj, key) {
+  const v = obj[key];
+  return typeof v === "string" ? v : void 0;
+}
+function readNumber(obj, key) {
+  const v = obj[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function maybeString(obj, src, dst) {
+  const v = readString(obj, src);
+  return v ? { [dst]: v } : {};
+}
+function maybeBool(obj, src, dst) {
+  const v = obj[src];
+  if (v === true) return { [dst]: true };
+  if (typeof v === "string" && v.toLowerCase() === "true") return { [dst]: true };
+  return {};
+}
+
+// src/commands/login.ts
+async function loginCommand() {
+  process.stdout.write("Opening browser for sign-in\u2026\n");
+  const { token } = await captureLoopbackToken({ navBaseUrl: navBase() });
+  const next = buildCredentials(token);
+  write(next);
+  const who = next.email ?? next.sub;
+  process.stdout.write(`Logged in as ${who}.
+`);
+}
+
+// src/commands/logout.ts
+function logoutCommand() {
+  const existed = read() !== null;
+  clear();
+  process.stdout.write(existed ? "Logged out.\n" : "Not logged in.\n");
+}
+
+// src/commands/whoami.ts
+function whoamiCommand() {
+  const stored = read();
+  if (!stored) {
+    process.stderr.write("Not logged in. Run `gs login`.\n");
+    return 1;
+  }
+  const expired = isExpired(stored);
+  const lines = [
+    `sub:        ${stored.sub}`,
+    `email:      ${stored.email ?? "(none)"}`,
+    `accountId:  ${stored.accountId ?? "(none)"}`,
+    `superUser:  ${stored.superUser ?? false}`,
+    `name:       ${[stored.name, stored.surname].filter(Boolean).join(" ") || "(none)"}`,
+    `expires:    ${new Date(stored.expires_at * 1e3).toISOString()}${expired ? " (EXPIRED)" : ""}`
+  ];
+  process.stdout.write(lines.join("\n") + "\n");
+  return expired ? 1 : 0;
+}
+
+// src/commands/list.ts
+async function listCommand(args) {
+  const slug = resolveStore({ flag: flagString(args.flags, "store") });
+  const url = `${apiBaseFor(slug)}/api/builder/components`;
+  const data = await request(url);
+  if (flagBool(args.flags, "json")) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    return;
+  }
+  if (data.components.length === 0) {
+    process.stdout.write(`(no components in ${slug})
+`);
+    return;
+  }
+  const rows = data.components.map((c) => ({
+    name: c.name,
+    draft: c.draft ? `v${c.draft.version}` : "\u2014",
+    live: c.live ? `v${c.live.version}` : "\u2014",
+    updated: c.live?.updatedAt ?? c.draft?.updatedAt ?? ""
+  }));
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    draft: Math.max(5, ...rows.map((r) => r.draft.length)),
+    live: Math.max(4, ...rows.map((r) => r.live.length))
+  };
+  const header = `${pad("NAME", widths.name)}  ${pad("DRAFT", widths.draft)}  ${pad("LIVE", widths.live)}  UPDATED`;
+  process.stdout.write(header + "\n");
+  for (const r of rows) {
+    process.stdout.write(
+      `${pad(r.name, widths.name)}  ${pad(r.draft, widths.draft)}  ${pad(r.live, widths.live)}  ${r.updated}
+`
+    );
+  }
+}
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
+// src/commands/pull.ts
+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>]");
+  }
+  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 });
+  fs3.writeFileSync(
+    path3.join(out, "manifest.json"),
+    JSON.stringify(data.manifest, null, 2) + "\n"
+  );
+  fs3.writeFileSync(path3.join(out, "bundle.js"), data.bundle);
+  process.stdout.write(
+    `Pulled ${name} v${data.version} \u2192 ${path3.resolve(out)}/{manifest.json, bundle.js}
+`
+  );
+}
+function buildRevisionQuery(args) {
+  const version = flagString(args.flags, "version");
+  if (version) return `?version=${encodeURIComponent(version)}`;
+  if (flagBool(args.flags, "draft")) return `?revision=draft`;
+  if (flagBool(args.flags, "live")) return `?revision=live`;
+  return "";
+}
+
+// src/commands/push.ts
+import * as fs4 from "fs";
+import * as path4 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");
+  if (!fs4.existsSync(manifestPath)) {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  if (!fs4.existsSync(bundlePath)) {
+    throw new Error(`Bundle not found: ${bundlePath} (did you run \`npm run build\`?)`);
+  }
+  const manifestText = fs4.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.");
+  }
+  if (manifestName && manifestName !== name) {
+    throw new Error(
+      `Manifest name "${manifestName}" does not match argument "${name}". The server will reject this.`
+    );
+  }
+  const bundleText = fs4.readFileSync(bundlePath, "utf8");
+  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");
+  const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}`;
+  const data = await request(url, { method: "POST", multipart: form });
+  process.stdout.write(
+    `Pushed ${name} v${data.version} (draft) to ${slug}. Run \`gs publish ${name}\` to promote.
+`
+  );
+}
+
+// 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 url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}/publish`;
+  const versionFlag = flagString(args.flags, "version");
+  let body = void 0;
+  if (versionFlag !== void 0) {
+    const n = Number.parseInt(versionFlag, 10);
+    if (!Number.isInteger(n) || n < 1) {
+      throw new Error(`Invalid --version: ${versionFlag}`);
+    }
+    body = { version: n };
+  } else {
+    body = {};
+  }
+  const data = await request(url, { method: "POST", body });
+  process.stdout.write(`Published ${name} (live = v${data.live_version}).
+`);
+}
+
+// src/commands/unpublish.ts
+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 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.
+`);
+}
+
+// src/commands/delete.ts
+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") });
+  if (!flagBool(args.flags, "yes")) {
+    const confirmed = await prompt(
+      `Soft-delete component "${name}" in store "${slug}"? Type "yes" to confirm: `
+    );
+    if (confirmed.trim() !== "yes") {
+      process.stdout.write("Aborted.\n");
+      return;
+    }
+  }
+  const url = `${apiBaseFor(slug)}/api/builder/components/${encodeURIComponent(name)}`;
+  await request(url, { method: "DELETE" });
+  process.stdout.write(`Deleted ${name}. (R2 objects retained; history preserved.)
+`);
+}
+function prompt(question) {
+  return new Promise((resolve5) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve5(answer);
+    });
+  });
+}
+
+// src/commands/init.ts
+import * as fs5 from "fs";
+import * as path5 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)) {
+    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);
+  }
+  process.stdout.write(
+    [
+      `Scaffolded "${name}" in ${out}.`,
+      "",
+      "Next steps:",
+      `  cd ${path5.relative(process.cwd(), out) || "."}`,
+      "  npm install",
+      "  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 files(opts) {
+  const { name, store } = opts;
+  return [
+    ["manifest.json", manifest(name)],
+    ["component.tsx", component(name)],
+    ["vite.config.ts", viteConfig()],
+    ["tsconfig.json", tsconfig()],
+    ["package.json", packageJson(name)],
+    [".gsrc", gsrc(store)],
+    [".gitignore", gitignore()],
+    ["README.md", readme(name)]
+  ];
+}
+function manifest(name) {
+  return JSON.stringify(
+    {
+      name,
+      description: `Renders the ${name} widget.`,
+      displayMode: "inline",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      }
+    },
+    null,
+    2
+  ) + "\n";
+}
+function component(name) {
+  return `import React from "react";
+
+interface Props {
+  // Add fields here matching manifest.json#inputSchema.properties.
+}
+
+export default function ${pascal(name)}(_props: Props): React.ReactElement {
+  return (
+    <div style={{ padding: "1rem", border: "1px solid #ddd", borderRadius: 8 }}>
+      <strong>${name}</strong> \u2014 hello from your component!
+    </div>
+  );
+}
+`;
+}
+function viteConfig() {
+  return `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// Builds a single ESM bundle suitable for \`gs push\`. React + ReactDOM
+// are externalized \u2014 the GreatStore runtime provides them at load time.
+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" },
+    },
+    minify: true,
+    sourcemap: false,
+  },
+});
+`;
+}
+function tsconfig() {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        jsx: "react-jsx",
+        lib: ["ES2022", "DOM"],
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        isolatedModules: true,
+        noEmit: true
+      },
+      include: ["component.tsx", "vite.config.ts"]
+    },
+    null,
+    2
+  ) + "\n";
+}
+function packageJson(name) {
+  return JSON.stringify(
+    {
+      name,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      scripts: {
+        build: "vite build",
+        push: "vite build && gs push"
+      },
+      dependencies: {
+        react: "^19.0.0",
+        "react-dom": "^19.0.0"
+      },
+      devDependencies: {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^4.3.0",
+        typescript: "^5.6.0",
+        vite: "^5.4.0"
+      }
+    },
+    null,
+    2
+  ) + "\n";
+}
+function gsrc(store) {
+  return JSON.stringify({ store: store ?? "<your-store-slug>" }, null, 2) + "\n";
+}
+function gitignore() {
+  return ["node_modules/", "bundle.js", "*.tsbuildinfo", ".DS_Store", ""].join("\n");
+}
+function readme(name) {
+  return `# ${name}
+
+A GreatStore custom component scaffolded with \`gs init\`.
+
+\`\`\`
+npm install
+npm run build   # produces bundle.js
+gs push          # uploads as a draft revision
+gs publish ${name}
+\`\`\`
+
+Edit \`component.tsx\` for the UI and \`manifest.json\` for the metadata
+that the LLM sees (especially \`description\` and \`inputSchema\`).
+`;
+}
+function pascal(name) {
+  return name.split(/[_-]/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join("");
+}
+
+// src/index.ts
+var VERSION = "0.0.1";
+var HELP = `gs \u2014 GreatStore CLI (v${VERSION})
+
+Usage:
+  gs <command> [args] [flags]
+
+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.
+  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.
+  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).
+  --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\`.
+  --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.
+`;
+async function main() {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+  if (flagBool(parsed.flags, "version")) {
+    process.stdout.write(`gs v${VERSION}
+`);
+    return 0;
+  }
+  if (flagBool(parsed.flags, "help") || parsed.command === "help" || parsed.command === null) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  switch (parsed.command) {
+    case "login":
+      await loginCommand();
+      return 0;
+    case "logout":
+      logoutCommand();
+      return 0;
+    case "whoami":
+      return whoamiCommand();
+    case "init":
+      initCommand(parsed);
+      return 0;
+    case "list":
+      await listCommand(parsed);
+      return 0;
+    case "pull":
+      await pullCommand(parsed);
+      return 0;
+    case "push":
+      await pushCommand(parsed);
+      return 0;
+    case "publish":
+      await publishCommand(parsed);
+      return 0;
+    case "unpublish":
+      await unpublishCommand(parsed);
+      return 0;
+    case "delete":
+      await deleteCommand(parsed);
+      return 0;
+    default:
+      process.stderr.write(`Unknown command: ${parsed.command}
+
+${HELP}`);
+      return 1;
+  }
+}
+main().then((code) => process.exit(code)).catch((err) => {
+  if (err instanceof AuthRequiredError) {
+    process.stderr.write(`${err.message}
+`);
+  } else if (err instanceof HttpError) {
+    process.stderr.write(`Error (HTTP ${err.status}): ${err.message}
+`);
+    if (err.detail && err.detail !== err.message) {
+      process.stderr.write(`  ${err.detail}
+`);
+    }
+  } else if (err instanceof StoreResolutionError || err instanceof LoopbackError) {
+    process.stderr.write(`Error: ${err.message}
+`);
+  } else if (err instanceof Error) {
+    process.stderr.write(`Error: ${err.message}
+`);
+  } else {
+    process.stderr.write(`Error: ${String(err)}
+`);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@greatstore/cli",
+  "version": "0.0.1",
+  "description": "CLI for authoring and shipping GreatStore custom components.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "gs": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.8.2",
+    "vitest": "^2.1.0"
+  }
+}