@cloudgrid-io/mcp 0.8.2 → 0.9.1

package/src/corpus/templates/app-with-data/services/web/app/layout.js

@@ -0,0 +1,32 @@
+// Root layout + plain inline CSS (no external CDNs, fonts, or stylesheets).
+export const metadata = {
+  title: "Todos",
+  description: "A persistent todo app on CloudGrid, backed by grid-shared Mongo.",
+};
+
+const css = `
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: system-ui, -apple-system, sans-serif; line-height: 1.5; }
+  main { max-width: 40rem; margin: 3rem auto; padding: 0 1.25rem; }
+  h1 { margin: 0 0 .25rem; }
+  .hint { margin: 0 0 1.5rem; opacity: .7; font-size: .9rem; }
+  .row { display: flex; gap: .5rem; margin-bottom: 1rem; }
+  input { flex: 1; padding: .5rem .75rem; border: 1px solid #8886; border-radius: .5rem; font: inherit; }
+  button { padding: .5rem .9rem; border: 1px solid #8886; border-radius: .5rem; background: #6663; font: inherit; cursor: pointer; }
+  button:disabled { opacity: .5; cursor: default; }
+  ul { list-style: none; padding: 0; margin: 0; }
+  li { display: flex; align-items: center; justify-content: space-between; gap: .5rem; padding: .6rem 0; border-bottom: 1px solid #8883; }
+  li.empty { opacity: .6; justify-content: flex-start; }
+`;
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <head>
+        <style dangerouslySetInnerHTML={{ __html: css }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/src/corpus/templates/app-with-data/services/web/app/page.js

@@ -0,0 +1,24 @@
+// Home page: a server component reads the todos straight from Mongo, and a small
+// client form adds/removes them via the API route. Data persists across refresh
+// and across users because it lives in the grid-shared Mongo, not in memory.
+import { getDb } from "../lib/db.js";
+import TodoForm from "./todo-form.js";
+
+export const dynamic = "force-dynamic";
+
+async function listTodos() {
+  const db = await getDb();
+  const items = await db.collection("todos").find({}).sort({ createdAt: -1 }).toArray();
+  return items.map((t) => ({ id: t._id.toString(), text: t.text, done: !!t.done }));
+}
+
+export default async function Page() {
+  const todos = await listTodos();
+  return (
+    <main>
+      <h1>Todos</h1>
+      <p className="hint">Persisted in the grid-shared Mongo — survives refresh.</p>
+      <TodoForm initialTodos={todos} />
+    </main>
+  );
+}

package/src/corpus/templates/app-with-data/services/web/app/todo-form.js

@@ -0,0 +1,58 @@
+"use client";
+
+// Small client component: renders the list and posts to /api/todos.
+import { useState } from "react";
+
+export default function TodoForm({ initialTodos }) {
+  const [todos, setTodos] = useState(initialTodos);
+  const [text, setText] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  async function add(e) {
+    e.preventDefault();
+    const value = text.trim();
+    if (!value) return;
+    setBusy(true);
+    const res = await fetch("/api/todos", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ text: value }),
+    });
+    if (res.ok) {
+      const todo = await res.json();
+      setTodos((prev) => [todo, ...prev]);
+      setText("");
+    }
+    setBusy(false);
+  }
+
+  async function remove(id) {
+    setBusy(true);
+    const res = await fetch(`/api/todos?id=${encodeURIComponent(id)}`, { method: "DELETE" });
+    if (res.ok) setTodos((prev) => prev.filter((t) => t.id !== id));
+    setBusy(false);
+  }
+
+  return (
+    <div>
+      <form onSubmit={add} className="row">
+        <input
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          placeholder="Add a todo…"
+          aria-label="New todo"
+        />
+        <button type="submit" disabled={busy}>Add</button>
+      </form>
+      <ul>
+        {todos.length === 0 && <li className="empty">No todos yet.</li>}
+        {todos.map((t) => (
+          <li key={t.id}>
+            <span>{t.text}</span>
+            <button type="button" onClick={() => remove(t.id)} disabled={busy}>Delete</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/corpus/templates/app-with-data/services/web/lib/db.js

@@ -0,0 +1,31 @@
+// Cached MongoDB client for the App Router.
+//
+// The grid injects the connection string as the MONGODB_URL environment variable
+// at runtime (after `grid plug`) and under `grid dev` locally. Never hardcode a
+// connection string here and never commit a secret.
+//
+// The env var and client are resolved LAZILY (inside getDb), never at module top
+// level — otherwise `next build` throws when it imports this module for route
+// analysis, before the grid injects MONGODB_URL.
+import { MongoClient } from "mongodb";
+
+function clientPromise() {
+  const uri = process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "MONGODB_URL is not set. The grid injects it automatically — run this app " +
+        "with `grid dev` locally, or deploy it with `grid plug` (the grid injects " +
+        "MONGODB_URL at runtime). Do not set it by hand.",
+    );
+  }
+  if (!globalThis.__mongoClientPromise) {
+    globalThis.__mongoClientPromise = new MongoClient(uri).connect();
+  }
+  return globalThis.__mongoClientPromise;
+}
+
+export async function getDb() {
+  const client = await clientPromise();
+  // The default DB comes from the MONGODB_URL path segment the grid injects.
+  return client.db();
+}

package/src/corpus/templates/app-with-data/services/web/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "my-app",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "mongodb": "^6.12.0"
+  }
+}

package/src/corpus/troubleshooting/persistent-apps.md

@@ -0,0 +1,22 @@
+---
+name: persistent-apps
+when: A persistent (Mongo-backed) app misbehaves — data doesn't survive refresh, MONGODB_URL is undefined, a runtime deploy seems stuck, or it won't build on hosted.
+summary: Symptom, cause, and fix for the common app-with-data (runtime Mongo app) problems — in-memory vs persistent, injected MONGODB_URL, async deploys, and the hosted-edition gate.
+---
+
+# Troubleshooting: persistent apps (app-with-data)
+
+Match the symptom to the row, apply the fix, and stop.
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Data doesn't persist / resets on refresh | You built a static inspiration (in-memory / localStorage), not a runtime app | Use the `app-with-data` workflow: a real Next.js + Mongo runtime that reads `process.env.MONGODB_URL`. Static templates keep state only in memory. |
+| `Error: Service directory not found: …/services/web` | App code lives at the repo/template root, not under the service folder | App code must live under `services/<name>/` (e.g. `services/web/`). `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path — the service name is the folder the CLI looks for. |
+| `next build` fails / MONGODB_URL error at build time | The DB env var is read at module top level; `next build` imports the module for route analysis before the grid injects the var | Read `process.env.MONGODB_URL` LAZILY inside the getter (e.g. inside `getDb`), never at module load. Moving the check into the function lets the build pass. |
+| App builds + deploys but every request 500s with `MONGODB_URL not set` | You used `needs:` in `cloudgrid.yaml`; the deployer doesn't inject the DB from `needs:` yet | Switch to `requires: [mongodb]`. The CLI warns `requires:` is deprecated, but the deployer only injects `MONGODB_URL` from `requires:` (platform bug flagged to Gilad). Keep `requires:` until `needs:` is honored. |
+| `MONGODB_URL is undefined` (or the db.js guard throws) | The env var isn't present because you're not running under the grid | Run locally with `grid dev`, or deploy with `grid plug` — the grid injects `MONGODB_URL` at dev-time and runtime. Do NOT set it yourself and never hardcode a connection string. |
+| Deploy seems stuck / no URL returned | Runtime deploys are asynchronous | `plug` returns `status: building`, not a URL. Poll `gridctl_status` (or the poll_url) until the app is live, then return the live URL. Don't treat the build/log link as the deliverable. |
+| It won't build on the hosted edition | Hosted MCP is inline-only — it can't run the CLI or folder-plug | Runtime apps need the LOCAL edition (Claude Desktop/Code) or the CLI. On hosted, tell the user persistence isn't available there and offer a static version instead. |
+| Redis not available | `redis` wasn't declared | Add `redis: private` to `requires` in `cloudgrid.yaml`; the grid then injects `REDIS_URL`. Only add it if the app actually needs Redis. |
+
+See the `app-with-data` workflow for the full recipe.

package/src/corpus/workflows/app-with-data.md

@@ -0,0 +1,115 @@
+---
+name: app-with-data
+when: The user wants an app that SAVES or PERSISTS data, shares state across users/sessions, has accounts/login, stores submissions, or needs a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook.
+summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.MONGODB_URL lazily, declare requires:[mongodb] (not needs:), deploy async, poll to a live URL.
+---
+
+# Workflow: app-with-data
+
+The user wants an app that actually **remembers** things — a to-do list that
+survives a refresh, a form whose submissions are stored, a dashboard whose data
+sticks, anything with accounts or shared state. That is NOT a static page: it is
+a **runtime app** backed by the grid's shared Mongo (and optionally Redis). A
+static template keeps state only in memory and loses it on refresh.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI, because the grid must run
+the CLI and folder-plug your project.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly: "A persistent app needs the local edition (Claude Desktop/Code) or
+  the CloudGrid CLI; the hosted edition can only publish static pages." Then
+  offer to build a **static version** instead (an in-memory / localStorage
+  to-do page via the `web-app` workflow) and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+Persistent apps are owned entities.
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use (per the existing `resolveGridOrAsk` behavior); do not
+   assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>` (the default `--type` is fine). `init` creates
+the entity + `.cloudgrid/link.json` and writes a `cloudgrid.yaml` with an EMPTY
+`services: {}`. `plug` needs a linked directory, so run `init` FIRST.
+
+You then do two things: (a) write the app under **`services/web/`**, and (b) fill
+in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml` to declare the `web` service and the store it needs.
+   **App code MUST live under `services/<name>/`** — `path:` is the URL mount,
+   NOT the filesystem path. A service named `web` → the CLI looks for
+   `services/web/`; app files at the repo root fail with
+   `Error: Service directory not found: …/services/web`.
+   ```yaml
+   name: my-app
+   services:
+     web:
+       type: nextjs
+       path: /
+   requires:
+     - mongodb        # alias: db
+     # - redis: private   # OPTIONAL — add only if the app needs Redis
+   ```
+   **Declare the datastore with `requires: [mongodb]` (NOT `needs:`)** — see the
+   yaml comment in the template. The CLI warns `requires:` is deprecated, but the
+   deployer only injects `MONGODB_URL` from `requires:`; `needs:` builds fine but
+   injects NO DB connection (every request 500s). Keep `requires:` until the
+   deployer honors `needs:`.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "app-with-data")`. It is a minimal, real
+   Next.js + `mongodb`-driver to-do app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `todos`
+   collection, and a page.
+3. Adapt it to the user's app (rename the collection, change the fields, adjust
+   the UI). **Read the database from `process.env.MONGODB_URL`** — the grid
+   injects that env var at dev-time and runtime. Never hardcode a connection
+   string; never commit a secret.
+   - **Put the DB connection behind a lazy getter — never read
+     `process.env.MONGODB_URL` at module top level, or `next build` fails** (the
+     module is imported for route analysis before the grid injects the var).
+   - (Optional) fetch `gridctl_fetch("example", "app-with-data")` for a slightly
+     richer filled reference to imitate.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+and sanity-check before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`.
+- Non-secret config → `gridctl_env`.
+- Do **NOT** set `MONGODB_URL` or `REDIS_URL` yourself — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — keep the user informed, never a
+  bare silent wait.
+- Only once it is live, return the deployed URL (the app URL, NOT the build/log
+  link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug
+the SAME entity (`target_entity_id`) so it updates the same URL. Runtime re-plug
+uses the CLI path (`cloudgrid plug` in the linked folder), per the plug
+description.
+
+Keep it honest: async build, local-edition only, credentials injected by the
+grid.