@cloudgrid-io/mcp 0.13.0 → 0.14.0

package/src/corpus/workflows/subscription-management.md

@@ -0,0 +1,141 @@
+---
+name: subscription-management
+when: "subscription management, manage subscriptions, self-serve plans/billing"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus Stripe subscription secrets. Runtime app, async build, local edition only. Declare needs { database: true } (deployer injects DATABASE_MONGODB_URL / legacy MONGODB_URL) and a vault block mapping STRIPE_KEY / STRIPE_WEBHOOK_SECRET to env vars. This is a BLUEPRINT — read AGENTS.md for the structure, then build."
+summary: "Build a self-serve subscription-management app on the grid — a Next.js app where a signed-in customer views their current plan, changes/upgrades/downgrades or cancels it, and manages billing via the Stripe Billing Portal, with a Stripe webhook syncing local state and grid-shared Mongo (customers + subscriptions collections). This is a BLUEPRINT: fetch the template, read AGENTS.md for the file tree + CloudGrid wiring (needs database true, vault for Stripe secrets), build the app under services/web/, deploy async, poll to a live URL."
+---
+
+# Workflow: subscription-management
+
+The user wants self-serve subscription management: a signed-in customer sees
+their current plan, upgrades/downgrades or cancels it, and manages billing (card,
+invoices, receipts) — with the app's state staying in sync with Stripe. That is a
+**persistent runtime app** — a Next.js app backed by the grid's shared Mongo,
+with Stripe subscription updates, the Stripe Billing Portal, and a webhook that
+keeps local subscription state authoritative.
+
+This is the **manage-what-you-already-have** surface. If the user actually wants
+the sign-up + paywall + gated-content acquisition flow, that is the
+`membership-site` workflow instead — the two share the same Stripe + Mongo wiring.
+
+This is a **blueprint**, not a fill-in template. There is no finished app to
+copy — there is a `cloudgrid.yaml` and a structure guide (`AGENTS.md`). Read the
+guide, then build the app following it. 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 subscription-management app is a built + deployed container. It requires the
+**local edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **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, offer a **static pricing/plans page** instead, and STOP the runtime
+  path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+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; do not assume a target.
+
+## 3. Read the blueprint
+
+Fetch the template and read its structure guide — this is the core of the
+workflow:
+
+- `gridctl_fetch("template", "subscription-management")` — the `cloudgrid.yaml` +
+  **`AGENTS.md`**. AGENTS.md has the file tree, the Mongo collections
+  (`customers`, `subscriptions`), the CloudGrid injection table, and the Stripe
+  change-plan / cancel / billing-portal / webhook wiring. **Read it fully before
+  building.**
+- `gridctl_fetch("template", "app-with-data")` — the proven Next.js + Mongo
+  shape this blueprint extends (lazy db client in `lib/db.js`, App-Router
+  GET/POST route). Imitate its wiring.
+
+## 4. Scaffold
+
+`gridctl_init` an app `<name>`. `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. Then write the app under **`services/web/`** and
+set `cloudgrid.yaml` to the active shape below.
+
+## 5. Build the app following AGENTS.md
+
+Build the file tree from AGENTS.md under `services/web/`: the lazy Mongo client,
+the lazy Stripe client, the plan catalog (`lib/plans.js`), the auth middleware,
+the subscription (change-plan) + cancel + billing-portal + webhook API routes,
+and the `/account` dashboard. Adapt the plans and document fields to the user.
+Key non-negotiables:
+
+- **App code under `services/web/`** — `path:` is the URL mount, NOT the
+  filesystem path. Root files fail with `Service directory not found`.
+- **Read the DB LAZILY** from `process.env.DATABASE_MONGODB_URL` (legacy
+  `process.env.MONGODB_URL` fallback) inside the getter — never at module top
+  level, or `next build` fails.
+- **Read secrets LAZILY** too — `process.env.STRIPE_KEY`,
+  `STRIPE_WEBHOOK_SECRET` — inside getters, never top-level.
+- **The webhook is the source of truth.** The change-plan and cancel APIs call
+  Stripe; do NOT write plan/status to Mongo there — let `/api/webhook` reconcile
+  the `subscriptions` collection so Stripe and Mongo never diverge. Read
+  plan/status server-side from Mongo; validate requested plans against
+  `lib/plans.js` (never accept an arbitrary price id from the client).
+- **Tie every action to the signed-in user** — resolve `userRef` server-side and
+  only ever act on that user's `stripeCustomerId`.
+
+`cloudgrid.yaml` active shape:
+
+```yaml
+name: my-subscription-management
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+```
+
+**Declare the datastore with `needs: { database: true }`** — the canonical
+shape. `requires:` is the deprecated v1 alias; don't author new yaml with it, and
+never set `needs:` and `requires:` together (the validator rejects it).
+
+## 6. Config / secrets
+
+- Stripe secrets → `gridctl_secrets` (set the vault items `stripe-live-key` and
+  `stripe-webhook-secret` that the `vault:` block maps from). The deployer
+  injects each as its env var at runtime and under `grid dev`. Add
+  `auth-provider-key` too if you use an auth SDK.
+- Non-secret config (Stripe publishable key `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`,
+  price ids, auth publishable key) → `gridctl_env` / `services.web.env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 7. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+and vault secrets before deploying. Don't require it.
+
+## 8. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, 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 — never a bare silent wait.
+- Once live, register the `/api/webhook` URL as the Stripe webhook endpoint,
+  copy the signing secret into the `stripe-webhook-secret` vault item, configure
+  the Billing Portal in the Stripe dashboard, and re-plug. Return the deployed
+  app URL (NOT the build/log link).
+
+## 9. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, DB injected by the grid, secrets injected from the vault.

package/src/corpus/workflows/ticket-system.md

@@ -0,0 +1,101 @@
+---
+name: ticket-system
+when: ticket system, support tickets, helpdesk, issue tracker, support queue — a persistent app that stores tickets (subject, requester, status, priority, body) with status changes. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo support ticket queue on the grid — a `tickets` collection (subject, requester, status open/pending/closed, priority, body) with add / status-change / delete. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: ticket-system
+
+The user wants a tickets app that **remembers** its
+records — they survive refresh and are shared across sessions. That is a
+**runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with a `tickets` domain
+(subject, requester, status of open/pending/closed, priority, body) and a table view with add, per-row status changes, and delete.
+
+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.
+
+- **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, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+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; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `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. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-tickets
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it). The template ships this file in the **full-annotated
+   reference form** — every field present as a comment, only `name`,
+   `services.web`, and `needs.database` uncommented — so it deploys to exactly
+   those active fields.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "ticket-system")`. It is a minimal, real Next.js +
+   `mongodb`-driver app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH (status)/DELETE route on a `tickets` collection, a
+   server-component page, and a client component.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, 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 — never a bare silent wait.
+- Only once it is live, return the deployed 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 so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/time-tracking.md

@@ -0,0 +1,104 @@
+---
+name: time-tracking
+when: time tracking, timesheet, hours logger, billable hours — a persistent app that logs time entries (task, project, minutes, date) and totals hours per project. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo time tracker on the grid — an `entries` collection (task, project, minutes:number, date) with add / list / delete and totals per project. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: time-tracking
+
+The user wants a time tracker / timesheet / billable-hours logger that
+**remembers** its entries — hours that survive refresh and are shared across
+sessions. That is a **runtime app** backed by the grid's shared Mongo, not a
+static page. It is the same proven shape as `app-with-data`, with an `entries`
+domain (task, project, minutes, date), an add form, a list of entries, and a
+per-project totals table.
+
+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.
+
+- **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, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+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; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `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. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-tracker
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "time-tracking")`. It is a minimal, real Next.js +
+   `mongodb`-driver time tracker under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on an `entries`
+   collection, a server-component page, and a client form that also renders
+   per-project totals.
+3. Adapt it (rename the collection, change fields, adjust the UI). The domain is
+   `entries {task, project, minutes:number, date}`: add an entry, list entries,
+   total minutes per project. **Read the DB from
+   `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - The route handler is `export const dynamic = "force-dynamic"` so time
+     entries are always read/written live.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, 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 — never a bare silent wait.
+- Only once it is live, return the deployed 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 so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/travel-booking.md

@@ -0,0 +1,115 @@
+---
+name: travel-booking
+when: travel booking portal, trip booking, flights/hotels booking, book a flight, book a hotel, travel reservations — a persistent app where users search and book flights/hotels and manage trips that survive refresh and are shared across sessions. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo). Runtime app, async build, local edition only. BLUEPRINT — ships structure + cloudgrid.yaml, not app code; read AGENTS.md and build. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Payment/auth secrets via the `vault:` block → env vars. Trip-reminder cron is NOT yet deployable (platform issue #1543)."
+summary: "Build a persistent Next.js + Mongo travel booking portal on the grid — `flights`, `hotels`, `bookings`, `trips` collections with search + availability logic, Stripe checkout, an auth provider, and a (pending) trip-reminder cron. This is a BLUEPRINT: fetch it, read AGENTS.md for the file tree + data model + CloudGrid wiring, then build the app under services/web/. Edition-gate first, scaffold, declare needs:{database:true} (not requires:), map secrets via vault:, deploy async, poll to a live URL."
+---
+
+# Workflow: travel-booking
+
+The user wants a travel booking portal — search and book flights and hotels, pay,
+and manage trips — that **remembers** its bookings across refresh and sessions.
+That is a **runtime app** backed by the grid's shared Mongo, not a static page.
+The proven runtime shape is the same as `app-with-data` (Next.js + lazy Mongo
+client under `services/web/`), with a travel domain (`flights`, `hotels`,
+`bookings`, `trips` with overbooking protection), Stripe checkout for paid
+bookings, an auth provider for accounts, and a scheduled trip-reminder job.
+
+**This is a BLUEPRINT.** It does NOT ship prewritten app code — it ships the
+annotated `cloudgrid.yaml` and an `AGENTS.md` structure guide (file tree, Mongo
+data model, and CloudGrid wiring). Fetch it, **read `AGENTS.md`**, then build the
+app under `services/web/` following it.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop), that it needs the local edition, and that the trip-reminder **cron
+service is not yet deployable** (platform issue #1543).
+
+## 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.
+
+- **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,
+  offer a **static preview** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+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; do not assume a target.
+
+## 3. Read the blueprint, then scaffold
+
+1. Fetch the blueprint: `gridctl_fetch("template", "travel-booking")`. **Read its
+   `AGENTS.md`** — it is the structure guide (file tree under `services/web/`, the
+   `flights` / `hotels` / `bookings` / `trips` collections + the overbooking
+   guard, how CloudGrid injects the DB and vault secrets, how to wire Stripe +
+   auth, and the trip-reminder-cron design).
+2. `gridctl_init` an app `<name>`. `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.
+
+## 4. Build the app + set cloudgrid.yaml
+
+1. Build the files under **`services/web/`** per the AGENTS.md file tree. **App
+   code MUST live under `services/<name>/`** — `path:` is the URL mount, NOT the
+   filesystem path.
+2. Set `cloudgrid.yaml` to the blueprint shape:
+   ```yaml
+   name: my-travel-booking
+   vault:
+     STRIPE_KEY: stripe-live-key
+     STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+     AUTH_PROVIDER_KEY: auth-provider-key
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+3. **Read every injected var lazily** (inside a getter), never at module top level
+   — `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`, and the vault
+   secrets (`STRIPE_KEY`, etc.) the same way. A top-level read fails `next build`.
+4. **Keep the trip-reminder cron COMMENTED.** cron deploy is PENDING platform
+   issue #1543 — `plug` rejects a `type: cron` service. Ship `web` alone; use the
+   stopgap in AGENTS.md §7 for reminders until #1543 lands.
+
+## 5. Config (secrets)
+
+- Payment/auth secrets → add the vault items with `gridctl_secrets` (e.g.
+  `stripe-live-key`, `stripe-webhook-secret`, `auth-provider-key`) BEFORE plug so
+  the `vault:` mappings resolve. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 6. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo +
+vault env vars before deploying. Good for testing search/availability logic. Don't
+require it.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, 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 — never a bare silent wait.
+- Only once it is live, return the deployed 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 so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid, and the trip-reminder cron pending #1543.