@stripe/extensibility-dev-tools 0.23.5

package/dist/dependencies/index.js

@@ -0,0 +1,560 @@
+// src/dependencies/index.ts
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { execSync } from "child_process";
+import PackageJson from "@npmcli/package-json";
+import * as semver from "semver";
+import { load as parseToml } from "js-toml";
+import { _createCliContext } from "@stripe/extensibility-tool-utils";
+function _npmDep(name, version) {
+  return { type: "npm", name, version };
+}
+function _devNpmDep(name, version) {
+  return { type: "dev-npm", name, version };
+}
+function _stripeCliPluginDep(name, minVersion) {
+  return minVersion ? { type: "stripe-cli-plugin", name, minVersion } : { type: "stripe-cli-plugin", name };
+}
+function _detectPackageManager(cwd) {
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fs.existsSync(path.join(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (fs.existsSync(path.join(cwd, "package-lock.json"))) {
+    return "npm";
+  }
+  let currentDir = cwd;
+  const root = path.parse(currentDir).root;
+  while (currentDir !== root) {
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) break;
+    if (fs.existsSync(path.join(parentDir, "pnpm-lock.yaml"))) {
+      if (fs.existsSync(path.join(parentDir, "pnpm-workspace.yaml"))) {
+        return "pnpm";
+      }
+    }
+    if (fs.existsSync(path.join(parentDir, "yarn.lock"))) {
+      return "yarn";
+    }
+    if (fs.existsSync(path.join(parentDir, "package-lock.json"))) {
+      return "npm";
+    }
+    currentDir = parentDir;
+  }
+  return "npm";
+}
+var _NpmDependencyHandler = class {
+  cwd;
+  quiet;
+  devDependencies;
+  context;
+  constructor(options) {
+    this.cwd = options.cwd;
+    this.quiet = options.quiet;
+    this.devDependencies = options.devDependencies ?? false;
+    this.context = options.context ?? _createCliContext();
+  }
+  get dependencyKey() {
+    return this.devDependencies ? "devDependencies" : "dependencies";
+  }
+  get dependencyLabel() {
+    return this.devDependencies ? "devDependencies" : "dependencies";
+  }
+  /** Check whether the npm dependency is already present in package.json. */
+  async check(dep) {
+    const packageJsonPath = path.join(this.cwd, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+      return {
+        satisfied: false,
+        message: `package.json not found at ${this.cwd}`
+      };
+    }
+    const pkgJson = await PackageJson.load(this.cwd);
+    const rawDeps = pkgJson.content[this.dependencyKey];
+    const deps = rawDeps ?? {};
+    const currentVersion = deps[dep.name];
+    if (currentVersion === void 0) {
+      return {
+        satisfied: false,
+        message: `${dep.name} not found in ${this.dependencyLabel}`
+      };
+    }
+    if (currentVersion === dep.version) {
+      return {
+        satisfied: true,
+        currentVersion,
+        message: `${dep.name}@${dep.version} already in ${this.dependencyLabel}`
+      };
+    }
+    if (this.versionsCompatible(currentVersion, dep.version)) {
+      return {
+        satisfied: true,
+        currentVersion,
+        message: `${dep.name}@${currentVersion} satisfies ${dep.version}`
+      };
+    }
+    return {
+      satisfied: false,
+      currentVersion,
+      message: `${dep.name}@${currentVersion} does not satisfy ${dep.version}`
+    };
+  }
+  /** Check whether the requested version conflicts with the currently installed version. */
+  async checkConflict(dep) {
+    const packageJsonPath = path.join(this.cwd, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+      return { hasConflict: false };
+    }
+    const pkgJson = await PackageJson.load(this.cwd);
+    const rawDeps = pkgJson.content[this.dependencyKey];
+    const deps = rawDeps ?? {};
+    const existingVersion = deps[dep.name];
+    if (existingVersion === void 0) {
+      return { hasConflict: false };
+    }
+    if (existingVersion === dep.version) {
+      return { hasConflict: false };
+    }
+    const existingMajor = this.extractMajorVersion(existingVersion);
+    const requestedMajor = this.extractMajorVersion(dep.version);
+    if (existingMajor !== null && requestedMajor !== null && existingMajor !== requestedMajor) {
+      return {
+        hasConflict: true,
+        existingVersion,
+        requestedVersion: dep.version,
+        message: `Major version mismatch: existing ${existingVersion} vs requested ${dep.version}`
+      };
+    }
+    if (!this.versionsCompatible(existingVersion, dep.version)) {
+      return {
+        hasConflict: true,
+        existingVersion,
+        requestedVersion: dep.version,
+        message: `Incompatible version ranges: existing ${existingVersion} vs requested ${dep.version}`
+      };
+    }
+    return { hasConflict: false };
+  }
+  /** Add or update the npm dependency in package.json. */
+  async add(dep) {
+    const packageJsonPath = path.join(this.cwd, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+      throw new Error(`package.json not found at ${this.cwd}`);
+    }
+    const pkgJson = await PackageJson.load(this.cwd);
+    const rawDeps = pkgJson.content[this.dependencyKey];
+    const deps = rawDeps ?? {};
+    const existingVersion = deps[dep.name];
+    const isUpdate = existingVersion !== void 0;
+    const update = {
+      [this.dependencyKey]: {
+        ...deps,
+        [dep.name]: dep.version
+      }
+    };
+    pkgJson.update(update);
+    await pkgJson.save();
+    const action = isUpdate ? "update" : "add";
+    const message = isUpdate ? `Updated ${dep.name} from ${existingVersion} to ${dep.version} in ${this.dependencyLabel}` : `Added ${dep.name}@${dep.version} to ${this.dependencyLabel}`;
+    if (!this.quiet) {
+      this.context.ux.log(`\u2713 ${message}`);
+    }
+    return { action, message };
+  }
+  /** Run the package manager install command in the working directory. */
+  install(_deps) {
+    const packageManager = _detectPackageManager(this.cwd);
+    if (!this.quiet) {
+      this.context.ux.log(`Running ${packageManager} install...`);
+    }
+    try {
+      execSync(`${packageManager} install`, {
+        cwd: this.cwd,
+        stdio: this.quiet ? "pipe" : "inherit"
+      });
+    } catch (error) {
+      const baseMessage = `Failed to run ${packageManager} install`;
+      if (error instanceof Error) {
+        return Promise.reject(new Error(`${baseMessage}: ${error.message}`));
+      }
+      return Promise.reject(new Error(`${baseMessage}: ${String(error)}`));
+    }
+    return Promise.resolve();
+  }
+  versionsCompatible(existing, requested) {
+    if (existing.startsWith("file:") || requested.startsWith("file:") || existing.startsWith("workspace:") || requested.startsWith("workspace:")) {
+      return existing === requested;
+    }
+    if (!semver.validRange(existing) || !semver.validRange(requested)) {
+      return existing === requested;
+    }
+    return semver.intersects(existing, requested);
+  }
+  extractMajorVersion(version) {
+    if (version.startsWith("file:") || version.startsWith("workspace:")) {
+      return null;
+    }
+    const coerced = semver.coerce(version);
+    if (coerced) {
+      return coerced.major;
+    }
+    return null;
+  }
+};
+var _StripeCliPluginHandler = class {
+  stripeConfigDir;
+  quiet;
+  context;
+  constructor(options) {
+    this.stripeConfigDir = options.stripeConfigDir;
+    this.quiet = options.quiet;
+    this.context = options.context ?? _createCliContext();
+  }
+  /** Check whether the Stripe CLI plugin is installed and meets the minimum version. */
+  check(dep) {
+    const pluginsTomlPath = path.join(this.stripeConfigDir, "plugins.toml");
+    if (!fs.existsSync(pluginsTomlPath)) {
+      return Promise.resolve({
+        satisfied: false,
+        message: `Stripe CLI plugin '${dep.name}' is not installed (plugins.toml not found)`
+      });
+    }
+    const pluginsContent = fs.readFileSync(pluginsTomlPath, "utf-8");
+    const installedPlugin = this.findPluginInToml(pluginsContent, dep.name);
+    if (!installedPlugin) {
+      return Promise.resolve({
+        satisfied: false,
+        message: `Stripe CLI plugin '${dep.name}' is not installed`
+      });
+    }
+    if (dep.minVersion && installedPlugin.version) {
+      if (!this.isVersionSatisfied(installedPlugin.version, dep.minVersion)) {
+        return Promise.resolve({
+          satisfied: false,
+          currentVersion: installedPlugin.version,
+          message: `Stripe CLI plugin '${dep.name}' version ${installedPlugin.version} is below minimum ${dep.minVersion}`
+        });
+      }
+    }
+    const result = {
+      satisfied: true,
+      message: `Stripe CLI plugin '${dep.name}' is installed${installedPlugin.version ? ` (version ${installedPlugin.version})` : ""}`
+    };
+    if (installedPlugin.version) {
+      result.currentVersion = installedPlugin.version;
+    }
+    return Promise.resolve(result);
+  }
+  /** Check whether the installed plugin version conflicts with the requested minimum. */
+  async checkConflict(dep) {
+    const checkResult = await this.check(dep);
+    if (checkResult.satisfied) {
+      return { hasConflict: false };
+    }
+    if (checkResult.currentVersion && dep.minVersion) {
+      return {
+        hasConflict: true,
+        existingVersion: checkResult.currentVersion,
+        requestedVersion: dep.minVersion,
+        message: `Installed version ${checkResult.currentVersion} is below minimum ${dep.minVersion}`
+      };
+    }
+    return { hasConflict: false };
+  }
+  /** Stage a Stripe CLI plugin for installation; the actual install happens in `install`. */
+  async add(dep) {
+    const checkResult = await this.check(dep);
+    const isUpdate = checkResult.currentVersion !== void 0;
+    const action = isUpdate ? "update" : "add";
+    const message = isUpdate ? `Will update Stripe CLI plugin '${dep.name}'` : `Will install Stripe CLI plugin '${dep.name}'`;
+    return { action, message };
+  }
+  /** Install Stripe CLI plugins using `stripe plugin install`. */
+  async install(deps) {
+    for (const dep of deps) {
+      const checkResult = await this.check(dep);
+      const isUpdate = checkResult.currentVersion !== void 0;
+      try {
+        execSync(`stripe plugin install ${dep.name}`, {
+          stdio: this.quiet ? "pipe" : "inherit"
+        });
+        const message = isUpdate ? `Updated Stripe CLI plugin '${dep.name}'` : `Installed Stripe CLI plugin '${dep.name}'`;
+        if (!this.quiet) {
+          this.context.ux.log(`\u2713 ${message}`);
+        }
+      } catch (error) {
+        const baseMessage = `Failed to install Stripe CLI plugin '${dep.name}'`;
+        if (error instanceof Error) {
+          throw new Error(`${baseMessage}: ${error.message}`);
+        }
+        throw new Error(`${baseMessage}: ${String(error)}`);
+      }
+    }
+  }
+  findPluginInToml(content, pluginName) {
+    try {
+      const parsed = parseToml(content);
+      const plugins = parsed.Plugin;
+      if (!plugins || !Array.isArray(plugins)) {
+        return null;
+      }
+      const plugin = plugins.find((p) => p.Shortname === pluginName);
+      if (!plugin) {
+        return null;
+      }
+      if (plugin.Release && Array.isArray(plugin.Release) && plugin.Release.length > 0) {
+        const currentArch = os.arch();
+        const currentOS = os.platform();
+        const normalizedArch = currentArch === "x64" ? "amd64" : currentArch;
+        const normalizedOS = currentOS === "win32" ? "windows" : currentOS;
+        const platformReleases = plugin.Release.filter(
+          (r) => r.Arch === normalizedArch && r.OS === normalizedOS
+        );
+        if (platformReleases.length === 0) {
+          return null;
+        }
+        const localBuildRelease = platformReleases.find(
+          (r) => r.Version === "local.build.dev"
+        );
+        if (localBuildRelease) {
+          return { version: "local.build.dev" };
+        }
+        const versions = platformReleases.map((r) => r.Version).filter((v) => v !== void 0);
+        if (versions.length === 0) {
+          return null;
+        }
+        const sortedVersions = versions.map((v) => ({ original: v, parsed: semver.coerce(v) })).filter(
+          (v) => v.parsed !== null
+        ).sort((a, b) => semver.rcompare(a.parsed, b.parsed));
+        if (sortedVersions.length === 0) {
+          return { version: versions[0] };
+        }
+        return { version: sortedVersions[0]?.original };
+      }
+      return { version: plugin.Version };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Check if installed version satisfies the required minimum version.
+   *
+   * Permissive policy: Non-semver versions (e.g., "local.build.dev", "dev", "canary-abc123")
+   * always satisfy version requirements. This avoids forcing upgrades during local development
+   * when developers are using locally built plugins.
+   *
+   * For valid semver versions, uses the semver library for proper semantic version comparison.
+   *
+   * @param installed - The installed version string
+   * @param required - The required minimum version string
+   * @returns true if installed version satisfies requirement
+   */
+  isVersionSatisfied(installed, required) {
+    const installedSemver = semver.coerce(installed);
+    const requiredSemver = semver.coerce(required);
+    if (!installedSemver) {
+      return true;
+    }
+    if (!requiredSemver) {
+      return true;
+    }
+    return semver.gte(installedSemver, requiredSemver);
+  }
+};
+function dependencyKey(dep) {
+  return `${dep.type}:${dep.name}`;
+}
+var _DependencyManager = class {
+  cwd;
+  stripeConfigDir;
+  quiet;
+  context;
+  npmHandler;
+  devNpmHandler;
+  stripeCliPluginHandler;
+  /** Internal state: pending changes indexed by dependency key */
+  pendingChanges = /* @__PURE__ */ new Map();
+  /** Whether commit() has been called */
+  committed = false;
+  constructor(options = {}) {
+    this.cwd = options.cwd ?? process.cwd();
+    this.stripeConfigDir = options.stripeConfigDir ?? path.join(os.homedir(), ".config", "stripe");
+    this.quiet = options.quiet ?? false;
+    this.context = options.context ?? _createCliContext();
+    this.npmHandler = new _NpmDependencyHandler({
+      cwd: this.cwd,
+      quiet: this.quiet,
+      devDependencies: false,
+      context: this.context
+    });
+    this.devNpmHandler = new _NpmDependencyHandler({
+      cwd: this.cwd,
+      quiet: this.quiet,
+      devDependencies: true,
+      context: this.context
+    });
+    this.stripeCliPluginHandler = new _StripeCliPluginHandler({
+      stripeConfigDir: this.stripeConfigDir,
+      quiet: this.quiet,
+      context: this.context
+    });
+  }
+  /**
+   * Analyze dependencies and accumulate changes.
+   * Can be called multiple times before commit().
+   * Returns the changes for this specific call.
+   */
+  async ensureDependencies(input) {
+    if (this.committed) {
+      throw new Error("DependencyManager has already been committed");
+    }
+    const { required, optional = [] } = input;
+    const changes = [];
+    for (const dep of [...required, ...optional]) {
+      const change = await this.analyzeDependency(dep);
+      changes.push(change);
+      this.pendingChanges.set(dependencyKey(dep), change);
+    }
+    return changes;
+  }
+  /**
+   * Resolve a conflict by marking it for force install.
+   * Throws if the dependency is not in conflict state.
+   */
+  resolveConflict(dep) {
+    if (this.committed) {
+      throw new Error("DependencyManager has already been committed");
+    }
+    const key = dependencyKey(dep);
+    const change = this.pendingChanges.get(key);
+    if (!change) {
+      throw new Error(`Dependency '${dep.name}' not found in pending changes`);
+    }
+    if (change.action !== "conflict") {
+      throw new Error(
+        `Dependency '${dep.name}' is not in conflict (action: ${change.action})`
+      );
+    }
+    change.conflictResolved = true;
+  }
+  /**
+   * Get all pending changes (accumulated across all ensureDependencies calls).
+   */
+  getPendingChanges() {
+    return Array.from(this.pendingChanges.values());
+  }
+  /**
+   * Commit all accumulated changes.
+   * - For npm deps: updates package.json, optionally runs package manager install
+   * - For Stripe CLI deps: always installs (no separate add step)
+   *
+   * @param options - Commit options. `options.runInstall`: if true, run package manager install for npm deps (default: true)
+   * @returns Summary of changes made
+   * @throws If called more than once
+   */
+  async commit(options = {}) {
+    if (this.committed) {
+      throw new Error("DependencyManager has already been committed");
+    }
+    this.committed = true;
+    const { runInstall = true } = options;
+    let added = 0;
+    let updated = 0;
+    const npmDeps = [];
+    const stripeCliDeps = [];
+    for (const change of this.pendingChanges.values()) {
+      if (change.action === "already-satisfied") {
+        continue;
+      }
+      if (change.action === "conflict" && !change.conflictResolved) {
+        continue;
+      }
+      const dep = change.dependency;
+      if (dep.type === "npm" || dep.type === "dev-npm") {
+        npmDeps.push(dep);
+      } else {
+        stripeCliDeps.push(dep);
+      }
+    }
+    for (const dep of npmDeps) {
+      const handler = dep.type === "npm" ? this.npmHandler : this.devNpmHandler;
+      const result = await handler.add(dep);
+      if (result.action === "add") {
+        added++;
+      } else {
+        updated++;
+      }
+    }
+    if (runInstall && npmDeps.length > 0) {
+      await this.npmHandler.install(npmDeps);
+    }
+    if (stripeCliDeps.length > 0) {
+      await this.stripeCliPluginHandler.install(stripeCliDeps);
+      for (const dep of stripeCliDeps) {
+        const change = this.pendingChanges.get(dependencyKey(dep));
+        if (change?.action === "add" || change?.action === "conflict" && !change.previousVersion) {
+          added++;
+        } else {
+          updated++;
+        }
+      }
+    }
+    return { added, updated };
+  }
+  async analyzeDependency(dep) {
+    const handler = this.getHandler(dep);
+    const checkResult = await handler.check(dep);
+    if (checkResult.satisfied) {
+      return {
+        dependency: dep,
+        action: "already-satisfied",
+        message: checkResult.message
+      };
+    }
+    const conflictResult = await handler.checkConflict(dep);
+    if (conflictResult.hasConflict) {
+      const result2 = {
+        dependency: dep,
+        action: "conflict",
+        message: conflictResult.message ?? "Dependency conflict detected",
+        conflict: conflictResult
+      };
+      if (conflictResult.existingVersion) {
+        result2.previousVersion = conflictResult.existingVersion;
+      }
+      return result2;
+    }
+    const isUpdate = checkResult.currentVersion !== void 0;
+    const result = {
+      dependency: dep,
+      action: isUpdate ? "update" : "add",
+      message: isUpdate ? `Will update ${dep.name} from ${String(checkResult.currentVersion)}` : `Will add ${dep.name}`
+    };
+    if (checkResult.currentVersion) {
+      result.previousVersion = checkResult.currentVersion;
+    }
+    return result;
+  }
+  getHandler(dep) {
+    switch (dep.type) {
+      case "npm":
+        return this.npmHandler;
+      case "dev-npm":
+        return this.devNpmHandler;
+      case "stripe-cli-plugin":
+        return this.stripeCliPluginHandler;
+    }
+  }
+};
+export {
+  _DependencyManager,
+  _NpmDependencyHandler,
+  _StripeCliPluginHandler,
+  _detectPackageManager,
+  _devNpmDep,
+  _npmDep,
+  _stripeCliPluginDep
+};