@groundfloorcloud/cli 0.1.1 → 0.1.2

package/README.md

@@ -6,6 +6,10 @@ secrets, files, apps, and Dataplane from your terminal.
 `gf login` opens a browser, you sign in, and the session is cached and
 refreshed automatically.
 
+Agents in Cursor use [`@groundfloorcloud/mcp`](../mcp/README.md) against the
+same `gf login` session to inspect the workspace and docs, then run `gf`
+commands to take action.
+
 ## Install
 
 ```bash
@@ -105,17 +109,28 @@ Runtime is auto-detected when omitted (`package.json` → node,
 Product **Apps** are packaging (Shell Module Federation remotes, or a
 standalone wrapper around a service). That is separate from `gf deploy`.
 
+**Always start from the official starter-kit.** Do not scaffold `App.tsx` or
+put `BrowserRouter` in the federated export — that crashes the Shell.
+
 ```bash
+gf apps init --slug my-federated-app
+cd my-federated-app
 gf apps create --name "My Federated App" --slug my-federated-app \
   --manifest ./groundfloor.manifest.json
+npm install
 npm run release
 gf apps publish --path release.zip
 ```
 
-`gf apps publish` uploads `release.zip` (or `remoteEntry.js`), finalizes the
-release, and by default PATCHes the Portal manifest from
+`gf apps init` downloads the public ZIP from the Customer Portal
+(`/downloads/shell-starter-kit.zip` on the current cell) and stamps
+`APP_ID` / `groundfloor.manifest.json` `appId` to the slug.
+
+`gf apps publish` uploads `release.zip` (or `remoteEntry.js`), flattens a
+Vite `dist/assets/` layout so chunks sit next to `remoteEntry.js`, finalizes
+the release, and by default PATCHes the Portal manifest from
 `groundfloor.manifest.json` next to the bundle. Pass an app id/slug, or set
-`appId` in that manifest.
+`appId` in that manifest. Prefer `npm run release` over zipping `dist/` by hand.
 
 Wrap an existing **service** coderunner as a product:
 
@@ -164,6 +179,7 @@ gf apps get <id|slug>
 | `gf domains ls\|add\|rm\|verify -c <id\|slug>` | Custom domains for a service. |
 | `gf secrets ls\|get\|set\|rm` | Workspace secrets. |
 | `gf files ls\|upload\|download\|rm` | Workspace files. |
+| `gf apps init --slug <slug>` | Download the official Shell starter-kit and stamp APP_ID. |
 | `gf apps ls\|get\|create\|publish` | Product apps (Shell publish / standalone wrap). |
 | `gf dataplane status\|provision` | Dataplane setup for the workspace. |
 

package/dist/index.js

@@ -68,19 +68,26 @@ var CELLS = {
   production: {
     apiUrl: "https://platform.groundfloor.cloud",
     issuer: "https://auth.groundfloor.cloud/realms/groundfloor",
-    clientId: "groundfloor-cli"
+    clientId: "groundfloor-cli",
+    consoleUrl: "https://console.groundfloor.cloud"
   },
   stage: {
     apiUrl: "https://platform.stage.groundfloor.cloud",
     issuer: "https://auth.stage.groundfloor.cloud/realms/groundfloor_pico_stage-realm",
-    clientId: "groundfloor-cli"
+    clientId: "groundfloor-cli",
+    consoleUrl: "https://console.stage.groundfloor.cloud"
   },
   dev: {
     apiUrl: "https://platform.dev.groundfloor.cloud",
     issuer: "https://auth.dev.groundfloor.cloud/realms/groundfloor_dev",
-    clientId: "groundfloor-cli"
+    clientId: "groundfloor-cli",
+    consoleUrl: "https://console.dev.groundfloor.cloud"
   }
 };
+var STARTER_KIT_ZIP_PATH = "/downloads/shell-starter-kit.zip";
+function starterKitZipUrl(cell = "production") {
+  return `${CELLS[cell].consoleUrl}${STARTER_KIT_ZIP_PATH}`;
+}
 var CELL_ALIASES = {
   production: "production",
   prod: "production",
@@ -384,10 +391,13 @@ async function refreshTokens(opts) {
 var EXPIRY_SKEW_MS = 3e4;
 var NotLoggedInError = class extends Error {
   constructor() {
-    super("Not logged in. Run `gf login` first.");
+    super(
+      "Not logged in. Set GROUNDFLOOR_TOKEN, or run `gf login` first."
+    );
     this.name = "NotLoggedInError";
   }
 };
+var accessTokenProvider = null;
 function decodeJwt(token) {
   const parts = token.split(".");
   if (parts.length < 2) return null;
@@ -414,6 +424,9 @@ function isFresh(session) {
   return Date.now() < session.expiresAt - EXPIRY_SKEW_MS;
 }
 async function getValidAccessToken() {
+  if (accessTokenProvider) {
+    return accessTokenProvider();
+  }
   const session = await readAuth();
   if (!session || !session.accessToken) {
     throw new NotLoggedInError();
@@ -520,9 +533,9 @@ async function parseError(res) {
   }
   return `${res.status} ${detail}`;
 }
-async function cpGet(apiUrl, path6) {
+async function cpGet(apiUrl, path7) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path6}`, {
+  const res = await fetch(`${apiUrl}${path7}`, {
     headers: {
       Authorization: `Bearer ${token}`,
       Accept: "application/json"
@@ -533,9 +546,9 @@ async function cpGet(apiUrl, path6) {
   }
   return await res.json();
 }
-async function cpPostJson(apiUrl, path6, body) {
+async function cpPostJson(apiUrl, path7, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path6}`, {
+  const res = await fetch(`${apiUrl}${path7}`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -549,9 +562,9 @@ async function cpPostJson(apiUrl, path6, body) {
   }
   return await res.json();
 }
-async function cpDelete(apiUrl, path6) {
+async function cpDelete(apiUrl, path7) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path6}`, {
+  const res = await fetch(`${apiUrl}${path7}`, {
     method: "DELETE",
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
   });
@@ -559,9 +572,9 @@ async function cpDelete(apiUrl, path6) {
     throw new CpError(res.status, await parseError(res));
   }
 }
-async function cpPutJson(apiUrl, path6, body) {
+async function cpPutJson(apiUrl, path7, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path6}`, {
+  const res = await fetch(`${apiUrl}${path7}`, {
     method: "PUT",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -575,9 +588,9 @@ async function cpPutJson(apiUrl, path6, body) {
   }
   return await res.json();
 }
-async function cpPatchJson(apiUrl, path6, body) {
+async function cpPatchJson(apiUrl, path7, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path6}`, {
+  const res = await fetch(`${apiUrl}${path7}`, {
     method: "PATCH",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -591,9 +604,9 @@ async function cpPatchJson(apiUrl, path6, body) {
   }
   return await res.json();
 }
-async function cpPutBytes(apiUrl, path6, body, contentType) {
+async function cpPutBytes(apiUrl, path7, body, contentType) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path6}`, {
+  const res = await fetch(`${apiUrl}${path7}`, {
     method: "PUT",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -1686,6 +1699,96 @@ async function filesRmCommand(fileId, opts) {
 // src/commands/apps.ts
 import { promises as fs5 } from "fs";
 import path5 from "path";
+
+// src/release-zip.ts
+import AdmZip2 from "adm-zip";
+var REMOTE_ENTRY = "remoteEntry.js";
+var FLATTEN_SUFFIXES = [".js", ".mjs", ".cjs", ".css", ".map", ".wasm"];
+function normalizeZipEntryName(filename) {
+  return filename.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function parentDir(rel) {
+  const i = rel.lastIndexOf("/");
+  return i === -1 ? "" : rel.slice(0, i);
+}
+function basename(rel) {
+  const i = rel.lastIndexOf("/");
+  return i === -1 ? rel : rel.slice(i + 1);
+}
+function chooseRemoteEntry(relpaths) {
+  const entries = relpaths.filter(
+    (p) => p === REMOTE_ENTRY || p.endsWith(`/${REMOTE_ENTRY}`)
+  );
+  if (entries.length === 0) return void 0;
+  if (entries.includes(REMOTE_ENTRY)) return REMOTE_ENTRY;
+  return [...entries].sort((a, b) => {
+    const score = (p) => {
+      const parts = p.split("/");
+      const inAssets = parts.length >= 2 && parts[parts.length - 2] === "assets";
+      return `${inAssets ? 0 : 1}:${parts.length}:${p}`;
+    };
+    return score(a).localeCompare(score(b));
+  })[0];
+}
+function flattenFederatedBundlePlan(relpaths) {
+  const paths = relpaths.map(normalizeZipEntryName).filter((name) => name && !name.endsWith("/") && !name.split("/").includes(".."));
+  const pathset = new Set(paths);
+  const entry = chooseRemoteEntry([...pathset]);
+  if (!entry) return {};
+  const promoteDirs = /* @__PURE__ */ new Set();
+  const entryDir = parentDir(entry);
+  if (entryDir) promoteDirs.add(entryDir);
+  for (const path7 of pathset) {
+    const parent = parentDir(path7);
+    if (parent === "assets" || parent.endsWith("/assets") && parent.split("/").length - 1 < 2) {
+      promoteDirs.add(parent);
+    }
+  }
+  const destToSrc = {};
+  for (const src of paths) {
+    const parent = parentDir(src);
+    if (!promoteDirs.has(parent)) continue;
+    const dest = basename(src);
+    if (dest === "release.zip") continue;
+    const lower = dest.toLowerCase();
+    if (dest !== REMOTE_ENTRY && !FLATTEN_SUFFIXES.some((ext) => lower.endsWith(ext))) {
+      continue;
+    }
+    if (pathset.has(dest)) continue;
+    const prev = destToSrc[dest];
+    if (prev === void 0 || src.split("/").length < prev.split("/").length) {
+      destToSrc[dest] = src;
+    }
+  }
+  return destToSrc;
+}
+function flattenFederatedReleaseZip(bytes) {
+  const zip = new AdmZip2(bytes);
+  const rels = [];
+  const byNorm = /* @__PURE__ */ new Map();
+  for (const entry of zip.getEntries()) {
+    if (entry.isDirectory) continue;
+    const name = normalizeZipEntryName(entry.entryName);
+    rels.push(name);
+    byNorm.set(name, entry);
+  }
+  const plan = flattenFederatedBundlePlan(rels);
+  const keys = Object.keys(plan);
+  if (keys.length === 0) return bytes;
+  for (const dest of keys) {
+    const src = plan[dest];
+    const source = byNorm.get(src);
+    if (!source) continue;
+    zip.addFile(dest, source.getData());
+  }
+  return zip.toBuffer();
+}
+function federatedReleaseZipHint() {
+  return "Run `npm run release` in a kit from `gf apps init --slug <portal-slug>` (do not zip Vite dist/ or dist/assets/ by hand).";
+}
+
+// src/commands/apps.ts
+import AdmZip3 from "adm-zip";
 var MAX_RELEASE_BYTES = 32 * 1024 * 1024;
 function slugify2(input) {
   const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -1716,6 +1819,33 @@ async function findSiblingManifest(bundlePath) {
   }
   return { path: candidate, manifest: await readJsonObject(candidate) };
 }
+function zipHasRemoteEntry(bytes) {
+  const zip = new AdmZip3(bytes);
+  return zip.getEntries().some((entry) => {
+    if (entry.isDirectory) return false;
+    const name = normalizeZipEntryName(entry.entryName);
+    return name === REMOTE_ENTRY || name.endsWith(`/${REMOTE_ENTRY}`);
+  });
+}
+function prepareReleaseZip(bytes) {
+  if (!zipHasRemoteEntry(bytes)) {
+    throw new Error(
+      `Zip has no remoteEntry.js. ${federatedReleaseZipHint()}`
+    );
+  }
+  const flattened = flattenFederatedReleaseZip(bytes);
+  const plan = flattenFederatedBundlePlan(
+    new AdmZip3(bytes).getEntries().filter((e) => !e.isDirectory).map((e) => normalizeZipEntryName(e.entryName))
+  );
+  if (Object.keys(plan).length > 0) {
+    process.stderr.write(
+      `Note: flattened Vite dist/assets layout so chunks sit next to remoteEntry.js.
+Prefer: ${federatedReleaseZipHint()}
+`
+    );
+  }
+  return flattened;
+}
 async function isDirectory(filePath) {
   try {
     return (await fs5.stat(filePath)).isDirectory();
@@ -1826,7 +1956,12 @@ async function appsCreateCommand(opts) {
 `);
   if (kind === "shell_federated") {
     process.stdout.write(
-      "Next: npm run release && gf apps publish --path release.zip\n"
+      `Next:
+  gf apps init --slug ${slug}
+  cd ${slug} && npm install && npm run release
+  gf apps publish --path release.zip
+Do not scaffold src/App.tsx from scratch \u2014 BrowserRouter in App.tsx crashes the Shell.
+`
     );
   }
 }
@@ -1865,6 +2000,9 @@ async function appsPublishCommand(appRef, opts) {
   }
   const ext = path5.extname(bundlePath).toLowerCase();
   const isZip = ext === ".zip";
+  if (isZip) {
+    bytes = prepareReleaseZip(bytes);
+  }
   const bundle = isZip ? "zip" : "remote_entry";
   const contentType = isZip ? "application/zip" : "application/javascript";
   if (opts.syncManifest !== false && sibling) {
@@ -1900,6 +2038,192 @@ async function appsPublishCommand(appRef, opts) {
   );
 }
 
+// src/commands/apps-init.ts
+import { promises as fs6 } from "fs";
+import os3 from "os";
+import path6 from "path";
+import AdmZip4 from "adm-zip";
+var MAX_KIT_BYTES = 8 * 1024 * 1024;
+function slugify3(input) {
+  const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "app";
+}
+function titleFromSlug(slug) {
+  return slug.split("-").filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ") || slug;
+}
+async function pathExists(filePath) {
+  try {
+    await fs6.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isEmptyDir(dir) {
+  try {
+    const entries = await fs6.readdir(dir);
+    return entries.length === 0;
+  } catch (err) {
+    if (err.code === "ENOENT") return true;
+    throw err;
+  }
+}
+async function findKitRoot(extracted) {
+  const candidates = [
+    path6.join(extracted, "shell-starter-kit"),
+    extracted
+  ];
+  const entries = await fs6.readdir(extracted, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      candidates.push(path6.join(extracted, entry.name));
+    }
+  }
+  for (const candidate of candidates) {
+    if (await pathExists(path6.join(candidate, "groundfloor.manifest.json"))) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    "Starter-kit ZIP did not contain groundfloor.manifest.json. Re-download with `gf apps init`."
+  );
+}
+function stampAppIdentity(source, slug) {
+  if (!/export const APP_ID\s*=/.test(source)) {
+    throw new Error("src/appIdentity.ts does not export APP_ID");
+  }
+  const safe = slug.replace(/['"]/g, "");
+  return source.replace(
+    /export const APP_ID\s*=\s*['"][^'"]*['"]/,
+    `export const APP_ID = '${safe}'`
+  );
+}
+function stampManifest(raw, slug, name) {
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("groundfloor.manifest.json must be a JSON object");
+  }
+  const manifest = parsed;
+  manifest.appId = slug;
+  manifest.name = name;
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+async function downloadKit(url) {
+  let res;
+  try {
+    res = await fetch(url, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(6e4),
+      headers: { "User-Agent": "groundfloor-cli/0.1.1" }
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Could not download starter-kit from ${url}: ${message}`);
+  }
+  if (!res.ok) {
+    throw new Error(
+      `Starter-kit download failed (${res.status}) from ${url}`
+    );
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.byteLength === 0) {
+    throw new Error(`Starter-kit ZIP is empty: ${url}`);
+  }
+  if (bytes.byteLength > MAX_KIT_BYTES) {
+    throw new Error(
+      `Starter-kit ZIP is too large (${bytes.byteLength} bytes) from ${url}`
+    );
+  }
+  if (bytes[0] !== 80 || bytes[1] !== 75) {
+    const head = bytes.subarray(0, 80).toString("utf8");
+    throw new Error(
+      `Expected a ZIP from ${url}, got ${res.headers.get("content-type") ?? "unknown"} (${head.trim()}). Do not scaffold a federated App.tsx from memory.`
+    );
+  }
+  return bytes;
+}
+function assertSafeZipEntries(zip) {
+  for (const entry of zip.getEntries()) {
+    const name = entry.entryName.replace(/\\/g, "/");
+    if (name.startsWith("/") || name.includes("..")) {
+      throw new Error(`Refusing starter-kit ZIP with unsafe path: ${name}`);
+    }
+  }
+}
+async function appsInitCommand(opts) {
+  const rawSlug = opts.slug?.trim() ?? "";
+  if (!rawSlug) {
+    throw new Error("Pass --slug <portal-slug>.");
+  }
+  const slug = slugify3(rawSlug);
+  if (slug !== rawSlug) {
+    process.stderr.write(`Note: slug normalized to ${slug}
+`);
+  }
+  const name = opts.name?.trim() || titleFromSlug(slug);
+  const dest = path6.resolve(opts.dir?.trim() || path6.join(process.cwd(), slug));
+  const cfg = await resolveConfig();
+  const cell = cfg.environment ?? "production";
+  const kitUrl = opts.kitUrl?.trim() || starterKitZipUrl(cell);
+  if (!await isEmptyDir(dest) && !opts.force) {
+    throw new Error(
+      `Destination ${dest} is not empty. Pass --force to overwrite, or choose another --dir.`
+    );
+  }
+  if (opts.force && await pathExists(dest)) {
+    await fs6.rm(dest, { recursive: true, force: true });
+  }
+  const bytes = await downloadKit(kitUrl);
+  const zip = new AdmZip4(bytes);
+  assertSafeZipEntries(zip);
+  const tmp = await fs6.mkdtemp(path6.join(os3.tmpdir(), "gf-starter-kit-"));
+  try {
+    zip.extractAllTo(tmp, true);
+    const kitRoot = await findKitRoot(tmp);
+    await fs6.mkdir(dest, { recursive: true });
+    await fs6.cp(kitRoot, dest, { recursive: true, force: true });
+  } finally {
+    await fs6.rm(tmp, { recursive: true, force: true });
+  }
+  const identityPath = path6.join(dest, "src", "appIdentity.ts");
+  const manifestPath = path6.join(dest, "groundfloor.manifest.json");
+  const identity = await fs6.readFile(identityPath, "utf8");
+  await fs6.writeFile(identityPath, stampAppIdentity(identity, slug), "utf8");
+  const manifest = await fs6.readFile(manifestPath, "utf8");
+  await fs6.writeFile(manifestPath, stampManifest(manifest, slug, name), "utf8");
+  const result = {
+    dir: dest,
+    slug,
+    name,
+    kitUrl,
+    next: [
+      `cd ${dest}`,
+      "npm install",
+      `gf apps create --name ${JSON.stringify(name)} --slug ${slug} --kind shell_federated --manifest ./groundfloor.manifest.json`,
+      "npm run release",
+      "gf apps publish --path release.zip"
+    ]
+  };
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`Starter-kit ready in ${dest}
+`);
+  process.stdout.write(`Stamped APP_ID / manifest appId = ${slug}
+`);
+  process.stdout.write(
+    "Do not wrap src/App.tsx in BrowserRouter (DevShell already has one).\n"
+  );
+  process.stdout.write("Next:\n");
+  for (const step of result.next) {
+    process.stdout.write(`  ${step}
+`);
+  }
+}
+
 // src/commands/dataplane.ts
 async function dataplaneStatusCommand(opts) {
   const cfg = await requireWorkspace(opts.workspace);
@@ -2011,10 +2335,30 @@ files.command("download <fileId>").description("Download a file").option("-w, --
 );
 files.command("rm <fileId>").alias("delete").description("Delete a file").option("-w, --workspace <id>", "Workspace id override").action((fileId, opts) => run(() => filesRmCommand(fileId, opts)));
 var apps = program.command("apps").description(
-  "Product apps (Shell federated / standalone) \u2014 create, list, publish"
+  "Product apps (Shell federated / standalone) \u2014 init, create, list, publish"
 );
 apps.command("ls").alias("list").description("List apps").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => appsListCommand(opts)));
 apps.command("get <appId>").description("Show one app (id or slug)").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((appId, opts) => run(() => appsGetCommand(appId, opts)));
+apps.command("init").description(
+  "Download the official Shell starter-kit and stamp APP_ID / manifest appId"
+).requiredOption(
+  "--slug <slug>",
+  "Portal app slug (written to APP_ID and groundfloor.manifest.json appId)"
+).option("-n, --name <name>", "Display name (default: title-cased slug)").option(
+  "-d, --dir <path>",
+  "Destination directory (default: ./<slug>)"
+).option("--kit-url <url>", "Override starter-kit ZIP URL").option("--force", "Overwrite an existing destination directory").option("--json", "Output raw JSON").argument("[dir]", "Destination directory (same as --dir)").action(
+  (dir, opts) => run(
+    () => appsInitCommand({
+      slug: opts.slug,
+      name: opts.name,
+      dir: opts.dir || dir,
+      kitUrl: opts.kitUrl,
+      force: opts.force,
+      json: opts.json
+    })
+  )
+);
 apps.command("create").description("Register a Shell federated or standalone product app").option("-w, --workspace <id>", "Workspace id override").option("-n, --name <name>", "Display name").option("--slug <slug>", "URL-safe slug (unique in the workspace)").option(
   "--kind <kind>",
   "shell_federated (default) or standalone",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Groundfloor gf CLI — sign in, deploy coderunners, publish Shell apps, and manage secrets, files, and Dataplane.",
   "type": "module",
   "bin": {