@venn-lang/cli 0.1.0

package/src/upgrade/latest-version.ts

@@ -0,0 +1,50 @@
+import { PACKAGE_NAME } from "./upgrade-plan.js";
+
+/** How long to wait on the registry before giving up and saying so. */
+const TIMEOUT_MS = 5_000;
+
+/**
+ * The newest published version, asked of the registry.
+ *
+ * Only the `dist-tags` document is fetched rather than the full package
+ * metadata, which for this package is megabytes of version history nobody
+ * asked for.
+ *
+ * @returns The version under the `latest` tag, or nothing when the registry
+ * cannot be reached. Being offline is not an error worth stopping for.
+ */
+export async function latestVersion(): Promise<string | undefined> {
+  const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
+  try {
+    const answer = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!answer.ok) return undefined;
+    const tags = (await answer.json()) as Record<string, string>;
+    return typeof tags.latest === "string" ? tags.latest : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether `candidate` is a later release than `current`.
+ *
+ * Compares the numeric parts only. A prerelease is never offered as an upgrade
+ * to someone on a stable version, since opting into one is a decision rather
+ * than an update.
+ */
+export function isNewer(args: { current: string; candidate: string }): boolean {
+  if (args.candidate.includes("-")) return false;
+  const now = parts(args.current);
+  const next = parts(args.candidate);
+  for (let at = 0; at < 3; at += 1) {
+    const a = next[at] ?? 0;
+    const b = now[at] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return false;
+}
+
+function parts(version: string): number[] {
+  const stable = version.split("-")[0] ?? version;
+  return stable.split(".").map((piece) => Number.parseInt(piece, 10) || 0);
+}

package/src/upgrade/upgrade-command.ts

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+import type { InstallSite, UpgradeOptions } from "./upgrade.types.js";
+import { upgradeCommandFor } from "./upgrade-plan.js";
+
+/**
+ * The shell command that moves this install to the latest version.
+ *
+ * Runs the manager rather than rewriting files: the CLI cannot replace itself
+ * while it is executing, and on Windows the running executable is locked.
+ *
+ * @returns The exit code of the manager, or 1 when it could not be started.
+ */
+export function runUpgrade(args: { site: InstallSite; options: UpgradeOptions }): Promise<number> {
+  const command = upgradeCommandFor(args.site.manager);
+  if (!command) return Promise.resolve(1);
+  if (args.options.dryRun) {
+    process.stdout.write(`${command.join(" ")}\n`);
+    return Promise.resolve(0);
+  }
+  return spawned(command);
+}
+
+function spawned(command: readonly string[]): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(command[0] as string, command.slice(1), {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => resolve(1));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}

package/src/upgrade/upgrade-plan.ts

@@ -0,0 +1,36 @@
+import type { InstallSite, PackageManager } from "./upgrade.types.js";
+
+/** The published name, which is what a manager is asked to install. */
+export const PACKAGE_NAME = "@venn-lang/cli";
+
+/**
+ * How each manager is told to install the latest version globally.
+ *
+ * @returns The command as its argument list, or nothing when the manager is
+ * unknown and guessing would be worse than saying so.
+ */
+export function upgradeCommandFor(manager: PackageManager): readonly string[] | undefined {
+  if (manager === "npm") return ["npm", "install", "-g", `${PACKAGE_NAME}@latest`];
+  if (manager === "pnpm") return ["pnpm", "add", "-g", `${PACKAGE_NAME}@latest`];
+  if (manager === "bun") return ["bun", "add", "-g", `${PACKAGE_NAME}@latest`];
+  if (manager === "yarn") return ["yarn", "global", "add", `${PACKAGE_NAME}@latest`];
+  return undefined;
+}
+
+/** Why an upgrade cannot proceed, phrased for the person who typed the command. */
+export function refusalFor(site: InstallSite): string | undefined {
+  if (site.manager === "unknown") {
+    return [
+      "Cannot tell how this copy of venn was installed, so it will not guess.",
+      `Reinstall it with your package manager, for example: npm install -g ${PACKAGE_NAME}@latest`,
+    ].join("\n");
+  }
+  if (!site.global) {
+    return [
+      "This copy belongs to the project, not to you.",
+      `Its version is pinned in package.json, so upgrading here would be undone by the next install.`,
+      `Update it there instead: ${site.manager} ${site.manager === "npm" ? "install" : "add"} -D ${PACKAGE_NAME}@latest`,
+    ].join("\n");
+  }
+  return undefined;
+}

package/src/upgrade/upgrade.types.ts

@@ -0,0 +1,17 @@
+/** The package managers that can install a global CLI. */
+export type PackageManager = "npm" | "pnpm" | "bun" | "yarn" | "unknown";
+
+/** Where a copy of the CLI came from. */
+export interface InstallSite {
+  manager: PackageManager;
+  /** False when the copy belongs to a project rather than to the user. */
+  global: boolean;
+}
+
+/** What `venn upgrade` was asked to do. */
+export interface UpgradeOptions {
+  /** Skip the confirmation. For scripts, never for a person. */
+  yes?: boolean;
+  /** Report what would happen and change nothing. */
+  dryRun?: boolean;
+}

package/src/upgrade/version.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+
+/**
+ * The version of the CLI that is running.
+ *
+ * Read from the package manifest rather than written into the source, so a
+ * release cannot ship a binary that reports the version before it. The manifest
+ * sits one level above the bundle, which is true both in `dist` and in `src`
+ * during development.
+ */
+export const VERSION: string = read();
+
+function read(): string {
+  try {
+    const require = createRequire(import.meta.url);
+    const manifest = require("../../package.json") as { version?: string };
+    return manifest.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}