@groundfloorcloud/cli 0.1.5 → 0.1.7

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.
 
@@ -67,7 +72,7 @@ Authentication, mode `groundfloor` or `external`) until the realm is active.
 |-------------------|-------------|---------------|
 | `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. |
+| `schedule` | Scheduled job | Cron via `--schedule` or `groundfloor.json` `schedule`. No public URL. |
 | `service` | **Deployment** | Long-running HTTP. **Root `Dockerfile` is required.** |
 
 ```bash
@@ -76,6 +81,7 @@ gf deploy --git https://github.com/me/my-fn.git --ref main
 gf deploy --name my-fn --runtime python --cpu 250m --memory 256Mi \
   -e API_KEY=secret
 gf deploy --workload-type service
+gf deploy --workload-type schedule --schedule "*/5 * * * *"
 gf deploy --app-id <app-uuid>
 ```
 
@@ -113,7 +119,8 @@ Then `gf deploy` the same tree. Do not zip `.env` files.
   "workloadType": "function",
   "cpu": "250m",
   "memory": "256Mi",
-  "env": { "STAGE": "dev" }
+  "env": { "STAGE": "dev" },
+  "schedule": "*/5 * * * *"
 }
 ```
 
@@ -127,6 +134,7 @@ Then `gf deploy` the same tree. Do not zip `.env` files.
 | `--subdir <dir>` | Package a subdirectory of the source. |
 | `--runtime <r>` | `python` \| `node` \| `dotnet-script`. |
 | `--workload-type <t>` | `function` \| `service` (Deployment) \| `job` \| `schedule`. Service requires a Dockerfile. |
+| `--schedule <cron>` | Cron for `schedule` workloads (or `groundfloor.json` `schedule`). |
 | `--cpu` / `--memory` | Resource requests, e.g. `250m` / `256Mi`. |
 | `-e, --env KEY=VALUE` | Deployment env var (repeatable). |
 | `-m, --message <text>` | Version description. |
@@ -200,10 +208,12 @@ gf apps get <id|slug>
 | `gf whoami` | Show identity and verify the Control Plane session. |
 | `gf token` | Print a fresh access token. |
 | `gf env` | Print `export …` lines for `eval "$(gf env)"`. |
+| `gf environments ls` (`envs`) | List workspace environments. |
 | `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 cancel-deployment -c <id\|slug>` | Delete the current (or `--deployment-id`) deployment. |
 | `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, path8) {
+async function cpGet(apiUrl, path10) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path8}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     headers: {
       Authorization: `Bearer ${token}`,
       Accept: "application/json"
@@ -546,9 +548,9 @@ async function cpGet(apiUrl, path8) {
   }
   return await res.json();
 }
-async function cpPostJson(apiUrl, path8, body) {
+async function cpPostJson(apiUrl, path10, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path8}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -562,9 +564,9 @@ async function cpPostJson(apiUrl, path8, body) {
   }
   return await res.json();
 }
-async function cpDelete(apiUrl, path8) {
+async function cpDelete(apiUrl, path10) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path8}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "DELETE",
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
   });
@@ -572,9 +574,9 @@ async function cpDelete(apiUrl, path8) {
     throw new CpError(res.status, await parseError(res));
   }
 }
-async function cpPutJson(apiUrl, path8, body) {
+async function cpPutJson(apiUrl, path10, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path8}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "PUT",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -588,9 +590,9 @@ async function cpPutJson(apiUrl, path8, body) {
   }
   return await res.json();
 }
-async function cpPatchJson(apiUrl, path8, body) {
+async function cpPatchJson(apiUrl, path10, body) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path8}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "PATCH",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -604,9 +606,9 @@ async function cpPatchJson(apiUrl, path8, body) {
   }
   return await res.json();
 }
-async function cpPutBytes(apiUrl, path8, body, contentType) {
+async function cpPutBytes(apiUrl, path10, body, contentType) {
   const token = await getValidAccessToken();
-  const res = await fetch(`${apiUrl}${path8}`, {
+  const res = await fetch(`${apiUrl}${path10}`, {
     method: "PUT",
     headers: {
       Authorization: `Bearer ${token}`,
@@ -707,6 +709,22 @@ async function getDeployment(apiUrl, workspaceId, coderunnerId) {
   }
   return await res.json();
 }
+function deleteCoderunnerDeployment(apiUrl, workspaceId, coderunnerId, deploymentId) {
+  return cpDelete(
+    apiUrl,
+    `/v1/workspaces/${encodeURIComponent(
+      workspaceId
+    )}/coderunners/${encodeURIComponent(
+      coderunnerId
+    )}/deployments/${encodeURIComponent(deploymentId)}`
+  );
+}
+function listWorkspaceEnvironments(apiUrl, workspaceId) {
+  return cpGet(
+    apiUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/environments`
+  );
+}
 function getCoderunnerStatus(apiUrl, workspaceId, coderunnerId) {
   return cpGet(
     apiUrl,
@@ -1015,6 +1033,79 @@ async function coderunnerListCommand(opts) {
   }
 }
 
+// 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/cancel-deployment.ts
+async function cancelDeploymentCommand(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
+  );
+  let deploymentId = opts.deploymentId?.trim();
+  if (!deploymentId) {
+    const current = await getDeployment(cfg.apiUrl, cfg.workspaceId, coderunnerId);
+    deploymentId = current?.id?.trim();
+  }
+  if (!deploymentId) {
+    throw new Error(
+      `No current deployment for coderunner ${coderunnerId}. Pass --deployment-id.`
+    );
+  }
+  await deleteCoderunnerDeployment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    coderunnerId,
+    deploymentId
+  );
+  process.stdout.write(
+    `Deleted deployment ${deploymentId} for coderunner ${coderunnerId}
+`
+  );
+}
+
+// src/commands/environments.ts
+async function environmentsListCommand(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 environments2 = await listWorkspaceEnvironments(
+    cfg.apiUrl,
+    cfg.workspaceId
+  );
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(environments2, null, 2)}
+`);
+    return;
+  }
+  if (environments2.length === 0) {
+    process.stdout.write("No environments in this workspace.\n");
+    return;
+  }
+  for (const env of environments2) {
+    const status = env.status ?? "";
+    process.stdout.write(`${env.id}  ${env.name}  [${status}]
+`);
+  }
+}
+
 // src/process-log.ts
 var PROCESS_STATUS_LABELS = {
   1: "Pending",
@@ -1128,16 +1219,6 @@ async function diagnoseDeployFailure(opts) {
   });
 }
 
-// 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 });
@@ -1403,6 +1484,30 @@ async function preflightNodePackage(sourceDir) {
   }
 }
 
+// src/deploy/schedule.ts
+var SCHEDULE_REQUIRED = 'workload type "schedule" requires --schedule "<cron>" or groundfloor.json "schedule".';
+var SCHEDULE_WRONG_TYPE = '--schedule / groundfloor.json "schedule" is only valid with --workload-type schedule.';
+function resolveDeploySchedule(opts) {
+  const cron = (opts.flag ?? opts.manifestSchedule)?.trim() || void 0;
+  if (opts.workloadType === "schedule") {
+    if (!cron) {
+      throw new Error(SCHEDULE_REQUIRED);
+    }
+    return cron;
+  }
+  if (cron) {
+    throw new Error(SCHEDULE_WRONG_TYPE);
+  }
+  return void 0;
+}
+
+// src/deploy/target.ts
+function formatDeployTarget(input) {
+  const label = input.workspaceName?.trim() ? `${input.workspaceName.trim()} (${input.workspaceId})` : input.workspaceId;
+  const cell = input.cell ?? "unknown";
+  return `Deploy target: workspace=${label} cell=${cell} api=${input.apiUrl}`;
+}
+
 // src/commands/deploy.ts
 var RUNTIMES = /* @__PURE__ */ new Set(["python", "node", "dotnet-script"]);
 var WORKLOAD_TYPES = /* @__PURE__ */ new Set(["function", "service", "job", "schedule"]);
@@ -1446,6 +1551,20 @@ async function deployCommand(opts) {
     );
   }
   const ws = cfg.workspaceId;
+  let workspaceName;
+  try {
+    const workspaces2 = await listWorkspaces(cfg.apiUrl);
+    workspaceName = workspaces2.find((item) => item.id === ws)?.name;
+  } catch {
+  }
+  log(
+    formatDeployTarget({
+      workspaceId: ws,
+      workspaceName,
+      cell: cfg.environment,
+      apiUrl: cfg.apiUrl
+    })
+  );
   log(
     opts.git ? `Cloning ${opts.git}${opts.ref ? ` (${opts.ref})` : ""}...` : `Packaging ${path4.resolve(opts.path ?? process.cwd())}...`
   );
@@ -1484,6 +1603,11 @@ async function deployCommand(opts) {
     if (runtime === "node") {
       await preflightNodePackage(pkg.sourceDir);
     }
+    const schedule = resolveDeploySchedule({
+      workloadType,
+      flag: opts.schedule,
+      manifestSchedule: manifest.schedule
+    });
     let coderunnerId = opts.coderunner;
     if (!coderunnerId) {
       const name = opts.name ?? manifest.name ?? (opts.git ? nameFromGitUrl(opts.git) : path4.basename(path4.resolve(opts.path ?? process.cwd())));
@@ -1585,7 +1709,8 @@ async function deployCommand(opts) {
       version_id: uploaded.version_id,
       cpu: opts.cpu ?? manifest.cpu,
       memory: opts.memory ?? manifest.memory,
-      envVariable: Object.keys(envVariable).length ? envVariable : void 0
+      envVariable: Object.keys(envVariable).length ? envVariable : void 0,
+      schedule
     });
     log("Waiting for deployment...");
     const deployDeadline = Date.now() + DEPLOY_POLL_TIMEOUT_MS;
@@ -2004,21 +2129,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 path8 of pathset) {
-    const parent = parentDir(path8);
+  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);
@@ -2393,6 +2518,12 @@ import { promises as fs7 } from "fs";
 import os3 from "os";
 import path7 from "path";
 import AdmZip4 from "adm-zip";
+
+// src/version.ts
+var GF_VERSION = "0.1.7";
+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, "");
@@ -2465,7 +2596,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);
@@ -2567,6 +2698,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}
@@ -2609,6 +2743,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]);
@@ -2624,7 +2833,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.5");
+).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(
@@ -2641,6 +2850,8 @@ program.command("logout").description("Clear the cached session").action(() => r
 program.command("whoami").description("Show the current identity and verify the Control Plane session").action(() => run(() => whoamiCommand()));
 program.command("token").description("Print a valid (auto-refreshed) access token to stdout").action(() => run(() => tokenCommand()));
 program.command("env").description('Print shell exports for `eval "$(gf env)"`').action(() => run(() => envCommand()));
+var environments = program.command("environments").alias("envs").description("List workspace environments");
+environments.command("list", { isDefault: true }).alias("ls").description("List environments in the default (or --workspace) workspace").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => environmentsListCommand(opts)));
 var workspaces = program.command("workspaces").alias("ws").description("List workspaces or set the default workspace");
 workspaces.command("list", { isDefault: true }).description("List workspaces visible to your user").option("--json", "Output raw JSON").action((opts) => run(() => workspacesListCommand(opts)));
 workspaces.command("use <workspaceId>").description("Set the default workspace").action(
@@ -2649,6 +2860,15 @@ 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("cancel-deployment").description("Delete the current (or --deployment-id) deployment").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--deployment-id <id>", "Deployment id (default: current deployment)").action(
+  (opts) => run(
+    () => cancelDeploymentCommand({
+      workspace: opts.workspace,
+      coderunner: opts.coderunner,
+      deploymentId: opts.deploymentId
+    })
+  )
+);
 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({
@@ -2755,11 +2975,47 @@ program.command("deploy").description(
 ).option("-n, --name <name>", "Coderunner name (default: folder or repo name)").option("-p, --path <dir>", "Local directory to package (default: cwd)").option("--git <url>", "Clone and deploy a remote git/bitbucket repo").option("--ref <ref>", "Branch/tag/commit for --git").option("--subdir <dir>", "Subdirectory within the source to package").option("--runtime <runtime>", "python | node | dotnet-script").option(
   "--workload-type <type>",
   "function | service | job | schedule"
+).option(
+  "--schedule <cron>",
+  'Cron for --workload-type schedule (or groundfloor.json "schedule")'
 ).option(
   "--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.5",
+  "version": "0.1.7",
   "description": "Groundfloor gf CLI — sign in, deploy coderunners, publish Shell apps, and manage secrets, files, and Dataplane.",
   "type": "module",
   "bin": {