@terminus-ai/cli 0.0.1 → 0.0.2

package/README.md

@@ -767,7 +767,7 @@ Bare `terminus` (or `terminus help`) prints its version and the everyday command
 with what it does on one line (`<word>` is a placeholder, `[ ]` is optional):
 
 ```text
-Terminus v0.0.1, created by Terminus Intelligence
+Terminus v0.0.2, created by Terminus Intelligence
 
 Account:
   terminus login                         Open your browser and sign in

package/bin/app-sdk.mjs

@@ -0,0 +1,128 @@
+/**
+ * The app SDK as the CLI sees it: the package apps depend on, the range
+ * `terminus init` writes, and whether an app's installed copy has fallen
+ * behind the newest one on npm.
+ *
+ * During the beta every app should run the newest SDK, but npm keeps whatever
+ * an app's lockfile holds until someone updates it — a cloned app, or one set
+ * up from the docs, can sit on an old SDK indefinitely. So `terminus push`
+ * and `terminus dev` ask `appSdkUpdate` and say so, with the command that
+ * fixes it.
+ *
+ * The check never fails or holds up a command: it asks the npm registry at
+ * most once a day (the answer is kept in ~/.terminus/app-sdk-latest.json),
+ * gives up after 1.5 s, and answers null — say nothing — offline, in CI, for
+ * a folder that does not use the SDK, or when anything is unexpected.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { compareReleaseVersions, parseReleaseVersion } from "./versioning.mjs";
+
+export const APP_SDK_PACKAGE = "@terminus-ai/app-sdk";
+
+// "latest" during the beta: a new app starts on the newest SDK and
+// `npm update` keeps moving it there, breaking releases included. When the
+// beta ends, scaffolds go back to a normal range.
+export const APP_SDK_VERSION = "latest";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_TIMEOUT_MS = 1500;
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** What the app's package.json asks for, or null when it does not use the SDK. */
+async function declaredRange(dir) {
+  const manifest = await readJson(path.join(dir, "package.json"));
+  const range = manifest?.dependencies?.[APP_SDK_PACKAGE] ?? manifest?.devDependencies?.[APP_SDK_PACKAGE];
+  return typeof range === "string" ? range : null;
+}
+
+/** The installed SDK's version, found the way Node resolves packages — up
+ * the node_modules chain — without going through the package's `exports`,
+ * which older builds did not open to package.json. */
+async function installedVersion(dir) {
+  for (let current = path.resolve(dir); ; current = path.dirname(current)) {
+    const manifest = await readJson(path.join(current, "node_modules", APP_SDK_PACKAGE, "package.json"));
+    if (typeof manifest?.version === "string") return manifest.version;
+    if (path.dirname(current) === current) return null;
+  }
+}
+
+function registryBase() {
+  const base = process.env.TERMINUS_NPM_REGISTRY || process.env.npm_config_registry || "https://registry.npmjs.org";
+  return base.replace(/\/+$/, "");
+}
+
+/** The newest published SDK version: from today's cache, else the registry. */
+async function newestVersion() {
+  const cacheFile = path.join(os.homedir(), ".terminus", "app-sdk-latest.json");
+  const cached = await readJson(cacheFile);
+  const age = Date.now() - Date.parse(cached?.checked_at);
+  if (typeof cached?.version === "string" && age >= 0 && age < DAY_MS) return cached.version;
+  let version;
+  try {
+    const response = await fetch(`${registryBase()}/${APP_SDK_PACKAGE.replace("/", "%2f")}/latest`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    ({ version } = await response.json());
+  } catch {
+    return null;
+  }
+  if (typeof version !== "string") return null;
+  try {
+    await mkdir(path.dirname(cacheFile), { recursive: true });
+    await writeFile(cacheFile, `${JSON.stringify({ version, checked_at: new Date().toISOString() })}\n`);
+  } catch {
+    // Unwritable home: ask again next time.
+  }
+  return version;
+}
+
+function inCi() {
+  const ci = process.env.CI;
+  return Boolean(ci) && ci !== "false" && ci !== "0";
+}
+
+/**
+ * Whether the app in `dir` runs an older SDK than the newest on npm:
+ * `{ package, installed, newest, command }`, or null. Never throws.
+ *
+ * The command follows the app's range: under "latest" (what `terminus init`
+ * writes) `npm update` reaches the newest; any other range may not let it, so
+ * the answer is `npm install …@latest`, which works from anywhere.
+ */
+export async function appSdkUpdate(dir) {
+  try {
+    if (inCi()) return null;
+    const range = await declaredRange(dir);
+    if (range === null) return null;
+    const installed = parseReleaseVersion(await installedVersion(dir));
+    if (!installed) return null;
+    const newest = parseReleaseVersion(await newestVersion());
+    if (!newest || compareReleaseVersions(installed, newest) >= 0) return null;
+    return {
+      package: APP_SDK_PACKAGE,
+      installed: installed.canonical,
+      newest: newest.canonical,
+      command: range === "latest" ? `npm update ${APP_SDK_PACKAGE}` : `npm install ${APP_SDK_PACKAGE}@latest`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The line `terminus push` and `terminus dev` print for an update. */
+export function appSdkUpdateLine(update) {
+  return `${update.package} ${update.newest} is out; this app has ${update.installed}. Update it: ${update.command}`;
+}

package/bin/appdev.mjs

@@ -46,6 +46,7 @@ import { injectAppRouteScript } from "./app-route-script.mjs";
 import { CliError, parseFlags, usageError } from "./client.mjs";
 import { Api, connect } from "./http.mjs";
 import { packageKind, readAppPackage, resolveCreation } from "./apps.mjs";
+import { appSdkUpdate, appSdkUpdateLine } from "./app-sdk.mjs";
 import { resolveTemplate } from "./devtriggers.mjs";
 import { DEV_DIRECTORY, ensureDevDirectory, sha256 } from "./files.mjs";
 import { nextCronAfter } from "./schedules.mjs";
@@ -4355,9 +4356,12 @@ export async function devCommand(args) {
     const { serviceDevCommand } = await import("./servicedev.mjs");
     return serviceDevCommand(dir, flags, args);
   }
+  // A stale SDK is told after the banner, whenever the answer comes; the
+  // harness never waits for it.
+  const sdkUpdate = appSdkUpdate(dir);
   const pkg = await readDevPackage(dir);
   requireBuiltDevBundle(pkg);
-  if (flags.remote) return remoteDevCommand(dir, flags, pkg, args);
+  if (flags.remote) return remoteDevCommand(dir, flags, pkg, args, sdkUpdate);
   let iconRemote = null;
   let platform = null;
   try {
@@ -4410,12 +4414,13 @@ export async function devCommand(args) {
   if (harness.guestPort !== null) {
     console.log("The guest is someone who is not signed in; the app's sign-in (session.signIn()) picks a member there.");
   }
+  sdkUpdate.then((update) => update && console.log(appSdkUpdateLine(update)));
   await new Promise(() => {}); // runs until Ctrl-C
 }
 
 /** `dev --remote`: the local bundle over the production runtime. Opt-in —
  * the SQLite harness stays the default. */
-async function remoteDevCommand(dir, flags, pkg, commandArgs) {
+async function remoteDevCommand(dir, flags, pkg, commandArgs, sdkUpdate) {
   for (const flag of ["members", "profiles", "guest", "fresh"]) {
     if (flags[flag] !== undefined) throw usageError(`--${flag} applies to the local harness, not --remote`);
   }
@@ -4442,5 +4447,6 @@ async function remoteDevCommand(dir, flags, pkg, commandArgs) {
   console.log(`Runtime: ${api.base}/app-runtime/* as the app session of ${minted.webHost}`);
   if (minted.expiresAt) console.log(`App session expires: ${minted.expiresAt}`);
   console.log(`  http://localhost:${harness.port}/`);
+  sdkUpdate.then((update) => update && console.log(appSdkUpdateLine(update)));
   await new Promise(() => {}); // runs until Ctrl-C
 }

package/bin/apps.mjs

@@ -77,6 +77,7 @@ import {
 } from "./client.mjs";
 import { CliError, usageError } from "./errors.mjs";
 import { connect, send } from "./http.mjs";
+import { APP_SDK_PACKAGE, APP_SDK_VERSION, appSdkUpdate, appSdkUpdateLine } from "./app-sdk.mjs";
 import {
   exists,
   globToRegExp,
@@ -165,12 +166,8 @@ function isSecretBasename(name) {
   return !/^\.env\.(example|sample|template)$/.test(name);
 }
 
-// The npm package scaffolds depend on. `~` takes every later 0.0.x (`^` on a
-// 0.0.x version takes that one version only), so SDK fixes reach new apps and
-// `npm update` without a CLI release; a breaking SDK release is 0.1.0, and
-// moves this range to `^0.1.0`. 0.0.2 is the SDK's first public version.
-export const APP_SDK_PACKAGE = "@terminus-ai/app-sdk";
-export const APP_SDK_VERSION = "~0.0.2";
+// The npm package scaffolds depend on, and the range they write (see app-sdk.mjs).
+export { APP_SDK_PACKAGE, APP_SDK_VERSION };
 const AUTOMATION_ACTIONS = new Set([
   "collection.put",
   "collection.delete",
@@ -4261,6 +4258,8 @@ export async function secretsCommand(args) {
 export async function pushAppCommand(args) {
   const flags = parseFlags(args, "push");
   const dir = path.resolve(flags._[0] ?? ".");
+  // Asked now, answered by the end: a stale SDK is worth a line, never a wait.
+  const sdkUpdate = appSdkUpdate(dir);
   const record = await readSyncRecord(dir);
   if (record?.source === "release") throw new CliError(readOnlyPushMessage(record.address));
   // The commit door caps a message at 500 characters and refuses a longer
@@ -4301,6 +4300,8 @@ export async function pushAppCommand(args) {
     version_problem: spentVersionWarning(manifest.version, pushed.releaseLabel),
     publish_url: creationPageUrl(flags, pushed.appId),
   };
+  const sdk = await sdkUpdate;
+  if (sdk) result.sdk_update = sdk;
   emitJson(flags, result, () => {
     if (!result.changed) {
       console.log(`Everything up to date: ${result.address} already matches this folder.`);
@@ -4319,6 +4320,7 @@ export async function pushAppCommand(args) {
       console.log("This agent runs code: `terminus dev --remote` tries it on Terminus's own engine first.");
     }
     console.log(`Publish it on the web when it is ready: ${result.publish_url}`);
+    if (result.sdk_update) console.log(appSdkUpdateLine(result.sdk_update));
   });
 }
 

package/bin/terminus.js

@@ -199,7 +199,7 @@ async function versionCommand(args) {
   const { APP_RUNTIME_API_VERSION } = await import("./app-runtime-contract.mjs");
   emitJson(flags, {
     version,
-    app_sdk: { package: APP_SDK_PACKAGE, version: APP_SDK_VERSION, install: `npm install ${APP_SDK_PACKAGE}` },
+    app_sdk: { package: APP_SDK_PACKAGE, version: APP_SDK_VERSION, install: `npm install ${APP_SDK_PACKAGE}@latest` },
     runtime_api_version: APP_RUNTIME_API_VERSION,
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminus-ai/cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Terminus CLI (`terminus`): search and use skills, and develop, run, and publish apps, services, and agents on the Terminus platform.",
   "license": "MIT",
   "type": "module",