@groundfloorcloud/cli 0.1.4 → 0.1.6

package/README.md

@@ -23,7 +23,12 @@ Without a global install:
 npx @groundfloorcloud/cli login
 ```
 
-Requires Node.js 20 or later. `gf login` signs in to production
+Requires Node.js 20 or later. `gf` checks npm at most once a day and prints a
+one-line upgrade notice when a newer `@groundfloorcloud/cli` exists. Unknown
+subcommands include the installed vs latest version so a stale binary is not
+read as wrong docs.
+
+`gf login` signs in to production
 (`https://platform.groundfloor.cloud`). Use `--dev` or `--stage` for
 other cells; later commands reuse that session.
 
@@ -65,7 +70,7 @@ Authentication, mode `groundfloor` or `external`) until the realm is active.
 
 | `--workload-type` | Also called | Package notes |
 |-------------------|-------------|---------------|
-| `function` | Function | HTTP on `PORT`/8080. Node needs `scripts.start`. |
+| `function` | Function | HTTP on `0.0.0.0:PORT`/8080. Node needs `scripts.start`. |
 | `job` | Background job | Run-to-completion. Then `gf coderunner run`. |
 | `schedule` | Scheduled job | Cron. No public URL. |
 | `service` | **Deployment** | Long-running HTTP. **Root `Dockerfile` is required.** |
@@ -88,7 +93,9 @@ How the target is chosen:
 
 Runtime is auto-detected when omitted (`package.json` → node,
 `requirements.txt` / `pyproject.toml` → python), defaulting to python.
-Node images run `npm start` — add `"scripts": { "start": "node index.js" }`.
+Node without a Dockerfile uses the platform bootstrap (`CMD ["npm","start"]`,
+port 8080). Add `"scripts": { "start": "node index.js" }` and bind
+`0.0.0.0`. `gf deploy` fails immediately if `scripts.start` is missing.
 
 ### Local with live data
 
@@ -201,6 +208,7 @@ gf apps get <id|slug>
 | `gf workspaces` (`ws`) | List workspaces; `gf workspaces use <id>` sets the default. |
 | `gf coderunner ls` (`cr ls`) | List coderunners. |
 | `gf coderunner status -c <id\|slug>` | Status and current deployment. |
+| `gf coderunner logs -c <id\|slug>` | Process Log (stdout/stderr). Also printed automatically on `gf deploy` failure. |
 | `gf coderunner run -c <id\|slug> [--payload '{}']` | Invoke a deployed function or job. |
 | `gf deploy` | Package code and deploy as a coderunner. |
 | `gf domains ls\|add\|rm\|verify -c <id\|slug>` | Custom domains for a service. |

package/dist/index.js

@@ -2,6 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
+import path9 from "path";
 
 // src/auth/store.ts
 import { promises as fs } from "fs";
@@ -62,6 +63,7 @@ async function updateConfig(patch) {
   await writeConfig(next);
   return next;
 }
+var paths = { CONFIG_DIR, AUTH_FILE, CONFIG_FILE };
 
 // src/auth/config.ts
 var CELLS = {
@@ -533,9 +535,9 @@ async function parseError(res) {
   }
   return `${res.status} ${detail}`;
 }
-async function cpGet(apiUrl, path7) {
+async function cpGet(apiUrl, path10) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path7}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     headers: {
       Authorization: `Bearer ${token}`,
       Accept: "application/json"
@@ -546,9 +548,9 @@ async function cpGet(apiUrl, path7) {
   }
   return await res.json();
 }
-async function cpPostJson(apiUrl, path7, body) {
+async function cpPostJson(apiUrl, path10, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path7}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -562,9 +564,9 @@ async function cpPostJson(apiUrl, path7, body) {
   }
   return await res.json();
 }
-async function cpDelete(apiUrl, path7) {
+async function cpDelete(apiUrl, path10) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path7}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "DELETE",
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
   });
@@ -572,9 +574,9 @@ async function cpDelete(apiUrl, path7) {
     throw new CpError(res.status, await parseError(res));
   }
 }
-async function cpPutJson(apiUrl, path7, body) {
+async function cpPutJson(apiUrl, path10, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path7}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "PUT",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -588,9 +590,9 @@ async function cpPutJson(apiUrl, path7, body) {
   }
   return await res.json();
 }
-async function cpPatchJson(apiUrl, path7, body) {
+async function cpPatchJson(apiUrl, path10, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path7}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "PATCH",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -604,9 +606,9 @@ async function cpPatchJson(apiUrl, path7, body) {
   }
   return await res.json();
 }
-async function cpPutBytes(apiUrl, path7, body, contentType) {
+async function cpPutBytes(apiUrl, path10, body, contentType) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path7}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "PUT",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -724,6 +726,18 @@ function runCoderunner(apiUrl, workspaceId, coderunnerId, payload) {
     payload
   );
 }
+function getProcessLogs(apiUrl, workspaceId, query = {}) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value == null || value === "") continue;
+    params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return cpGet(
+    apiUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/logs${qs ? `?${qs}` : ""}`
+  );
+}
 function domainsBase(workspaceId, coderunnerId) {
   return `/v1/workspaces/${encodeURIComponent(
     workspaceId
@@ -1003,9 +1017,188 @@ async function coderunnerListCommand(opts) {
   }
 }
 
+// src/process-log.ts
+var PROCESS_STATUS_LABELS = {
+  1: "Pending",
+  2: "Processing",
+  3: "Completed",
+  4: "Failed",
+  5: "Deleting",
+  6: "Deleted",
+  7: "Stopped"
+};
+function statusLabel(status) {
+  if (status == null) return "unknown";
+  const name = PROCESS_STATUS_LABELS[status];
+  return name ? `${name} (${status})` : `status=${status}`;
+}
+function customerPortalOrigin(apiUrl) {
+  try {
+    const url = new URL(apiUrl);
+    url.host = url.host.replace(/^platform\./, "app.");
+    return url.origin;
+  } catch {
+    return "https://app.groundfloor.cloud";
+  }
+}
+function processLogPortalUrl(portalOrigin, workspaceId, runnerId) {
+  const params = new URLSearchParams({
+    workspace_id: workspaceId,
+    runner_id: runnerId
+  });
+  return `${portalOrigin.replace(/\/+$/, "")}/process-log?${params.toString()}`;
+}
+function formatLogPreview(entries, limit = 20) {
+  const slice = entries.slice(0, limit);
+  return [...slice].reverse().map((entry) => {
+    const ts = entry.ts?.trim() ? `${entry.ts} ` : "";
+    return `${ts}${entry.line}`;
+  }).join("\n");
+}
+function formatDeployFailure(input) {
+  const lines = [input.headline, ""];
+  lines.push(`coderunner:  ${input.coderunnerId}`);
+  if (input.versionId) lines.push(`version:     ${input.versionId}`);
+  if (input.deploymentId) lines.push(`deployment:  ${input.deploymentId}`);
+  if (input.status != null) lines.push(`status:      ${statusLabel(input.status)}`);
+  if (input.logLines) {
+    lines.push("", "logs:", input.logLines);
+  } else {
+    lines.push("", "logs:        (none yet)");
+  }
+  if (input.portalUrl) {
+    lines.push("", `portal:      ${input.portalUrl}`);
+  }
+  lines.push(`more logs:   gf coderunner logs -c ${input.coderunnerId}`);
+  return lines.join("\n");
+}
+async function fetchFailureLogEntries(apiUrl, workspaceId, ids) {
+  const attempts = [];
+  if (ids.deploymentId) attempts.push({ deployment_id: ids.deploymentId });
+  attempts.push({ runner_id: ids.coderunnerId });
+  if (ids.versionId && ids.versionId !== ids.coderunnerId) {
+    attempts.push({ runner_id: ids.versionId });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let lastError;
+  let anyOk = false;
+  for (const query of attempts) {
+    const key = JSON.stringify(query);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    try {
+      const page = await getProcessLogs(apiUrl, workspaceId, {
+        ...query,
+        limit: 20,
+        since_seconds: 3600
+      });
+      anyOk = true;
+      if (page.entries?.length) return page.entries;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  if (!anyOk && lastError) throw lastError;
+  return [];
+}
+async function diagnoseDeployFailure(opts) {
+  let logLines = "";
+  try {
+    const entries = await fetchFailureLogEntries(opts.apiUrl, opts.workspaceId, {
+      coderunnerId: opts.coderunnerId,
+      versionId: opts.versionId ?? void 0,
+      deploymentId: opts.deploymentId ?? void 0
+    });
+    logLines = formatLogPreview(entries);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logLines = `(could not fetch Process Log: ${message})`;
+  }
+  const runnerForPortal = opts.deploymentId || opts.coderunnerId;
+  return formatDeployFailure({
+    headline: opts.headline,
+    coderunnerId: opts.coderunnerId,
+    versionId: opts.versionId,
+    deploymentId: opts.deploymentId,
+    status: opts.status,
+    logLines,
+    portalUrl: processLogPortalUrl(
+      customerPortalOrigin(opts.apiUrl),
+      opts.workspaceId,
+      runnerForPortal
+    )
+  });
+}
+
+// src/resolve-coderunner.ts
+async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
+  const list = await listCoderunners(apiUrl, workspaceId);
+  const match = list.find((c) => c.id === idOrSlug || c.slug === idOrSlug);
+  if (!match) {
+    throw new Error(`Coderunner not found: ${idOrSlug}`);
+  }
+  return match.id;
+}
+
+// src/commands/logs.ts
+async function logsCommand(opts) {
+  const cfg = await resolveConfig({ workspaceId: opts.workspace });
+  if (!cfg.workspaceId) {
+    throw new Error(
+      "No workspace selected. Run `gf workspaces use <id>` or pass --workspace <id>."
+    );
+  }
+  const coderunnerId = await resolveCoderunnerId(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.coderunner
+  );
+  const limit = opts.limit ? Number(opts.limit) : 50;
+  const sinceSeconds = opts.sinceSeconds ? Number(opts.sinceSeconds) : 3600;
+  if (!Number.isFinite(limit) || limit < 1) {
+    throw new Error("Invalid --limit (expected a positive number).");
+  }
+  if (!Number.isFinite(sinceSeconds) || sinceSeconds < 10) {
+    throw new Error("Invalid --since-seconds (minimum 10).");
+  }
+  const page = await getProcessLogs(cfg.apiUrl, cfg.workspaceId, {
+    runner_id: coderunnerId,
+    limit,
+    since_seconds: sinceSeconds,
+    search: opts.search
+  });
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(page, null, 2)}
+`);
+    return;
+  }
+  const preview = formatLogPreview(page.entries ?? [], limit);
+  if (!preview) {
+    process.stdout.write("No log entries.\n");
+  } else {
+    process.stdout.write(`${preview}
+`);
+  }
+  if (page.has_more) {
+    process.stdout.write(
+      `(more available \u2014 raise --limit or narrow --since-seconds)
+`
+    );
+  }
+  process.stdout.write(
+    `
+portal: ${processLogPortalUrl(
+      customerPortalOrigin(cfg.apiUrl),
+      cfg.workspaceId,
+      coderunnerId
+    )}
+`
+  );
+}
+
 // src/commands/deploy.ts
-import { promises as fs3 } from "fs";
-import path3 from "path";
+import { promises as fs4 } from "fs";
+import path4 from "path";
 
 // src/deploy/package.ts
 import { execFile } from "child_process";
@@ -1173,6 +1366,45 @@ async function detectRuntime(dir) {
   return null;
 }
 
+// src/deploy/preflight.ts
+import { promises as fs3 } from "fs";
+import path3 from "path";
+var NODE_BOOTSTRAP_MISSING_START = 'Node packages without a Dockerfile use the platform bootstrap image (CMD ["npm","start"], EXPOSE 8080). Add package.json "scripts": { "start": "node <entrypoint>" }. The process must listen on process.env.PORT || 8080 and bind 0.0.0.0 (not 127.0.0.1).';
+var NODE_BOOTSTRAP_MISSING_PACKAGE = 'Node packages without a Dockerfile need package.json with "scripts.start" (bootstrap image runs `npm start` and probes 0.0.0.0:8080).';
+var NODE_DOCKERFILE_NPM_START_MISSING = 'Dockerfile runs `npm start` but package.json has no "scripts.start". Add "scripts": { "start": "node <entrypoint>" }.';
+function dockerfileRunsNpmStart(text) {
+  return /npm["'\s,]+start/.test(text);
+}
+async function readOptional(filePath) {
+  try {
+    return await fs3.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function preflightNodePackage(sourceDir) {
+  const dockerfile = await readOptional(path3.join(sourceDir, "Dockerfile"));
+  const needsStartScript = dockerfile == null || dockerfileRunsNpmStart(dockerfile);
+  if (!needsStartScript) return;
+  const raw = await readOptional(path3.join(sourceDir, "package.json"));
+  if (raw == null) {
+    throw new Error(
+      dockerfile == null ? NODE_BOOTSTRAP_MISSING_PACKAGE : NODE_DOCKERFILE_NPM_START_MISSING
+    );
+  }
+  let npm;
+  try {
+    npm = JSON.parse(raw);
+  } catch {
+    throw new Error("package.json is not valid JSON.");
+  }
+  if (!npm.scripts?.start?.trim()) {
+    throw new Error(
+      dockerfile == null ? NODE_BOOTSTRAP_MISSING_START : NODE_DOCKERFILE_NPM_START_MISSING
+    );
+  }
+}
+
 // src/commands/deploy.ts
 var RUNTIMES = /* @__PURE__ */ new Set(["python", "node", "dotnet-script"]);
 var WORKLOAD_TYPES = /* @__PURE__ */ new Set(["function", "service", "job", "schedule"]);
@@ -1202,6 +1434,9 @@ function parseEnvPairs(pairs) {
 }
 var log = (msg) => process.stderr.write(`${msg}
 `);
+async function failDeploy(opts) {
+  throw new Error(await diagnoseDeployFailure(opts));
+}
 async function deployCommand(opts) {
   const cfg = await resolveConfig({
     apiUrl: opts.apiUrl,
@@ -1214,7 +1449,7 @@ async function deployCommand(opts) {
   }
   const ws = cfg.workspaceId;
   log(
-    opts.git ? `Cloning ${opts.git}${opts.ref ? ` (${opts.ref})` : ""}...` : `Packaging ${path3.resolve(opts.path ?? process.cwd())}...`
+    opts.git ? `Cloning ${opts.git}${opts.ref ? ` (${opts.ref})` : ""}...` : `Packaging ${path4.resolve(opts.path ?? process.cwd())}...`
   );
   const pkg = await packageSource({
     path: opts.path,
@@ -1241,7 +1476,7 @@ async function deployCommand(opts) {
     }
     if (workloadType === "service") {
       try {
-        await fs3.access(path3.join(pkg.sourceDir, "Dockerfile"));
+        await fs4.access(path4.join(pkg.sourceDir, "Dockerfile"));
       } catch {
         throw new Error(
           'workload type "service" (also called Deployment) requires a Dockerfile at the project root.'
@@ -1249,26 +1484,11 @@ async function deployCommand(opts) {
       }
     }
     if (runtime === "node") {
-      try {
-        const raw = await fs3.readFile(
-          path3.join(pkg.sourceDir, "package.json"),
-          "utf8"
-        );
-        const npm = JSON.parse(raw);
-        if (!npm.scripts?.start?.trim()) {
-          throw new Error(
-            'Node Coderunner packages require package.json "scripts.start" (runtime CMD is npm start).'
-          );
-        }
-      } catch (err) {
-        if (err instanceof Error && err.message.includes("scripts.start")) {
-          throw err;
-        }
-      }
+      await preflightNodePackage(pkg.sourceDir);
     }
     let coderunnerId = opts.coderunner;
     if (!coderunnerId) {
-      const name = opts.name ?? manifest.name ?? (opts.git ? nameFromGitUrl(opts.git) : path3.basename(path3.resolve(opts.path ?? process.cwd())));
+      const name = opts.name ?? manifest.name ?? (opts.git ? nameFromGitUrl(opts.git) : path4.basename(path4.resolve(opts.path ?? process.cwd())));
       const slug = manifest.slug ?? slugify(name);
       const existing = await listCoderunners(cfg.apiUrl, ws);
       const match = existing.find((c) => c.slug === slug || c.name === name);
@@ -1317,16 +1537,38 @@ async function deployCommand(opts) {
         break;
       }
       if (status === 4) {
-        throw new Error(
-          `Build failed for version ${uploaded.version_id} (status=4).`
-        );
+        return await failDeploy({
+          apiUrl: cfg.apiUrl,
+          workspaceId: ws,
+          headline: `Build failed for version ${uploaded.version_id} (${statusLabel(4)}).`,
+          coderunnerId,
+          versionId: uploaded.version_id,
+          status: 4
+        });
       }
       process.stderr.write(".");
       await new Promise((r) => setTimeout(r, VERSION_POLL_INTERVAL_MS));
     }
     process.stderr.write("\n");
     if (!built) {
-      throw new Error("Timed out waiting for the build to complete.");
+      let lastStatus = null;
+      try {
+        lastStatus = (await getVersion(
+          cfg.apiUrl,
+          ws,
+          coderunnerId,
+          uploaded.version_id
+        )).status ?? null;
+      } catch {
+      }
+      return await failDeploy({
+        apiUrl: cfg.apiUrl,
+        workspaceId: ws,
+        headline: "Timed out waiting for the build to complete.",
+        coderunnerId,
+        versionId: uploaded.version_id,
+        status: lastStatus
+      });
     }
     log("Build completed.");
     if (opts.skipDeploy) {
@@ -1358,16 +1600,38 @@ async function deployCommand(opts) {
         break;
       }
       if (dStatus === 4) {
-        throw new Error(
-          `Deployment failed for coderunner ${coderunnerId} (status=4).`
-        );
+        return await failDeploy({
+          apiUrl: cfg.apiUrl,
+          workspaceId: ws,
+          headline: `Deployment failed for coderunner ${coderunnerId} (${statusLabel(4)}).`,
+          coderunnerId,
+          versionId: uploaded.version_id,
+          deploymentId: result.deployment_id ?? deployment?.id,
+          status: 4
+        });
       }
       process.stderr.write(".");
       await new Promise((r) => setTimeout(r, DEPLOY_POLL_INTERVAL_MS));
     }
     process.stderr.write("\n");
     if (!deployOk) {
-      throw new Error("Timed out waiting for the deployment to complete.");
+      let lastStatus = null;
+      let deploymentId = result.deployment_id;
+      try {
+        const latest = await getDeployment(cfg.apiUrl, ws, coderunnerId);
+        lastStatus = latest?.status ?? null;
+        deploymentId = latest?.id ?? deploymentId;
+      } catch {
+      }
+      return await failDeploy({
+        apiUrl: cfg.apiUrl,
+        workspaceId: ws,
+        headline: "Timed out waiting for the deployment to complete.",
+        coderunnerId,
+        versionId: uploaded.version_id,
+        deploymentId,
+        status: lastStatus
+      });
     }
     log("Deployment completed.");
     process.stdout.write(`
@@ -1388,21 +1652,13 @@ Deployed coderunner ${coderunnerId}
     }
   } finally {
     if (pkg.cleanup) {
-      await fs3.rm(pkg.cleanup, { recursive: true, force: true }).catch(() => {
+      await fs4.rm(pkg.cleanup, { recursive: true, force: true }).catch(() => {
       });
     }
   }
 }
 
 // src/commands/run.ts
-async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
-  const list = await listCoderunners(apiUrl, workspaceId);
-  const match = list.find((c) => c.id === idOrSlug || c.slug === idOrSlug);
-  if (!match) {
-    throw new Error(`Coderunner not found: ${idOrSlug}`);
-  }
-  return match.id;
-}
 async function runCommand(opts) {
   const cfg = await resolveConfig({ workspaceId: opts.workspace });
   if (!cfg.workspaceId) {
@@ -1436,14 +1692,6 @@ async function runCommand(opts) {
 }
 
 // src/commands/status.ts
-async function resolveCoderunnerId2(apiUrl, workspaceId, idOrSlug) {
-  const list = await listCoderunners(apiUrl, workspaceId);
-  const match = list.find((c) => c.id === idOrSlug || c.slug === idOrSlug);
-  if (!match) {
-    throw new Error(`Coderunner not found: ${idOrSlug}`);
-  }
-  return match.id;
-}
 async function statusCommand(opts) {
   const cfg = await resolveConfig({ workspaceId: opts.workspace });
   if (!cfg.workspaceId) {
@@ -1451,7 +1699,7 @@ async function statusCommand(opts) {
       "No workspace selected. Run `gf workspaces use <id>` or pass --workspace <id>."
     );
   }
-  const coderunnerId = await resolveCoderunnerId2(
+  const coderunnerId = await resolveCoderunnerId(
     cfg.apiUrl,
     cfg.workspaceId,
     opts.coderunner
@@ -1634,10 +1882,10 @@ async function secretsRmCommand(key, opts) {
 }
 
 // src/commands/files.ts
-import { promises as fs4 } from "fs";
-import path4 from "path";
+import { promises as fs5 } from "fs";
+import path5 from "path";
 function guessContentType(filename) {
-  const ext = path4.extname(filename).toLowerCase();
+  const ext = path5.extname(filename).toLowerCase();
   const types = {
     ".json": "application/json",
     ".txt": "text/plain",
@@ -1672,9 +1920,9 @@ async function filesListCommand(opts) {
 }
 async function filesUploadCommand(filePath, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const resolved = path4.resolve(filePath);
-  const buf = await fs4.readFile(resolved);
-  const name = opts.name ?? path4.basename(resolved);
+  const resolved = path5.resolve(filePath);
+  const buf = await fs5.readFile(resolved);
+  const name = opts.name ?? path5.basename(resolved);
   const contentType = guessContentType(name);
   const init = await initFileUpload(cfg.apiUrl, cfg.workspaceId, {
     name,
@@ -1711,8 +1959,8 @@ async function filesDownloadCommand(fileId, opts) {
     throw new Error(`Download failed: ${res.status} ${res.statusText}`);
   }
   const buf = Buffer.from(await res.arrayBuffer());
-  const dest = path4.resolve(opts.out ?? fileId);
-  await fs4.writeFile(dest, buf);
+  const dest = path5.resolve(opts.out ?? fileId);
+  await fs5.writeFile(dest, buf);
   process.stdout.write(`Wrote ${dest}
 `);
 }
@@ -1724,8 +1972,8 @@ async function filesRmCommand(fileId, opts) {
 }
 
 // src/commands/apps.ts
-import { promises as fs5 } from "fs";
-import path5 from "path";
+import { promises as fs6 } from "fs";
+import path6 from "path";
 
 // src/release-zip.ts
 import AdmZip2 from "adm-zip";
@@ -1758,21 +2006,21 @@ function chooseRemoteEntry(relpaths) {
   })[0];
 }
 function flattenFederatedBundlePlan(relpaths) {
-  const paths = relpaths.map(normalizeZipEntryName).filter((name) => name && !name.endsWith("/") && !name.split("/").includes(".."));
-  const pathset = new Set(paths);
+  const paths2 = relpaths.map(normalizeZipEntryName).filter((name) => name && !name.endsWith("/") && !name.split("/").includes(".."));
+  const pathset = new Set(paths2);
   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);
+  for (const path10 of pathset) {
+    const parent = parentDir(path10);
     if (parent === "assets" || parent.endsWith("/assets") && parent.split("/").length - 1 < 2) {
       promoteDirs.add(parent);
     }
   }
   const destToSrc = {};
-  for (const src of paths) {
+  for (const src of paths2) {
     const parent = parentDir(src);
     if (!promoteDirs.has(parent)) continue;
     const dest = basename(src);
@@ -1897,7 +2145,7 @@ function formatApp(app) {
   return `${app.id}  ${app.name ?? app.slug ?? ""}  ${app.app_kind ?? ""}  [${app.status ?? ""}]`;
 }
 async function readJsonObject(filePath) {
-  const raw = await fs5.readFile(filePath, "utf8");
+  const raw = await fs6.readFile(filePath, "utf8");
   const parsed = JSON.parse(raw);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`${filePath} must contain a JSON object`);
@@ -1906,13 +2154,13 @@ async function readJsonObject(filePath) {
 }
 async function maybeReadManifest(filePath) {
   if (!filePath) return void 0;
-  return readJsonObject(path5.resolve(filePath));
+  return readJsonObject(path6.resolve(filePath));
 }
 async function findSiblingManifest(bundlePath) {
-  const dir = await isDirectory(bundlePath) ? bundlePath : path5.dirname(bundlePath);
-  const candidate = path5.join(dir, "groundfloor.manifest.json");
+  const dir = await isDirectory(bundlePath) ? bundlePath : path6.dirname(bundlePath);
+  const candidate = path6.join(dir, "groundfloor.manifest.json");
   try {
-    await fs5.access(candidate);
+    await fs6.access(candidate);
   } catch {
     return void 0;
   }
@@ -1948,7 +2196,7 @@ Prefer: ${federatedReleaseZipHint(slug)}
 }
 async function isDirectory(filePath) {
   try {
-    return (await fs5.stat(filePath)).isDirectory();
+    return (await fs6.stat(filePath)).isDirectory();
   } catch {
     return false;
   }
@@ -2068,11 +2316,11 @@ Do not scaffold src/App.tsx from scratch \u2014 BrowserRouter in App.tsx crashes
 }
 async function appsPublishCommand(appRef, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const inputPath = path5.resolve(opts.path ?? "release.zip");
-  const bundlePath = await isDirectory(inputPath) ? path5.join(inputPath, "release.zip") : inputPath;
+  const inputPath = path6.resolve(opts.path ?? "release.zip");
+  const bundlePath = await isDirectory(inputPath) ? path6.join(inputPath, "release.zip") : inputPath;
   let bytes;
   try {
-    bytes = await fs5.readFile(bundlePath);
+    bytes = await fs6.readFile(bundlePath);
   } catch {
     throw new Error(
       `No bundle at ${bundlePath}. ${initThenPublishHint()}`
@@ -2099,11 +2347,11 @@ async function appsPublishCommand(appRef, opts) {
       `Releases are only for shell_federated apps (this app is ${app.app_kind}). Use \`gf deploy\` for coderunner workloads.`
     );
   }
-  const ext = path5.extname(bundlePath).toLowerCase();
+  const ext = path6.extname(bundlePath).toLowerCase();
   const isZip = ext === ".zip";
   if (!isZip) {
     throw new Error(
-      `Publish release.zip from \`npm run release\`, not a lone ${path5.basename(bundlePath)}. ` + initThenPublishHint(app.slug)
+      `Publish release.zip from \`npm run release\`, not a lone ${path6.basename(bundlePath)}. ` + initThenPublishHint(app.slug)
     );
   }
   bytes = prepareReleaseZip(bytes, app.slug);
@@ -2143,10 +2391,16 @@ async function appsPublishCommand(appRef, opts) {
 }
 
 // src/commands/apps-init.ts
-import { promises as fs6 } from "fs";
+import { promises as fs7 } from "fs";
 import os3 from "os";
-import path6 from "path";
+import path7 from "path";
 import AdmZip4 from "adm-zip";
+
+// src/version.ts
+var GF_VERSION = "0.1.6";
+var GF_NPM_PACKAGE = "@groundfloorcloud/cli";
+
+// src/commands/apps-init.ts
 var MAX_KIT_BYTES = 8 * 1024 * 1024;
 function slugify3(input) {
   const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -2157,7 +2411,7 @@ function titleFromSlug(slug) {
 }
 async function pathExists(filePath) {
   try {
-    await fs6.access(filePath);
+    await fs7.access(filePath);
     return true;
   } catch {
     return false;
@@ -2165,7 +2419,7 @@ async function pathExists(filePath) {
 }
 async function isEmptyDir(dir) {
   try {
-    const entries = await fs6.readdir(dir);
+    const entries = await fs7.readdir(dir);
     return entries.length === 0;
   } catch (err) {
     if (err.code === "ENOENT") return true;
@@ -2174,17 +2428,17 @@ async function isEmptyDir(dir) {
 }
 async function findKitRoot(extracted) {
   const candidates = [
-    path6.join(extracted, "shell-starter-kit"),
+    path7.join(extracted, "shell-starter-kit"),
     extracted
   ];
-  const entries = await fs6.readdir(extracted, { withFileTypes: true });
+  const entries = await fs7.readdir(extracted, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isDirectory()) {
-      candidates.push(path6.join(extracted, entry.name));
+      candidates.push(path7.join(extracted, entry.name));
     }
   }
   for (const candidate of candidates) {
-    if (await pathExists(path6.join(candidate, "groundfloor.manifest.json"))) {
+    if (await pathExists(path7.join(candidate, "groundfloor.manifest.json"))) {
       return candidate;
     }
   }
@@ -2219,7 +2473,7 @@ async function downloadKit(url) {
     res = await fetch(url, {
       redirect: "follow",
       signal: AbortSignal.timeout(6e4),
-      headers: { "User-Agent": "groundfloor-cli/0.1.1" }
+      headers: { "User-Agent": `groundfloor-cli/${GF_VERSION}` }
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -2266,7 +2520,7 @@ async function appsInitCommand(opts) {
 `);
   }
   const name = opts.name?.trim() || titleFromSlug(slug);
-  const dest = path6.resolve(opts.dir?.trim() || path6.join(process.cwd(), slug));
+  const dest = path7.resolve(opts.dir?.trim() || path7.join(process.cwd(), slug));
   const cfg = await resolveConfig();
   const cell = cfg.environment ?? "production";
   const kitUrl = opts.kitUrl?.trim() || starterKitZipUrl(cell);
@@ -2276,26 +2530,26 @@ async function appsInitCommand(opts) {
     );
   }
   if (opts.force && await pathExists(dest)) {
-    await fs6.rm(dest, { recursive: true, force: true });
+    await fs7.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-"));
+  const tmp = await fs7.mkdtemp(path7.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 });
+    await fs7.mkdir(dest, { recursive: true });
+    await fs7.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");
+    await fs7.rm(tmp, { recursive: true, force: true });
+  }
+  const identityPath = path7.join(dest, "src", "appIdentity.ts");
+  const manifestPath = path7.join(dest, "groundfloor.manifest.json");
+  const identity = await fs7.readFile(identityPath, "utf8");
+  await fs7.writeFile(identityPath, stampAppIdentity(identity, slug), "utf8");
+  const manifest = await fs7.readFile(manifestPath, "utf8");
+  await fs7.writeFile(manifestPath, stampManifest(manifest, slug, name), "utf8");
   const result = {
     dir: dest,
     slug,
@@ -2321,6 +2575,9 @@ async function appsInitCommand(opts) {
   process.stdout.write(
     "Do not wrap src/App.tsx in BrowserRouter (DevShell already has one).\n"
   );
+  process.stdout.write(
+    "MCP: .mcp.json is included (npx @groundfloorcloud/mcp). Cursor on macOS: copy .cursor/mcp.json.example.\n"
+  );
   process.stdout.write("Next:\n");
   for (const step of result.next) {
     process.stdout.write(`  ${step}
@@ -2363,6 +2620,81 @@ async function dataplaneProvisionCommand(opts) {
   }
 }
 
+// src/update-check.ts
+import { promises as fs8 } from "fs";
+import path8 from "path";
+var UPDATE_TTL_MS = 24 * 60 * 60 * 1e3;
+function isNewer(latest, current) {
+  const a = latest.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const b = current.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i += 1) {
+    const lv = a[i] ?? 0;
+    const cv = b[i] ?? 0;
+    if (lv > cv) return true;
+    if (lv < cv) return false;
+  }
+  return false;
+}
+function upgradeNotice(current, latest) {
+  return `gf ${latest} is available (you have ${current}). npm i -g ${GF_NPM_PACKAGE}@latest`;
+}
+function unknownCommandNotice(command, current, latest) {
+  if (latest && isNewer(latest, current)) {
+    return `unknown command '${command}' \u2014 your gf is ${current}, latest is ${latest}. npm i -g ${GF_NPM_PACKAGE}@latest`;
+  }
+  return `unknown command '${command}' \u2014 your gf is ${current}`;
+}
+function parseUnknownCommandName(message) {
+  const match = message.match(/unknown command ['"]([^'"]+)['"]/i);
+  return match?.[1] ?? "that";
+}
+async function fetchNpmLatest(pkg = GF_NPM_PACKAGE) {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(1500)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" && body.version.trim() ? body.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+async function readUpdateCache(file) {
+  try {
+    const raw = await fs8.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.checkedAt !== "number" || typeof parsed.latest !== "string" || !parsed.latest.trim()) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function writeUpdateCache(file, cache) {
+  await fs8.mkdir(path8.dirname(file), { recursive: true, mode: 448 });
+  await fs8.writeFile(file, `${JSON.stringify(cache)}
+`, { mode: 384 });
+}
+async function resolveLatest(opts) {
+  const now = opts.now ?? Date.now();
+  const ttl = opts.ttlMs ?? UPDATE_TTL_MS;
+  const cached = await readUpdateCache(opts.cacheFile);
+  if (cached && now - cached.checkedAt < ttl) {
+    return cached.latest;
+  }
+  const fetchLatest = opts.fetchLatest ?? fetchNpmLatest;
+  const latest = await fetchLatest();
+  if (latest) {
+    await writeUpdateCache(opts.cacheFile, { checkedAt: now, latest });
+    return latest;
+  }
+  return cached?.latest ?? null;
+}
+
 // src/index.ts
 function collect(value, previous) {
   return previous.concat([value]);
@@ -2378,7 +2710,7 @@ function run(fn) {
 var program = new Command();
 program.name("gf").description(
   "Groundfloor CLI \u2014 sign in, deploy coderunners, publish Shell apps, and manage workspace resources."
-).version("0.1.4");
+).version(GF_VERSION);
 program.command("login").description(
   "Log in via the browser (production by default; --dev / --stage for other cells)"
 ).option("--dev", "Sign in to Groundfloor dev").option("--stage", "Sign in to Groundfloor stage").option(
@@ -2403,6 +2735,18 @@ workspaces.command("use <workspaceId>").description("Set the default workspace")
 var coderunner = program.command("coderunner").alias("cr").description("Coderunner commands");
 coderunner.command("ls").alias("list").description("List coderunners in the default (or --workspace) workspace").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => coderunnerListCommand(opts)));
 coderunner.command("status").description("Show coderunner status + current deployment JSON").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => statusCommand(opts)));
+coderunner.command("logs").description("Show Process Log lines for a coderunner (stdout/stderr)").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--limit <n>", "Max lines (default 50)").option("--since-seconds <n>", "Lookback window in seconds (default 3600)").option("--search <text>", "Substring filter").option("--json", "Output raw JSON").action(
+  (opts) => run(
+    () => logsCommand({
+      workspace: opts.workspace,
+      coderunner: opts.coderunner,
+      limit: opts.limit,
+      sinceSeconds: opts.sinceSeconds,
+      search: opts.search,
+      json: opts.json
+    })
+  )
+);
 coderunner.command("run").description("Invoke a deployed function/job (smoke run)").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--payload <json>", "JSON payload object", "{}").option("--json", "Output raw JSON").action(
   (opts) => run(
     () => runCommand({
@@ -2501,7 +2845,40 @@ program.command("deploy").description(
   "--app-id <id>",
   "Bind newly created coderunner as a helper of this App (optional)"
 ).option("--cpu <cpu>", "CPU request, e.g. 250m").option("--memory <memory>", "Memory request, e.g. 256Mi").option("-e, --env <KEY=VALUE>", "Environment variable (repeatable)", collect, []).option("-m, --message <text>", "Version description").option("--skip-deploy", "Upload a new version but do not deploy it").action((opts) => run(() => deployCommand(opts)));
-program.parseAsync(process.argv).catch((err) => {
+function wireUnknownCommands(root, current, latest) {
+  const walk = (cmd) => {
+    if (cmd.commands.length === 0) return;
+    cmd.exitOverride((err) => {
+      if (err.code === "commander.unknownCommand") {
+        process.stderr.write(
+          `${unknownCommandNotice(parseUnknownCommandName(err.message), current, latest)}
+`
+        );
+        process.exit(1);
+      }
+      throw err;
+    });
+    for (const child of cmd.commands) walk(child);
+  };
+  walk(root);
+}
+async function notifyUpgrade() {
+  if (process.env.GF_SKIP_UPDATE_CHECK === "1") return null;
+  const latest = await resolveLatest({
+    cacheFile: path9.join(paths.CONFIG_DIR, "update-check.json")
+  });
+  if (latest && isNewer(latest, GF_VERSION)) {
+    process.stderr.write(`${upgradeNotice(GF_VERSION, latest)}
+`);
+  }
+  return latest;
+}
+async function main() {
+  const latest = await notifyUpgrade();
+  wireUnknownCommands(program, GF_VERSION, latest);
+  await program.parseAsync(process.argv);
+}
+main().catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
   process.stderr.write(`Error: ${message}
 `);

package/package.json

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