@stripe/extensibility-dev-tools 0.23.5

package/dist/dependencies/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Dependencies module for installing and tracking dependencies
+ *
+ * This module handles the installation and tracking of dependencies required by generated code:
+ * - npm dependencies (added to package.json dependencies)
+ * - dev npm dependencies (added to package.json devDependencies)
+ * - Stripe CLI plugin dependencies (checks if installed, can auto-install)
+ *
+ * @deprecated NOT FOR EXTERNAL USE. This subpath is Stripe-internal and will be removed in a future release. External consumers must not depend on it.
+ * @internal
+ */
+import { type _CliContext } from '@stripe/extensibility-tool-utils';
+/**
+ * A runtime npm dependency to add to `dependencies` in package.json.
+ * @internal
+ */
+export interface _NpmDependency {
+    /** Discriminant tag identifying this as a runtime npm dependency. */
+    type: 'npm';
+    /** npm package name. */
+    name: string;
+    /** Semver version range. */
+    version: string;
+}
+/**
+ * A dev npm dependency to add to `devDependencies` in package.json.
+ * @internal
+ */
+export interface _DevNpmDependency {
+    /** Discriminant tag identifying this as a dev npm dependency. */
+    type: 'dev-npm';
+    /** npm package name. */
+    name: string;
+    /** Semver version range. */
+    version: string;
+}
+/**
+ * A Stripe CLI plugin dependency that must be installed via `stripe plugin install`.
+ * @internal
+ */
+export interface _StripeCliPluginDependency {
+    /** Discriminant tag identifying this as a Stripe CLI plugin dependency. */
+    type: 'stripe-cli-plugin';
+    /** Plugin shortname (e.g., `extensibility`). */
+    name: string;
+    /** Minimum required semver version of the plugin. */
+    minVersion?: string;
+}
+/**
+ * A dependency that the workspace needs: npm runtime, npm dev, or Stripe CLI plugin.
+ * @internal
+ */
+export type _Dependency = _NpmDependency | _DevNpmDependency | _StripeCliPluginDependency;
+/**
+ * Create a runtime npm dependency descriptor.
+ * @internal
+ */
+export declare function _npmDep(name: string, version: string): _NpmDependency;
+/**
+ * Create a dev npm dependency descriptor.
+ * @internal
+ */
+export declare function _devNpmDep(name: string, version: string): _DevNpmDependency;
+/**
+ * Create a Stripe CLI plugin dependency descriptor.
+ * @internal
+ */
+export declare function _stripeCliPluginDep(name: string, minVersion?: string): _StripeCliPluginDependency;
+/**
+ * Result of checking whether a dependency is satisfied.
+ * @internal
+ */
+export interface _CheckResult {
+    /** Whether the dependency requirement is currently satisfied. */
+    satisfied: boolean;
+    /** The currently installed version, if any. */
+    currentVersion?: string;
+    /** Human-readable message describing the check result. */
+    message: string;
+}
+/**
+ * Result of checking whether a dependency version conflicts with an existing installation.
+ * @internal
+ */
+export interface _ConflictResult {
+    /** Whether a version conflict exists. */
+    hasConflict: boolean;
+    /** The version currently installed, if any. */
+    existingVersion?: string;
+    /** The version being requested, if applicable. */
+    requestedVersion?: string;
+    /** Human-readable message describing the conflict, if any. */
+    message?: string;
+}
+/**
+ * The action to take for a dependency: add new, update existing, no-op, or flag a conflict.
+ * @internal
+ */
+export type _DependencyAction = 'add' | 'update' | 'already-satisfied' | 'conflict';
+/**
+ * A pending dependency change accumulated by the dependency manager before commit.
+ * @internal
+ */
+export interface _PendingChange {
+    /** The dependency this change applies to. */
+    dependency: _Dependency;
+    /** The action that will be taken for this dependency. */
+    action: _DependencyAction;
+    /** Human-readable message describing the pending change. */
+    message: string;
+    /** The previously installed version, if an update is involved. */
+    previousVersion?: string;
+    /** Conflict details when action is 'conflict'. */
+    conflict?: _ConflictResult;
+    /** Whether conflict has been resolved (force install) */
+    conflictResolved?: boolean;
+}
+/**
+ * Input for requesting dependency installation.
+ * @internal
+ */
+export interface _EnsureDependenciesInput {
+    /** Dependencies that must be present. */
+    required: _Dependency[];
+    /** Dependencies that are preferred but not required. */
+    optional?: _Dependency[];
+}
+/**
+ * Options for committing accumulated dependency changes.
+ * @internal
+ */
+export interface _CommitOptions {
+    /** If true, run package manager install for npm deps. Default: true */
+    runInstall?: boolean;
+}
+/**
+ * Summary of changes applied by a dependency manager commit.
+ * @internal
+ */
+export interface _CommitResult {
+    /** Number of new dependencies added. */
+    added: number;
+    /** Number of existing dependencies updated. */
+    updated: number;
+}
+/**
+ * Package manager detected in the workspace.
+ * @internal
+ */
+export type _PackageManager = 'pnpm' | 'yarn' | 'npm';
+/**
+ * Detect the package manager used in the workspace by looking for lockfiles.
+ * @internal
+ */
+export declare function _detectPackageManager(cwd: string): _PackageManager;
+/**
+ * Handler interface for a specific dependency type (npm or Stripe CLI plugin).
+ * @internal
+ */
+export interface _DependencyHandler<T extends _Dependency> {
+    /** Check if dependency is satisfied */
+    check(dep: T): Promise<_CheckResult>;
+    /** Check for conflicts with existing state */
+    checkConflict(dep: T): Promise<_ConflictResult>;
+    /** Add the dependency (update package.json for npm, noop for stripe cli) */
+    add(dep: T): Promise<{
+        action: 'add' | 'update';
+        message: string;
+    }>;
+    /** Run actual install (npm install for npm deps, stripe plugin install for cli) */
+    install(deps: T[]): Promise<void>;
+}
+/**
+ * Options for constructing an npm dependency handler.
+ * @internal
+ */
+export interface _NpmHandlerOptions {
+    /** Working directory containing the target package.json. */
+    cwd: string;
+    /** Whether to suppress console output. */
+    quiet: boolean;
+    /** If true, manage devDependencies; otherwise manage dependencies. */
+    devDependencies?: boolean;
+    /** CLI context for user-facing output. */
+    context?: _CliContext;
+}
+/**
+ * Handles npm and dev-npm dependency installation via package.json updates.
+ * @internal
+ */
+export declare class _NpmDependencyHandler implements _DependencyHandler<_NpmDependency | _DevNpmDependency> {
+    private readonly cwd;
+    private readonly quiet;
+    private readonly devDependencies;
+    private readonly context;
+    constructor(options: _NpmHandlerOptions);
+    private get dependencyKey();
+    private get dependencyLabel();
+    /** Check whether the npm dependency is already present in package.json. */
+    check(dep: _NpmDependency | _DevNpmDependency): Promise<_CheckResult>;
+    /** Check whether the requested version conflicts with the currently installed version. */
+    checkConflict(dep: _NpmDependency | _DevNpmDependency): Promise<_ConflictResult>;
+    /** Add or update the npm dependency in package.json. */
+    add(dep: _NpmDependency | _DevNpmDependency): Promise<{
+        action: 'add' | 'update';
+        message: string;
+    }>;
+    /** Run the package manager install command in the working directory. */
+    install(_deps: (_NpmDependency | _DevNpmDependency)[]): Promise<void>;
+    private versionsCompatible;
+    private extractMajorVersion;
+}
+/**
+ * Options for constructing a Stripe CLI plugin dependency handler.
+ * @internal
+ */
+export interface _StripeCliPluginHandlerOptions {
+    /** Path to the Stripe CLI config directory (e.g., `~/.config/stripe`). */
+    stripeConfigDir: string;
+    /** Whether to suppress console output. */
+    quiet: boolean;
+    /** CLI context for user-facing output. */
+    context?: _CliContext;
+}
+/**
+ * Handles Stripe CLI plugin installation via `stripe plugin install`.
+ * @internal
+ */
+export declare class _StripeCliPluginHandler implements _DependencyHandler<_StripeCliPluginDependency> {
+    private readonly stripeConfigDir;
+    private readonly quiet;
+    private readonly context;
+    constructor(options: _StripeCliPluginHandlerOptions);
+    /** Check whether the Stripe CLI plugin is installed and meets the minimum version. */
+    check(dep: _StripeCliPluginDependency): Promise<_CheckResult>;
+    /** Check whether the installed plugin version conflicts with the requested minimum. */
+    checkConflict(dep: _StripeCliPluginDependency): Promise<_ConflictResult>;
+    /** Stage a Stripe CLI plugin for installation; the actual install happens in `install`. */
+    add(dep: _StripeCliPluginDependency): Promise<{
+        action: 'add' | 'update';
+        message: string;
+    }>;
+    /** Install Stripe CLI plugins using `stripe plugin install`. */
+    install(deps: _StripeCliPluginDependency[]): Promise<void>;
+    private findPluginInToml;
+    /**
+     * 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
+     */
+    private isVersionSatisfied;
+}
+/**
+ * Options for constructing a dependency manager.
+ * @internal
+ */
+export interface _DependencyManagerOptions {
+    /** Working directory (defaults to process.cwd()) */
+    cwd?: string;
+    /** Path to Stripe config directory (defaults to ~/.config/stripe) */
+    stripeConfigDir?: string;
+    /** Whether to suppress console output */
+    quiet?: boolean;
+    /** CLI context for user-facing output */
+    context?: _CliContext;
+}
+/**
+ * Orchestrates dependency analysis and installation across all dependency types.
+ * @internal
+ */
+export declare class _DependencyManager {
+    private readonly cwd;
+    private readonly stripeConfigDir;
+    private readonly quiet;
+    private readonly context;
+    private readonly npmHandler;
+    private readonly devNpmHandler;
+    private readonly stripeCliPluginHandler;
+    /** Internal state: pending changes indexed by dependency key */
+    private pendingChanges;
+    /** Whether commit() has been called */
+    private committed;
+    constructor(options?: _DependencyManagerOptions);
+    /**
+     * Analyze dependencies and accumulate changes.
+     * Can be called multiple times before commit().
+     * Returns the changes for this specific call.
+     */
+    ensureDependencies(input: _EnsureDependenciesInput): Promise<_PendingChange[]>;
+    /**
+     * Resolve a conflict by marking it for force install.
+     * Throws if the dependency is not in conflict state.
+     */
+    resolveConflict(dep: _Dependency): void;
+    /**
+     * Get all pending changes (accumulated across all ensureDependencies calls).
+     */
+    getPendingChanges(): _PendingChange[];
+    /**
+     * 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
+     */
+    commit(options?: _CommitOptions): Promise<_CommitResult>;
+    private analyzeDependency;
+    private getHandler;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/dependencies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dependencies/index.ts"],"names":[],"mappings":"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"}