@getmagical/cli 0.1.7 → 0.1.9

package/README.md

@@ -10,6 +10,7 @@ Magical CLI for the shared MCP operation surface.
 ## Usage
 
 ```bash
+mgcl --version
 mgcl update
 mgcl auth login
 mgcl settings env base-url http://main.localhost:1355
@@ -68,6 +69,10 @@ Once installed, users can update from the same channel with:
 mgcl --update
 ```
 
+Installed CLIs also check the configured npm dist-tag before running
+subcommands. If the local version is behind, `mgcl` blocks the command and
+asks the user to run `mgcl update` before rerunning it.
+
 To remove the managed install:
 
 ```bash

package/dist/index.js

@@ -2063,10 +2063,10 @@ function createMagicalApiClient({
   const resolveApiBaseUrl = typeof apiBaseUrl === "string" ? () => apiBaseUrl : apiBaseUrl;
   async function fetchJson({
     accessToken,
-    path: path5,
+    path: path6,
     init
   }) {
-    const url = `${trimTrailingSlash(await resolveApiBaseUrl())}${path5}`;
+    const url = `${trimTrailingSlash(await resolveApiBaseUrl())}${path6}`;
     const headers = new Headers(init?.headers);
     headers.set("authorization", `Bearer ${accessToken}`);
     const response = await fetchFn(url, {
@@ -2546,6 +2546,9 @@ function isAppErrorCategory(category) {
   return typeof category === "string" && // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   ORDERED_APP_ERROR_CATEGORIES.includes(category);
 }
+function isNonEmptyAppErrorCategoryArray(categories) {
+  return Array.isArray(categories) && categories.length > 0 && categories.every(isAppErrorCategory);
+}
 var APP_ERROR_SEVERITIES = ["warn", "error", "fatal"];
 function isAppErrorCode(code) {
   return typeof code === "number" && Number.isInteger(code) && code >= 400 && code <= 599;
@@ -2583,42 +2586,55 @@ var AppError = class _AppError extends Error {
     }
     return type;
   }
-  static extractCategoriesFromCause(cause) {
-    if (!cause || typeof cause !== "object" || !("categories" in cause)) {
-      return ["internal_platform"];
+  static getInheritedCauseField(cause, extractor, seen = /* @__PURE__ */ new Set()) {
+    if (!cause || typeof cause !== "object" || seen.has(cause)) {
+      return void 0;
     }
-    if (Array.isArray(cause.categories) && cause.categories.length > 0 && cause.categories.every(isAppErrorCategory)) {
-      return cause.categories;
+    const causeRecord = cause;
+    const extractedValue = extractor(causeRecord);
+    if (extractedValue !== void 0) {
+      return extractedValue;
     }
-    return ["internal_platform"];
+    return _AppError.getInheritedCauseField(causeRecord["cause"], extractor, new Set(seen).add(cause));
+  }
+  static extractCategoriesFromCause(cause) {
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { categories } = causeRecord;
+      if (isNonEmptyAppErrorCategoryArray(categories)) {
+        return categories;
+      }
+      return void 0;
+    }) ?? ["internal_platform"];
   }
   static extractSeverityFromCause(cause) {
-    if (cause && typeof cause === "object" && "severity" in cause && isAppErrorSeverity(cause.severity)) {
-      return cause.severity;
-    }
-    return "error";
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { severity } = causeRecord;
+      return isAppErrorSeverity(severity) ? severity : void 0;
+    }) ?? "error";
   }
   static extractStatusCodeFromCause(cause) {
-    if (cause && typeof cause === "object" && "statusCode" in cause && isAppErrorCode(cause.statusCode)) {
-      return cause.statusCode;
-    }
-    if (cause && typeof cause === "object" && "code" in cause && isAppErrorCode(cause.code)) {
-      return cause.code;
-    }
-    return void 0;
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { statusCode } = causeRecord;
+      if (isAppErrorCode(statusCode)) {
+        return statusCode;
+      }
+      const { code: legacyCode } = causeRecord;
+      return isAppErrorCode(legacyCode) ? legacyCode : void 0;
+    });
   }
   /** @deprecated Use statusCode instead. */
   get code() {
     return this.statusCode;
   }
   static extractSuggestedActionFromCause(cause) {
-    if (cause && typeof cause === "object" && "suggestedAction" in cause && typeof cause.suggestedAction === "string") {
-      const trimmedSuggestedAction = cause.suggestedAction.trim();
-      if (trimmedSuggestedAction.length > 0) {
-        return trimmedSuggestedAction;
+    return _AppError.getInheritedCauseField(cause, (causeRecord) => {
+      const { suggestedAction } = causeRecord;
+      if (typeof suggestedAction !== "string") {
+        return void 0;
       }
-    }
-    return void 0;
+      const trimmedSuggestedAction = suggestedAction.trim();
+      return trimmedSuggestedAction.length > 0 ? trimmedSuggestedAction : void 0;
+    });
   }
   static applyStack(error, stack, internalFrames) {
     if (stack) {
@@ -3022,10 +3038,28 @@ import { spawn as spawn2 } from "child_process";
 import fs from "fs";
 import path3 from "path";
 import { fileURLToPath } from "url";
+
+// ../common/dist/src/stdlib/url.utils.js
+function safeUrlConstructor(url) {
+  try {
+    return Ok(new URL(url));
+  } catch {
+    return Err({
+      type: "invalid-url",
+      message: `Invalid URL`,
+      url
+    });
+  }
+}
+
+// src/self-update.ts
 var CLI_PACKAGE_NAME = "@getmagical/cli";
 var DEFAULT_CLI_DIST_TAG2 = "latest";
 var DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org/";
 var MANAGED_NODE_SUBPATH = "runtime/node";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function resolveInstalledPackageRoot({
   entryFilePath,
   packageName
@@ -3066,6 +3100,154 @@ function resolveInstallPrefixFromPackageRoot(packageRootPath) {
     currentPath = parentPath;
   }
 }
+function readInstalledPackageVersion({
+  packageName,
+  packageRootPath
+}) {
+  const packageManifestPath2 = path3.join(packageRootPath, "package.json");
+  if (!fs.existsSync(packageManifestPath2)) {
+    throw new CliError(
+      `Installed package metadata was not found at ${packageManifestPath2}. Reinstall mgcl and try again.`
+    );
+  }
+  const packageManifestResult2 = safeJsonParse(
+    fs.readFileSync(packageManifestPath2, "utf8")
+  );
+  if (isErr(packageManifestResult2)) {
+    throw new CliError(`Failed to parse ${packageManifestPath2}.`, {
+      cause: packageManifestResult2.error.cause
+    });
+  }
+  const packageManifest = packageManifestResult2.value;
+  if (packageManifest.name !== packageName) {
+    throw new CliError(
+      `Expected installed package ${packageName} at ${packageManifestPath2}. Reinstall mgcl and try again.`
+    );
+  }
+  if (typeof packageManifest.version !== "string" || !packageManifest.version) {
+    throw new CliError(
+      `Installed package version is missing from ${packageManifestPath2}. Reinstall mgcl and try again.`
+    );
+  }
+  return packageManifest.version;
+}
+function parseVersionSegment(segment, version) {
+  if (!/^\d+$/u.test(segment)) {
+    throw new CliError(`Invalid CLI version "${version}".`);
+  }
+  return Number(segment);
+}
+function parseSemanticVersion(version) {
+  const normalizedVersion = version.trim().replace(/^v/u, "");
+  const [versionWithoutBuildMetadata = ""] = normalizedVersion.split("+");
+  if (!versionWithoutBuildMetadata) {
+    throw new CliError(`Invalid CLI version "${version}".`);
+  }
+  const [releasePart, prereleasePart] = versionWithoutBuildMetadata.split("-");
+  if (!releasePart) {
+    throw new CliError(`Invalid CLI version "${version}".`);
+  }
+  return {
+    prerelease: prereleasePart ? prereleasePart.split(".") : null,
+    release: releasePart.split(".").map((segment) => parseVersionSegment(segment, version))
+  };
+}
+function comparePrereleaseIdentifiers(left, right) {
+  const leftIsNumeric = /^\d+$/u.test(left);
+  const rightIsNumeric = /^\d+$/u.test(right);
+  if (leftIsNumeric && rightIsNumeric) {
+    return Number(left) - Number(right);
+  }
+  if (leftIsNumeric) {
+    return -1;
+  }
+  if (rightIsNumeric) {
+    return 1;
+  }
+  return left.localeCompare(right);
+}
+function compareSemanticVersions(leftVersion, rightVersion) {
+  const left = parseSemanticVersion(leftVersion);
+  const right = parseSemanticVersion(rightVersion);
+  const releaseLength = Math.max(left.release.length, right.release.length);
+  for (let index = 0; index < releaseLength; index += 1) {
+    const difference = (left.release[index] ?? 0) - (right.release[index] ?? 0);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  if (!left.prerelease && !right.prerelease) {
+    return 0;
+  }
+  if (!left.prerelease) {
+    return 1;
+  }
+  if (!right.prerelease) {
+    return -1;
+  }
+  const prereleaseLength = Math.max(
+    left.prerelease.length,
+    right.prerelease.length
+  );
+  for (let index = 0; index < prereleaseLength; index += 1) {
+    const leftIdentifier = left.prerelease[index];
+    const rightIdentifier = right.prerelease[index];
+    if (leftIdentifier === void 0) {
+      return -1;
+    }
+    if (rightIdentifier === void 0) {
+      return 1;
+    }
+    const difference = comparePrereleaseIdentifiers(
+      leftIdentifier,
+      rightIdentifier
+    );
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return 0;
+}
+async function fetchPublishedPackageVersion({
+  distTag,
+  fetchFn = fetch,
+  packageName,
+  registryUrl
+}) {
+  const distTagUrlResult = safeUrlConstructor(
+    `${registryUrl.replace(/\/?$/u, "/")}-/package/${encodeURIComponent(packageName)}/dist-tags`
+  );
+  if (isErr(distTagUrlResult)) {
+    throw new CliError(`Invalid npm registry URL "${registryUrl}".`);
+  }
+  const response = await fetchFn(distTagUrlResult.value, {
+    headers: {
+      accept: "application/json"
+    }
+  });
+  if (!response.ok) {
+    throw new CliError(
+      `Could not check the latest published mgcl version (status ${response.status}).`
+    );
+  }
+  const distTagsResult = safeJsonParse(await response.text());
+  if (isErr(distTagsResult)) {
+    throw new CliError("Could not parse the npm dist-tags response for mgcl.", {
+      cause: distTagsResult.error.cause
+    });
+  }
+  if (!isRecord2(distTagsResult.value)) {
+    throw new CliError("Could not parse the npm dist-tags response for mgcl.");
+  }
+  const distTags = distTagsResult.value;
+  const publishedVersion = distTags[distTag];
+  if (typeof publishedVersion !== "string" || publishedVersion.length === 0) {
+    throw new CliError(
+      `Could not find npm dist-tag "${distTag}" for ${packageName}.`
+    );
+  }
+  return publishedVersion;
+}
 function resolveNpmCommandFromPath() {
   return {
     argsPrefix: [],
@@ -3179,18 +3361,44 @@ async function selfUpdateInstalledCli({
     registryUrl
   });
 }
-
-// ../common/dist/src/stdlib/url.utils.js
-function safeUrlConstructor(url) {
-  try {
-    return Ok(new URL(url));
-  } catch {
-    return Err({
-      type: "invalid-url",
-      message: `Invalid URL`,
-      url
-    });
+async function getInstalledCliUpdateRequirement({
+  distTag = DEFAULT_CLI_DIST_TAG2,
+  entryFilePath = fileURLToPath(import.meta.url),
+  fetchFn = fetch,
+  packageName = CLI_PACKAGE_NAME,
+  registryUrl = DEFAULT_NPM_REGISTRY_URL
+} = {}) {
+  const packageRootPath = resolveInstalledPackageRoot({
+    entryFilePath,
+    packageName
+  });
+  if (!packageRootPath) {
+    return null;
+  }
+  const installedVersion = readInstalledPackageVersion({
+    packageName,
+    packageRootPath
+  });
+  const publishedVersionResult = await fromThrowable(
+    async () => fetchPublishedPackageVersion({
+      distTag,
+      fetchFn,
+      packageName,
+      registryUrl
+    }),
+    "cli-update-check-failed"
+  );
+  if (isErr(publishedVersionResult)) {
+    return null;
   }
+  const publishedVersion = publishedVersionResult.value;
+  if (compareSemanticVersions(installedVersion, publishedVersion) >= 0) {
+    return null;
+  }
+  return {
+    installedVersion,
+    latestVersion: publishedVersion
+  };
 }
 
 // src/settings-command.ts
@@ -3343,6 +3551,28 @@ function createFileStateStore(stateFilePath) {
   };
 }
 
+// src/version.ts
+import fs2 from "fs";
+import path5 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var packageManifestPath = path5.resolve(
+  path5.dirname(fileURLToPath2(import.meta.url)),
+  "../package.json"
+);
+var packageManifestResult = safeJsonParse(
+  fs2.readFileSync(packageManifestPath, "utf8")
+);
+if (isErr(packageManifestResult)) {
+  throw new Error(`Failed to parse ${packageManifestPath}.`, {
+    cause: packageManifestResult.error.cause
+  });
+}
+var cliPackageVersion = packageManifestResult.value.version;
+if (typeof cliPackageVersion !== "string" || cliPackageVersion.length === 0) {
+  throw new Error(`Expected a version in ${packageManifestPath}.`);
+}
+var CLI_VERSION = cliPackageVersion;
+
 // src/workos-auth.ts
 import { z as z6 } from "zod";
 var DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;
@@ -3555,7 +3785,7 @@ function parseCommandOptionValue(rawValue, optionSpec) {
     }
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveOrganizationBySelector({
@@ -3615,7 +3845,7 @@ function collectOperationVariables(operationSpec, options) {
       parsedVariables.error.issues[0]?.message ?? "Invalid command input."
     );
   }
-  if (!isRecord2(parsedVariables.data)) {
+  if (!isRecord3(parsedVariables.data)) {
     throw new CliError("Invalid command input.");
   }
   return parsedVariables.data;
@@ -3718,6 +3948,25 @@ async function handleSelfUpdate(dependencies, options) {
     `Updated mgcl via npm (${updateResult.packageSpecifier}) in ${updateResult.installPrefix}.`
   );
 }
+function isRootUpdateCommand(program2, actionCommand) {
+  return actionCommand.parent === program2 && actionCommand.name() === "update";
+}
+async function enforceLatestCliVersionIfNeeded({
+  dependencies,
+  program: program2,
+  actionCommand
+}) {
+  if (actionCommand === program2 || isRootUpdateCommand(program2, actionCommand)) {
+    return;
+  }
+  const updateRequirement = await dependencies.ensureLatestCliVersion?.();
+  if (!updateRequirement) {
+    return;
+  }
+  throw new CliError(
+    `mgcl ${updateRequirement.installedVersion} is outdated. Upgrade to ${updateRequirement.latestVersion} with "mgcl update", then rerun your command.`
+  );
+}
 async function handleOperationCommand(dependencies, operationSpec, commandOptions) {
   const state = requireLoggedInState(await dependencies.stateStore.load());
   const organization = resolveSelectedOrganization({
@@ -3862,6 +4111,7 @@ function createDefaultDependencies() {
     refreshTokenStore: createKeytarRefreshTokenStore(
       runtimeConfig.keychainServiceName
     ),
+    ensureLatestCliVersion: async () => getInstalledCliUpdateRequirement(selfUpdateOptions),
     runtimeConfig,
     settingsStore,
     selfUpdateCli: async () => selfUpdateInstalledCli(selfUpdateOptions),
@@ -3871,7 +4121,7 @@ function createDefaultDependencies() {
 function buildProgram(dependencies) {
   const program2 = configureCommandPresentation(
     new Command2().name("mgcl").description("Run Magical operations from the command line.")
-  ).addOption(new Option2("--json", "Render JSON output.")).addOption(
+  ).addOption(new Option2("--json", "Render JSON output.")).version(CLI_VERSION, "--version", `Display mgcl version (${CLI_VERSION}).`).addOption(
     new Option2(
       "--update",
       "Update mgcl to the latest published npm release."
@@ -3897,6 +4147,13 @@ ${formatOutputModesNote()}`
     }
     this.outputHelp();
   });
+  program2.hook("preAction", async (_command, actionCommand) => {
+    await enforceLatestCliVersionIfNeeded({
+      actionCommand,
+      dependencies,
+      program: program2
+    });
+  });
   const authCommand = configureCommandPresentation(
     new Command2("auth").description("Manage CLI authentication.")
   ).helpGroup("Workspace:").addHelpText(