@cloudgrid-io/mcp 0.12.0 → 0.14.0

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.

package/src/corpus/workflows/waitlist.md

@@ -0,0 +1,42 @@
+---
+name: waitlist
+when: waitlist, coming soon, early access, join the list, launch page, sign-up teaser with an email capture form. NOTE the form is static — to actually STORE signups you need a runtime app (needs: database), coming in the crud-app archetype.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. The email form posts to a configurable mailto/external endpoint; it does NOT store signups. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the waitlist template, fill it with the user's launch copy, wire the form to a mailto or external endpoint, deploy it, and return the live share URL.
+---
+
+# Workflow: waitlist
+
+Detect the intent ("build me a waitlist / coming-soon / early-access page") and
+follow this recipe. Do not ask setup questions first; use sensible defaults and
+build.
+
+**Important — the form is static.** This template captures an email and posts it
+to a configurable action: a `mailto:` (the default, which opens the visitor's
+mail client) or an external form endpoint you set on the `<form action>`. It does
+NOT store signups anywhere on CloudGrid. To actually **store** waitlist signups
+(persist, count, export them), you need a runtime app with a database
+(`needs: { database: true }`) — that is a CRUD app, coming in the crud-app
+archetype (Wave 1b). Do not claim this static page persists data.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "waitlist")` to load
+   the self-contained HTML waitlist page (hero, email form, social-proof counter).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The product name, coming-soon headline, and subheadline.
+   - The signup counter and any social-proof line.
+   - The form action: set `<form action>` to a `mailto:` address or an external
+     form endpoint. Default is `mailto:`.
+   - Keep it a single self-contained HTML file. Do not add external scripts,
+     stylesheets, fonts, or large embedded media.
+3. **Deploy.** Deploy the filled HTML:
+   - Hosted MCP edition: call the drop tool with the HTML.
+   - Local MCP / CLI edition: write the HTML to a file and run `gridctl plug`.
+   It is an inspiration and deploys synchronously, so you get a URL right away.
+4. **Return the live share URL.** For revisions, re-deploy with the entity id
+   from the first deploy — it updates the same share URL. If the user needs
+   signups stored, tell them that needs the runtime crud-app archetype (Wave 1b).
+
+Keep the whole flow tight: fetch, fill, deploy, share.