@stage5/lumine 0.1.4 → 0.1.5

package/README.md

@@ -49,6 +49,12 @@ Reference folders are marked `readOnly` in `.twinkle/lumine-project.json`.
 Running `lumine save` from a reference folder is blocked; fork the source Build
 first if you want an editable workspace.
 
+The CLI checks npm for the latest `@stage5/lumine` version on normal commands.
+If the installed copy is outdated, it prints an update warning and records the
+version state in `.twinkle/lumine-project.json` so local agents can tell when
+they should rerun with `npx @stage5/lumine@latest`. Use `--no-update-check` to
+skip that advisory network check.
+
 After pulling a project, run an agent from the pulled folder:
 
 ```bash

package/bin/lumine.js

@@ -8,12 +8,14 @@ import { stdin as input, stdout as output } from "process";
 
 const DEFAULT_API_URL = "https://api.twinkle.network";
 const DEFAULT_SITE_URL = "https://www.twin-kle.com";
+const DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org";
 const DEFAULT_AUTH_FILE = path.join(
   os.homedir(),
   ".twinkle",
   "lumine-cli-auth.json",
 );
 const DEFAULT_TIMEOUT_MS = 20000;
+const UPDATE_CHECK_TIMEOUT_MS = 1500;
 const DEFAULT_PROJECT_LIMIT = 50;
 const PROJECT_METADATA_DIR = ".twinkle";
 const PROJECT_METADATA_FILE = "lumine-project.json";
@@ -35,6 +37,7 @@ const BUNDLED_SDK_REFERENCE_URL = new URL(
   "../sdk/BUILD_SDK_INDEX.md",
   import.meta.url,
 );
+const PACKAGE_METADATA_URL = new URL("../package.json", import.meta.url);
 const SDK_REFERENCE_FALLBACK = `${LUMINE_SDK_REFERENCE_MARKER}
 # Twinkle Build SDK Reference
 
@@ -61,6 +64,7 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
 - Read .twinkle/lumine-project.json before changing files.
 - Treat build.canWrite, build.canPublish, and build.contributionRootBuildId as authoritative.
+- If lumineCli.updateAvailable is true, ask the user to rerun with npx @stage5/lumine@latest before saving.
 - Read ${SDK_REFERENCE_FILE} before adding, removing, or changing any Twinkle.* SDK calls.
 - If build.canWrite is false, do not save changes.
 - If build.canPublish is false or contributionRootBuildId is set, this checkout is a contribution branch. Save only to this branch and do not run lumine launch or lumine save --publish.
@@ -102,6 +106,7 @@ the workspace to save.
 ## Source Of Truth
 
 - Read .twinkle/lumine-project.json before using these files.
+- If lumineCli.updateAvailable is true, ask the user to rerun with npx @stage5/lumine@latest before borrowing patterns.
 - If metadata.readOnly is true or build.role is "reference", do not run lumine save from this directory.
 - To start from this Build, run lumine fork with the source build id and edit the forked workspace.
 - Do not edit another local checkout to bypass reference read-only semantics.
@@ -132,10 +137,14 @@ main().catch((error) => {
 
 async function main() {
   const options = parseArgs(process.argv.slice(2));
+  options.lumineCli = await loadLumineCliVersionInfo({ options });
   if (options.help) {
     printHelp();
     return;
   }
+  if (options.updateCheck) {
+    await maybeCheckForLumineCliUpdate({ options });
+  }
 
   if (options.command === "workspace") {
     await workspace(options);
@@ -1117,6 +1126,7 @@ async function writeProjectMetadata({
           : null,
         apiUrl: options.apiUrl,
         siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
         manifest,
         pulledAt,
         lastSavedAt,
@@ -1164,6 +1174,7 @@ async function writeReferenceMetadata({
         },
         apiUrl: options.apiUrl,
         siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
         manifest,
         pulledAt,
       },
@@ -1258,6 +1269,20 @@ async function saveSelectedBuild({ options, auth, build }) {
   });
 }
 
+function serializeLumineCliMetadata(options) {
+  const info = options.lumineCli || {};
+  return {
+    packageName: info.packageName || "@stage5/lumine",
+    version: info.version || null,
+    latestVersion: info.latestVersion || null,
+    updateAvailable: Boolean(info.updateAvailable),
+    updateCommand: info.updateCommand || "npx @stage5/lumine@latest",
+    checkedAt: info.checkedAt || null,
+    checkFailed: Boolean(info.checkFailed),
+    checkSkipped: Boolean(info.checkSkipped),
+  };
+}
+
 function printBuildList(builds) {
   if (!builds.length) {
     console.log("No owned or team Twinkle builds found.");
@@ -1503,6 +1528,117 @@ async function request({ method = "GET", url, authToken, body, timeoutMs }) {
   }
 }
 
+async function loadLumineCliVersionInfo({ options }) {
+  const packageMetadata = await loadLocalPackageMetadata();
+  const packageName = packageMetadata.name || "@stage5/lumine";
+  const version = packageMetadata.version || null;
+  return {
+    packageName,
+    version,
+    latestVersion: null,
+    updateAvailable: false,
+    updateCommand: `npx ${packageName}@latest`,
+    checkedAt: null,
+    checkFailed: false,
+    checkSkipped: !options.updateCheck,
+  };
+}
+
+async function loadLocalPackageMetadata() {
+  try {
+    const rawPackage = await fs.readFile(PACKAGE_METADATA_URL, "utf8");
+    const parsedPackage = JSON.parse(rawPackage);
+    return {
+      name: String(parsedPackage?.name || "").trim(),
+      version: String(parsedPackage?.version || "").trim(),
+    };
+  } catch {
+    return {
+      name: "@stage5/lumine",
+      version: null,
+    };
+  }
+}
+
+async function maybeCheckForLumineCliUpdate({ options }) {
+  const info = options.lumineCli || (await loadLumineCliVersionInfo({ options }));
+  const checkedAt = new Date().toISOString();
+  if (!info.packageName || !info.version) {
+    options.lumineCli = {
+      ...info,
+      checkedAt,
+      checkFailed: true,
+      checkSkipped: false,
+    };
+    return;
+  }
+
+  try {
+    const latestVersion = await loadLatestPackageVersion({
+      packageName: info.packageName,
+      registryUrl: options.npmRegistryUrl,
+    });
+    const updateAvailable = isNewerVersion(latestVersion, info.version);
+    options.lumineCli = {
+      ...info,
+      latestVersion,
+      updateAvailable,
+      checkedAt,
+      checkFailed: false,
+      checkSkipped: false,
+    };
+    if (updateAvailable) {
+      printLumineCliUpdateWarning(options.lumineCli);
+    }
+  } catch {
+    options.lumineCli = {
+      ...info,
+      checkedAt,
+      checkFailed: true,
+      checkSkipped: false,
+    };
+  }
+}
+
+async function loadLatestPackageVersion({ packageName, registryUrl }) {
+  const encodedPackageName = encodeURIComponent(packageName);
+  const result = await requestJson({
+    url: `${registryUrl}/${encodedPackageName}/latest`,
+    timeoutMs: UPDATE_CHECK_TIMEOUT_MS,
+  });
+  const latestVersion = String(result?.version || "").trim();
+  if (!latestVersion) {
+    throw new Error("No latest package version returned");
+  }
+  return latestVersion;
+}
+
+function isNewerVersion(latestVersion, currentVersion) {
+  const latestParts = parseSemverParts(latestVersion);
+  const currentParts = parseSemverParts(currentVersion);
+  if (!latestParts || !currentParts) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (latestParts[index] > currentParts[index]) return true;
+    if (latestParts[index] < currentParts[index]) return false;
+  }
+  return false;
+}
+
+function parseSemverParts(value) {
+  const match = String(value || "")
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function printLumineCliUpdateWarning(info) {
+  console.error(
+    `lumine: update available for ${info.packageName}: ${info.version} -> ${info.latestVersion}.`,
+  );
+  console.error(`lumine: run \`${info.updateCommand}\` to use the latest CLI.`);
+}
+
 function parseArgs(args) {
   const firstArg = args[0] || "";
   const firstArgIsCommand =
@@ -1517,7 +1653,13 @@ function parseArgs(args) {
   const rest = command === "workspace" ? args : args.slice(1);
   const raw = {};
   const positional = [];
-  const booleanFlags = new Set(["noOpen", "open", "publish", "save"]);
+  const booleanFlags = new Set([
+    "noOpen",
+    "open",
+    "publish",
+    "save",
+    "noUpdateCheck",
+  ]);
 
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
@@ -1557,6 +1699,13 @@ function parseArgs(args) {
     siteUrl: trimTrailingSlash(
       String(raw.siteUrl || process.env.TWINKLE_SITE_URL || DEFAULT_SITE_URL),
     ),
+    npmRegistryUrl: trimTrailingSlash(
+      String(
+        raw.npmRegistryUrl ||
+          process.env.LUMINE_NPM_REGISTRY_URL ||
+          DEFAULT_NPM_REGISTRY_URL,
+      ),
+    ),
     authFile: String(
       raw.authFile || process.env.TWINKLE_CLI_AUTH_FILE || DEFAULT_AUTH_FILE,
     ),
@@ -1579,6 +1728,7 @@ function parseArgs(args) {
     openBrowser: parseBoolean(raw.noOpen, false)
       ? false
       : parseBoolean(raw.open, true),
+    updateCheck: parseBoolean(raw.noUpdateCheck, false) ? false : true,
     timeoutMs: Math.max(
       Number(raw.timeoutMs || process.env.TWINKLE_TIMEOUT_MS) ||
         DEFAULT_TIMEOUT_MS,
@@ -1802,6 +1952,7 @@ Options:
   --publish             Publish after saving
   --save                Save local files before launch
   --limit <number>      Number of projects to show
+  --no-update-check     Skip the npm latest-version check
   --no-open             Print the approval URL without opening a browser
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {