@groundfloorcloud/mcp 0.1.15 → 0.1.16

package/dist/index.js

@@ -446,14 +446,38 @@ async function resolveMcpConfig(overrides) {
 
 // src/coderunner-runtime.ts
 var CODERUNNER_RUNTIME_BODY = `
-When a ZIP has **no Dockerfile**, Coderunner injects a language bootstrap image.
-Your process must match that image \u2014 \`gf deploy\` checks the Node bits before
-upload. A custom Dockerfile (required for \`service\` / Deployment) replaces
-the bootstrap; the listen/bind rules still apply.
+The contract depends on the workload type.
 
-## Node (no Dockerfile)
+| Type | Entrypoint (no Dockerfile) | Needs |
+|---|---|---|
+| \`function\`, \`job\`, \`schedule\` | Generated \`/app/main.js\` that does \`require('./handler')\` | Root \`handler.js\` exporting \`handler\` |
+| \`service\` (Deployment) | Your Dockerfile \`CMD\` (Dockerfile required) | \`npm start\` / \`PORT\` / bind \`0.0.0.0\` if CMD is \`npm start\` |
 
-Bootstrap is effectively:
+\`gf deploy\` checks the Node bits before upload.
+
+## Node: function, job, schedule
+
+\`npm start\` is **not** run for these types. The platform's generated
+\`/app/main.js\` loads your code with \`require('./handler')\`, so:
+
+1. Put a \`handler.js\` at the ZIP root (not nested) that exports \`handler\`.
+   \`gf deploy\` also accepts a \`package.json\` \`"main"\` that points at an
+   existing file, but \`./handler\` is the documented path; prefer \`handler.js\`.
+2. \`scripts.start\` is not required, and a server that listens on a port is
+   not needed.
+3. Missing \`handler.js\` \u2192 the new revision crash-loops
+   (\`Cannot find module './handler'\`, \`MODULE_NOT_FOUND\`) and the deployment
+   ends **Failed (status 4)**. Check \`gf coderunner logs -c <id>\`.
+
+For the handler's arguments and, for functions, the HTTP event/return shape,
+see the runtime docs (https://docs.groundfloor.cloud/docs/deploy). Do not guess
+the argument order.
+
+## Node: service (or any Dockerfile that runs \`npm start\`)
+
+A \`service\` **requires** a root Dockerfile; you own \`CMD\`. If it is
+\`npm start\` (for any type), \`package.json\` needs \`"scripts": { "start": ... }\`,
+and the process must follow the HTTP contract:
 
 \`\`\`dockerfile
 FROM node:18-alpine
@@ -464,8 +488,7 @@ ENV PORT=8080
 CMD ["npm", "start"]
 \`\`\`
 
-1. \`package.json\` **must** define \`"scripts": { "start": "node <entrypoint>" }\`.
-   Missing \`start\` \u2192 container crash loop, probe \`127.0.0.1:8080\` connection
+1. Missing \`start\` \u2192 container crash loop, probe \`127.0.0.1:8080\` connection
    refused, deployment **Failed (status 4)** after several minutes.
 2. Listen on \`Number(process.env.PORT || 8080)\`.
 3. Bind **\`0.0.0.0\`**, not \`127.0.0.1\`. Cluster traffic is not loopback.
@@ -477,29 +500,8 @@ server.listen(port, "0.0.0.0", () => {
 });
 \`\`\`
 
-Offer GET \`/\` or \`/health\` for the probe. Sample: \`samples/hello-fn/\`.
-
-## Known issue: bootstrap has been reported to skip \`npm start\`
-
-Reported 2026-09-22 against a \`function\` deploy with no Dockerfile, **unresolved as of this
-writing**: instead of running \`npm start\` per the contract above, the platform's own
-\`/app/main.js\` ran \`require('./handler')\` \u2014 a file/module contract this document does not
-describe \u2014 even though \`scripts.start\` and the entrypoint were present and correct. Symptom in
-\`gf coderunner logs -c <id>\`: \`Cannot find module './handler'\` (\`MODULE_NOT_FOUND\`), repeated
-probe \`127.0.0.1:8080\` connection refused, deployment **Failed (status 4)**. Whether \`job\` and
-\`schedule\` share this bootstrap path and are equally affected has not been confirmed either way \u2014
-treat the workaround below as precautionary for those types too if you hit the same signature.
-
-**Workaround:** add your own root \`Dockerfile\` (e.g. \`CMD ["npm", "start"]\`) and keep your
-existing \`workload_type\` \u2014 a Dockerfile bypasses the injected bootstrap entirely regardless of
-type (see "Node (with Dockerfile)" below), so this sidesteps the bug without changing how the
-workload is invoked.
-
-## Node (with Dockerfile)
-
-You own \`CMD\`. If it is \`npm start\`, you still need \`scripts.start\`.
-Listen on 8080 / \`PORT\` and bind \`0.0.0.0\`. \`service\` (Deployment)
-**requires** a root Dockerfile \u2014 bootstrap is not injected on that path.
+Offer GET \`/\` or \`/health\` for the probe. A Dockerfile whose \`CMD\` is not
+\`npm start\` replaces the generated bootstrap entirely, for any type.
 
 ## Python
 
@@ -508,16 +510,18 @@ Bind \`0.0.0.0\` and \`PORT\` (default 8080), for example
 
 ## Jobs and schedules
 
-Same package/start rules. The process may exit 0 when finished; it does not
-need a public URL. Schedules have **no** Deployment URL. Set cron with
+Node: \`handler.js\` exporting \`handler\`, same as functions (no \`npm start\`).
+They do not need a public URL. Schedules have **no** Deployment URL. Set cron with
 \`gf deploy --workload-type schedule --schedule "<cron>"\` or
 \`groundfloor.json\` \`"schedule"\`.
 
 ## What \`gf deploy\` checks
 
 - \`service\` without a root Dockerfile \u2192 fail immediately.
-- Node without a Dockerfile (or a Dockerfile that runs \`npm start\`) and no
-  \`scripts.start\` \u2192 fail immediately with this contract.
+- Node \`function\`/\`job\`/\`schedule\` without a Dockerfile and without a root
+  \`handler.js\` (or a \`package.json\` \`"main"\` that resolves to a file) \u2192 fail
+  immediately. \`scripts.start\` is not required.
+- Node with a Dockerfile that runs \`npm start\` and no \`scripts.start\` \u2192 fail immediately.
 - Listen/bind are not parsed from source; match the sample or the probe fails
   at deploy time. Check Process Log / \`gf coderunner logs -c <id>\`.
 `.trim();
@@ -571,24 +575,24 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
 
 ### Function
 
-- ZIP at archive root (\`package.json\` / \`index.js\` or \`main.py\` not nested).
-- Listen on \`process.env.PORT || 8080\`, bind **\`0.0.0.0\`** (health GET \`/\` or \`/health\`).
-- **Node:** \`package.json\` **must** include \`"scripts": { "start": "node index.js" }\`.
-  The runtime image is \`CMD ["npm", "start"]\`. Missing \`start\` \u2192 crash loop,
-  probe \`127.0.0.1:8080\` connection refused, deployment **Failed (status 4)**.
+- ZIP at archive root (\`handler.js\` / \`package.json\` or \`main.py\` not nested).
+- **Node:** a root \`handler.js\` exporting \`handler\`. The platform runs a generated
+  \`/app/main.js\` that does \`require('./handler')\`; \`npm start\` is **not** run and
+  \`scripts.start\` is not required. Missing \`handler.js\` \u2192 crash loop
+  (\`Cannot find module './handler'\`), deployment **Failed (status 4)**.
+  \`gf deploy\` fails fast on this. Handler arguments and the HTTP event/return
+  shape: see the runtime docs (\`docs_get\` id \`coderunner-runtime\`, docs.groundfloor.cloud/docs/deploy).
+- Node with your own Dockerfile (\`CMD ["npm","start"]\`) instead: listen on
+  \`process.env.PORT || 8080\`, bind **\`0.0.0.0\`** (health GET \`/\` or \`/health\`), and
+  define \`scripts.start\`.
 - Python: process must bind 0.0.0.0:\${PORT:-8080}.
 - After deploy: \`gf coderunner run -c <slug> --payload '{"hello":"world"}'\`.
-- \u26A0\uFE0F See "Known issue" in \`docs_get\` id \`coderunner-runtime\` if \`gf coderunner logs\` shows
-  \`Cannot find module './handler'\` despite a correct \`scripts.start\` \u2014 add a Dockerfile as the
-  workaround, no type change needed.
 
 ### Job
 
-- Same package rules as function. No need to serve forever; exit 0 on success.
+- Node: same as function (root \`handler.js\` exporting \`handler\`; no \`npm start\`).
+  No need to serve forever; exit 0 on success.
 - Deploy, then start a run (\`gf coderunner run\`). Check Process Log.
-- \u26A0\uFE0F Not confirmed whether the no-Dockerfile bootstrap bug in \`docs_get\` id \`coderunner-runtime\`
-  ("Known issue") also hits \`job\` \u2014 if a run never starts and logs show the same
-  \`MODULE_NOT_FOUND: './handler'\`, apply the same Dockerfile workaround.
 
 ### Schedule
 
@@ -598,8 +602,7 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
 - GET/list/status expose top-level \`workload_type\` and \`schedule\`.
   \`gf coderunner status -c <slug>\` prints type, schedule, last_job.
 - No public invoke URL. Debug with \`gf coderunner logs\`, not curl.
-- \u26A0\uFE0F Same caveat as Job: unconfirmed whether the bootstrap "Known issue" affects scheduled runs;
-  same Dockerfile workaround if you see the identical crash signature.
+- Node: same handler contract as function (root \`handler.js\`).
 
 ### Service (Deployment)
 
@@ -620,7 +623,7 @@ ENV PORT=8080
 CMD ["npm", "start"]
 \`\`\`
 
-- Still require Node \`"start"\` if CMD is \`npm start\`.
+- Services follow the \`npm start\` / \`PORT\` contract: Node needs \`scripts.start\` if CMD is \`npm start\`.
 - Prefer curling the Deployment URL (\`/health\`) over \`\u2026/run\`.
 
 ## Latest deploy rules (all types)
@@ -651,7 +654,7 @@ gf dataplane status       # provision if needed: gf dataplane provision
 gf secrets ls
 \`\`\`
 
-Local HTTP (Node function/service):
+Local HTTP (Node service, or a Dockerfile-based function):
 
 \`\`\`bash
 export PORT=8080
@@ -1144,17 +1147,17 @@ var DOC_CATALOG = [
     id: "coderunner",
     title: "Coderunner",
     path: "/docs/deploy",
-    summary: "Workload types (function, job, schedule, service/Deployment), runtime contract (scripts.start, 0.0.0.0:8080), Dockerfile for services, Coderunner identities for Vault, App authentication optional, local live data, gf deploy.",
+    summary: "Workload types (function, job, schedule, service/Deployment), runtime contract (handler.js for function/job/schedule; npm start, PORT 8080 for service), Dockerfile for services, Coderunner identities for Vault, App authentication optional, local live data, gf deploy.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-09-25"
+    lastUpdated: "2026-10-02"
   },
   {
     id: "coderunner-runtime",
     title: "Coderunner runtime contract",
     path: "/docs/deploy",
-    summary: "What the platform expects your code to do: Node bootstrap (npm start, PORT/8080, bind 0.0.0.0), Python bind, service Dockerfile.",
+    summary: "What the platform expects your code to do: Node handler.js for function/job/schedule, npm start + PORT/8080 + bind 0.0.0.0 for service/Dockerfile, Python bind.",
     embedded: CODERUNNER_RUNTIME_CONTRACT,
-    lastUpdated: "2026-09-23"
+    lastUpdated: "2026-10-02"
   },
   {
     id: "coderunner-overview",
@@ -1162,7 +1165,7 @@ var DOC_CATALOG = [
     path: "/docs/deploy",
     summary: "Architecture and lifecycle. Prefer docs_get id coderunner for type usage, Dockerfile, and create prerequisites.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-09-25"
+    lastUpdated: "2026-10-02"
   },
   {
     id: "authentication",
@@ -1250,7 +1253,7 @@ var DOC_CATALOG = [
     path: "/docs/deploy/schedules",
     summary: "workload_type=schedule plus cron. gf coderunner status shows type/schedule/last_job. Use Process Log, not a public URL.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-09-25"
+    lastUpdated: "2026-10-02"
   }
 ];
 function docUrl(entry) {
@@ -1325,7 +1328,7 @@ function suggestCli(intent, args) {
     case "deploy":
       return {
         command: name ? `gf deploy -n ${name}${ws}` : `gf deploy${ws}`,
-        why: 'Package the current (or --path) folder and deploy as a Coderunner. App authentication is optional (end-user login only). workloadType function|job|schedule|service (service = Deployment; requires a Dockerfile). Schedules need --schedule "<cron>" or groundfloor.json schedule. Node bootstrap: scripts.start, listen PORT||8080, bind 0.0.0.0. Do not create an App for this.',
+        why: 'Package the current (or --path) folder and deploy as a Coderunner. App authentication is optional (end-user login only). workloadType function|job|schedule|service (service = Deployment; requires a Dockerfile). Schedules need --schedule "<cron>" or groundfloor.json schedule. Node function/job/schedule: root handler.js exporting handler (no npm start). Node service/Dockerfile: scripts.start, listen PORT||8080, bind 0.0.0.0. Do not create an App for this.',
         docs: "https://docs.groundfloor.cloud/docs/deploy"
       };
     case "run":
@@ -1524,12 +1527,12 @@ server.tool(
           runtime_contract: "coderunner-runtime",
           before_create: "Team write can create Coderunners without App authentication. Site auth is optional (end-user login). Mode none uses Portal JWKS (GET /v1/public/jwks.json).",
           types: {
-            function: "HTTP handler on PORT/8080 bound to 0.0.0.0. Invoke with gf coderunner run or the Deployment URL. Node requires package.json scripts.start.",
-            job: "Run-to-completion worker. Deploy, then gf coderunner run.",
+            function: "Request/response handler. Invoke with gf coderunner run or the Deployment URL. Node: root handler.js exporting handler (npm start is not run); see docs_get coderunner-runtime.",
+            job: "Run-to-completion worker. Node: root handler.js exporting handler. Deploy, then gf coderunner run.",
             schedule: 'Cron job. No public Deployment URL. Set cron with gf deploy --workload-type schedule --schedule "<cron>" (or groundfloor.json schedule).',
             service: "Long-running Deployment (same type as service). Dockerfile at ZIP root is required. Listen on 8080 / 0.0.0.0."
           },
-          node: "No Dockerfile \u2192 platform injects node:18-alpine CMD npm start EXPOSE 8080. Require scripts.start; listen on PORT||8080; bind 0.0.0.0. gf deploy fails fast if scripts.start is missing.",
+          node: "function/job/schedule without a Dockerfile run a generated /app/main.js that requires ./handler: ship a root handler.js exporting handler (scripts.start not needed). service/Dockerfile running npm start: scripts.start, listen PORT||8080, bind 0.0.0.0. gf deploy fails fast on either missing.",
           local_live_data: 'eval "$(gf env)". For files/secrets as a builder use Bearer $(gf token). For Vault/Files as the deployed workload, attach an M2M client and use Bearer $(gf m2m token). Never DATAPLANE_SERVICE_API_KEY. Do not zip .env files.'
         },
         shell_app_howto: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/mcp",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {