@stripe/extensibility-dev-tools 0.23.5

package/dist/extensibility-dev-tools-dependencies-internal.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Result of checking whether a dependency is satisfied.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Shared context threaded through CLI operations.
+ *
+ * Carry this through call chains so that output can be redirected in tests
+ * without patching global `process.stdout`/`process.stderr`.
+ *
+ * @internal
+ */
+declare interface _CliContext {
+    /** Output abstraction for writing to stdout/stderr. */
+    readonly ux: _CliUx;
+}
+
+/**
+ * Thin output abstraction used by CLI entry points and the functions they call.
+ *
+ * Inject a `_CliUx` constructed with `PassThrough` streams in tests to capture
+ * output without spying on `process.stdout`/`process.stderr`.
+ *
+ * @internal
+ */
+declare class _CliUx {
+    #private;
+    constructor(options?: {
+        readonly stderr?: NodeJS.WritableStream;
+        readonly stdout?: NodeJS.WritableStream;
+    });
+    /** Write a product output line to stdout (or the configured stream). */
+    print(message: string): void;
+    /** Write a status/progress line to stderr (or the configured stream). */
+    log(message: string): void;
+    /**
+     * Error message to **stderr** (or the configured stderr stream).
+     *
+     * Behaviorally identical to {@link _CliUx.log} today. Use `error()` for failures
+     * and `log()` for progress/status — the distinction supports future
+     * formatting differentiation (color, prefixes, severity filtering).
+     */
+    error(message: string): void;
+}
+
+/**
+ * Options for committing accumulated dependency changes.
+ * @internal
+ */
+export declare 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 declare interface _CommitResult {
+    /** Number of new dependencies added. */
+    added: number;
+    /** Number of existing dependencies updated. */
+    updated: number;
+}
+
+/**
+ * Result of checking whether a dependency version conflicts with an existing installation.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * A dependency that the workspace needs: npm runtime, npm dev, or Stripe CLI plugin.
+ * @internal
+ */
+export declare type _Dependency = _DevNpmDependency | _NpmDependency | _StripeCliPluginDependency;
+
+/**
+ * The action to take for a dependency: add new, update existing, no-op, or flag a conflict.
+ * @internal
+ */
+export declare type _DependencyAction = 'add' | 'already-satisfied' | 'conflict' | 'update';
+
+/**
+ * Handler interface for a specific dependency type (npm or Stripe CLI plugin).
+ * @internal
+ */
+export declare 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>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Options for constructing a dependency manager.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Detect the package manager used in the workspace by looking for lockfiles.
+ * @internal
+ */
+export declare function _detectPackageManager(cwd: string): _PackageManager;
+
+/**
+ * Create a dev npm dependency descriptor.
+ * @internal
+ */
+export declare function _devNpmDep(name: string, version: string): _DevNpmDependency;
+
+/**
+ * A dev npm dependency to add to `devDependencies` in package.json.
+ * @internal
+ */
+export declare interface _DevNpmDependency {
+    /** Discriminant tag identifying this as a dev npm dependency. */
+    type: 'dev-npm';
+    /** npm package name. */
+    name: string;
+    /** Semver version range. */
+    version: string;
+}
+
+/**
+ * Input for requesting dependency installation.
+ * @internal
+ */
+export declare interface _EnsureDependenciesInput {
+    /** Dependencies that must be present. */
+    required: _Dependency[];
+    /** Dependencies that are preferred but not required. */
+    optional?: _Dependency[];
+}
+
+/**
+ * Create a runtime npm dependency descriptor.
+ * @internal
+ */
+export declare function _npmDep(name: string, version: string): _NpmDependency;
+
+/**
+ * A runtime npm dependency to add to `dependencies` in package.json.
+ * @internal
+ */
+export declare interface _NpmDependency {
+    /** Discriminant tag identifying this as a runtime npm dependency. */
+    type: 'npm';
+    /** npm package name. */
+    name: string;
+    /** Semver version range. */
+    version: string;
+}
+
+/**
+ * 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: _DevNpmDependency | _NpmDependency): Promise<_CheckResult>;
+    /** Check whether the requested version conflicts with the currently installed version. */
+    checkConflict(dep: _DevNpmDependency | _NpmDependency): Promise<_ConflictResult>;
+    /** Add or update the npm dependency in package.json. */
+    add(dep: _DevNpmDependency | _NpmDependency): Promise<{
+        action: 'add' | 'update';
+        message: string;
+    }>;
+    /** Run the package manager install command in the working directory. */
+    install(_deps: (_DevNpmDependency | _NpmDependency)[]): Promise<void>;
+    private versionsCompatible;
+    private extractMajorVersion;
+}
+
+/**
+ * Options for constructing an npm dependency handler.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Package manager detected in the workspace.
+ * @internal
+ */
+export declare type _PackageManager = 'npm' | 'pnpm' | 'yarn';
+
+/**
+ * A pending dependency change accumulated by the dependency manager before commit.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Create a Stripe CLI plugin dependency descriptor.
+ * @internal
+ */
+export declare function _stripeCliPluginDep(name: string, minVersion?: string): _StripeCliPluginDependency;
+
+/**
+ * A Stripe CLI plugin dependency that must be installed via `stripe plugin install`.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * 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 Stripe CLI plugin dependency handler.
+ * @internal
+ */
+export declare 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;
+}
+
+export { }

package/dist/extensibility-dev-tools-dependencies-public.d.ts

@@ -0,0 +1,51 @@
+/* Excluded from this release type: _CheckResult */
+
+/* Excluded from this release type: _CliContext */
+
+/* Excluded from this release type: _CliUx */
+
+/* Excluded from this release type: _CommitOptions */
+
+/* Excluded from this release type: _CommitResult */
+
+/* Excluded from this release type: _ConflictResult */
+
+/* Excluded from this release type: _Dependency */
+
+/* Excluded from this release type: _DependencyAction */
+
+/* Excluded from this release type: _DependencyHandler */
+
+/* Excluded from this release type: _DependencyManager */
+
+/* Excluded from this release type: _DependencyManagerOptions */
+
+/* Excluded from this release type: _detectPackageManager */
+
+/* Excluded from this release type: _devNpmDep */
+
+/* Excluded from this release type: _DevNpmDependency */
+
+/* Excluded from this release type: _EnsureDependenciesInput */
+
+/* Excluded from this release type: _npmDep */
+
+/* Excluded from this release type: _NpmDependency */
+
+/* Excluded from this release type: _NpmDependencyHandler */
+
+/* Excluded from this release type: _NpmHandlerOptions */
+
+/* Excluded from this release type: _PackageManager */
+
+/* Excluded from this release type: _PendingChange */
+
+/* Excluded from this release type: _stripeCliPluginDep */
+
+/* Excluded from this release type: _StripeCliPluginDependency */
+
+/* Excluded from this release type: _StripeCliPluginHandler */
+
+/* Excluded from this release type: _StripeCliPluginHandlerOptions */
+
+export { }