@stripe/extensibility-dev-tools 0.23.5

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

@@ -0,0 +1,554 @@
+/**
+ * Shows an advanced diff viewer with scrolling and colorized output.
+ * Falls back to basic prompt if not in a TTY or on error.
+ *
+ * @param filePath - Relative path to the file (for display)
+ * @param cwd - Working directory to resolve the path from
+ * @param newContent - New content that would be written
+ * @returns User's decision about overwriting
+ * @internal
+ */
+export declare function _advancedDiffPrompt(filePath: string, cwd: string, newContent: string): Promise<_OverwriteDecision>;
+
+/**
+ * Generate the ESLint config file for an extension workspace.
+ * @internal
+ */
+export declare function _createExtensionEslintConfigFile(params: { extensionInterfaceId: string } & Pick<_ExtensionParams, 'id'>, context: _TemplateContext): _GeneratedFile;
+
+/**
+ * Helper for creating a SingleTemplateManager with simple single-file generation
+ *
+ * @param generateContent - Function that generates file content from parameters
+ * @param pathTemplate - Function that generates file path from parameters
+ * @returns SingleTemplateManager ready to use
+ *
+ * @example
+ * ```typescript
+ * interface MyParams {
+ *   name: string
+ * }
+ *
+ * // Simple template that generates content from parameters
+ * const templateManager = createSimpleSingleFileTemplate<MyParams>(
+ *   (params) => `export class ${params.name} { ... }`,
+ *   (params) => `src/${snakeCase(params.name)}.ts`
+ * )
+ *
+ * const output = await templateManager.generate({ name: 'MyClass' })
+ * // output.files[0] = { path: 'src/my_class.ts', content: '...' }
+ * ```
+ * @internal
+ */
+export declare function _createSimpleSingleFileTemplate<TParams>(generateContent: (params: TParams) => string, pathTemplate: (params: TParams) => string): _SingleTemplateManager<TParams>;
+
+/**
+ * Convert a simple content generator to a full Template
+ * @param generateContent - Function that generates file content from parameters
+ * @param pathTemplate - Function that generates file path from parameters
+ * @returns Full Template implementation
+ *
+ * @example
+ * ```typescript
+ * interface MyParams {
+ *   name: string
+ *   version: string
+ * }
+ *
+ * const template = createSimpleTemplate<MyParams>(
+ *   (params) => `export const ${params.name} = "${params.version}";`,
+ *   (params) => `src/${snakeCase(params.name)}.ts`
+ * )
+ * ```
+ * @internal
+ */
+export declare function _createSimpleTemplate<TParams>(generateContent: (params: TParams) => string, pathTemplate: (params: TParams) => string): _Template<TParams>;
+
+/**
+ * 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;
+}
+
+/**
+ * Static metadata for a single method on an extension template
+ * @internal
+ */
+export declare interface _ExtensionMethodInfo {
+    /** Implementation types supported by this method (e.g. 'script', 'remote-function') */
+    implementation_types: string[];
+}
+
+/**
+ * Parameters for extension template generation
+ * @internal
+ */
+export declare interface _ExtensionParams extends Record<string, unknown> {
+    /** Extension ID (validated to be safe for file paths and IDs) */
+    id: string;
+    /** Human-readable name for the extension */
+    name: string;
+    /** Package version (preserved from existing package.json, defaults to 0.0.1) */
+    version: string;
+}
+
+/**
+ * Extension template - specialization of generic Template with a description
+ * @internal
+ */
+export declare interface _ExtensionTemplate extends _Template<_ExtensionParams, _ExtensionTemplateOutput> {
+    /** Short human-readable description of the extension interface */
+    description: string;
+    /** Whether this template is deprecated and should not be offered for new extensions */
+    deprecated?: boolean;
+    /** Whether this template is hidden from `stripe generate` (used only by the build pipeline) */
+    hidden?: boolean;
+    /** Static metadata for each method — implementation types supported per method */
+    methods: Record<string, _ExtensionMethodInfo>;
+}
+
+/**
+ * Summary info for a registered extension template
+ * @internal
+ */
+export declare interface _ExtensionTemplateInfo {
+    /** Template key (the extension interface ID) */
+    key: string;
+    /** Short human-readable description */
+    description: string;
+    /** Whether this template is deprecated */
+    deprecated: boolean;
+    /** Whether this template is hidden from user-facing generators */
+    hidden: boolean;
+    /** Static metadata for each method — implementation types supported per method */
+    methods: Record<string, _ExtensionMethodInfo>;
+}
+
+/**
+ * Extension template manager
+ * Specialized TemplateManager for extension generation
+ * @internal
+ */
+export declare class _ExtensionTemplateManager extends _TemplateManager<_ExtensionParams, _ExtensionTemplateOutput, _ExtensionTemplate> {
+    /**
+     * Get summary info for all registered extension templates
+     */
+    getTemplateInfo(): _ExtensionTemplateInfo[];
+}
+
+/**
+ * Output from extension template generation
+ * @internal
+ */
+export declare interface _ExtensionTemplateOutput extends _TemplateOutput {
+    /** Methods configuration for stripe-app.yaml */
+    methods: Record<string, unknown>;
+    /** Dependencies required by the extension */
+    dependencies?: {
+        dev?: _DevNpmDependency[];
+        runtime?: _NpmDependency[];
+    };
+    /** Post-generation hooks to run after files are generated and dependencies installed */
+    postGenerationHooks?: _PostGenerationHook[];
+}
+
+/**
+ * Result of writing files
+ * @internal
+ */
+export declare interface _FileWriteResult {
+    /**
+     * Paths of files that were successfully written (relative to cwd)
+     * Includes both newly created files and overwritten files
+     */
+    written: string[];
+    /**
+     * Paths of all files that already existed before the operation (relative to cwd)
+     * Always populated when files exist, regardless of whether they were overwritten
+     */
+    existing: string[];
+    /**
+     * Whether the entire operation was skipped due to overwrite='abort-if-existing' with existing files
+     * True only when overwrite='abort-if-existing' and files exist (all-or-nothing behavior)
+     * False for all other modes including interactive (even if user skips all files)
+     */
+    skipped: boolean;
+    /**
+     * Whether the user aborted the operation during interactive prompting
+     * True only when user chose 'quit' during interactive mode
+     * Caller should stop further processing (dependencies, hooks, etc.)
+     */
+    aborted: boolean;
+}
+
+/**
+ * Options for writing generated files
+ * @internal
+ */
+export declare interface _FileWriterOptions {
+    /**
+     * Working directory to write files relative to
+     * Defaults to process.cwd()
+     */
+    cwd?: string;
+    /**
+     * How to handle existing files:
+     * - 'overwrite-all': Overwrite all existing files
+     * - 'abort-if-existing': Refuse to write ANY files if ANY already exist (all-or-nothing)
+     * - 'if-missing': Skip individual files that exist, write only missing files
+     * - function: Prompt before overwriting each file (interactive ask mode)
+     * Defaults to 'abort-if-existing'
+     */
+    write?: _WriteMode;
+    /**
+     * Callback invoked after a file is successfully written
+     * @param file - The file that was written
+     * @param wasOverwrite - True if file existed and was overwritten, false if newly created
+     */
+    onFileWritten?: (file: _GeneratedFile, wasOverwrite: boolean) => void;
+    /**
+     * Callback invoked when a file already exists and is skipped
+     * @param file - The file that was skipped
+     */
+    onFileSkipped?: (file: _GeneratedFile) => void;
+    /**
+     * Callback invoked when a file already exists with identical content
+     * @param file - The file that is identical
+     */
+    onFileIdentical?: (file: _GeneratedFile) => void;
+}
+
+/**
+ * Default TemplateFS instance rooted at templates/
+ *
+ * ESM: Uses filesystem implementation (reads from templates/ directory)
+ * CJS: This entire file is replaced with in-memory implementation
+ * @internal
+ */
+export declare const _fs: _TemplateFS;
+
+/**
+ * Core generic types for the template system
+ *
+ * This module provides the foundation for a flexible, type-safe template system
+ * that can be specialized for different use cases (extensions, custom objects, etc.)
+ */
+/**
+ * Represents a single generated file
+ * @internal
+ */
+export declare interface _GeneratedFile {
+    /**
+     * Path to the file relative to project root
+     * Example: "extensions/my-extension/src/index.ts"
+     */
+    path: string;
+    /**
+     * Content of the file
+     */
+    content: string;
+    /**
+     * Never overwrite this file, even if --force specified.
+     */
+    precious?: boolean;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * User decision when prompted about overwriting a file
+ * @internal
+ */
+export declare type _OverwriteDecision = 'abort' | 'overwrite-all' | 'overwrite' | 'skip';
+
+/**
+ * Callback function for prompting about file overwrites
+ * @param path - Relative path to the file that would be overwritten
+ * @param cwd - Working directory (for resolving the path)
+ * @param newContent - Content of the file that would be written
+ * @returns Promise resolving to user's decision
+ * @internal
+ */
+export declare type _OverwritePromptCallback = (path: string, cwd: string, newContent: string) => Promise<_OverwriteDecision>;
+
+/**
+ * Post-generation hook configuration
+ * Either `script` (run via `pnpm run`) or `exec` (run via `pnpm exec`)
+ * @internal
+ */
+export declare type _PostGenerationHook = {
+    description?: string;
+    exec: string;
+} | {
+    description?: string;
+    script: string;
+};
+
+/**
+ * Simple text-based prompt for overwrite decisions
+ * Uses single-keypress input in interactive terminals (no Enter required)
+ * Falls back to line-based input in non-interactive environments (tests, CI)
+ *
+ * @param filePath - Path to the file that would be overwritten
+ * @returns Promise resolving to user's decision
+ * @internal
+ */
+export declare function _promptOverwrite(filePath: string): Promise<_OverwriteDecision>;
+
+/**
+ * Root workspace template manager
+ * Automatically selects filesystem or in-memory implementation
+ * @internal
+ */
+export declare const _rootTemplateManager: _SingleTemplateManager<_RootWorkspaceParams, _RootWorkspaceOutput>;
+
+/**
+ * Output from root workspace template generation
+ * @internal
+ */
+export declare interface _RootWorkspaceOutput extends _TemplateOutput {
+    /** Dependencies to install after file generation. */
+    dependencies?: {
+        dev?: _DevNpmDependency[];
+        runtime?: _NpmDependency[];
+    };
+    /** Hooks to run after dependencies are installed. */
+    postGenerationHooks?: _PostGenerationHook[];
+}
+
+/**
+ * Parameters for root workspace template generation
+ * @internal
+ */
+export declare interface _RootWorkspaceParams extends Record<string, unknown> {
+    /** The app identifier (package.json `name`). */
+    appId: string;
+    /** The app display name (package.json `description`). */
+    appName: string;
+    /** The app version string. */
+    version: string;
+}
+
+/**
+ * Root workspace template generator.
+ *
+ * Generates common configuration files for the monorepo root:
+ * - .prettierrc (code formatting config)
+ * - .prettierignore (files to ignore in formatting)
+ *
+ * @example
+ * ```typescript
+ * const output = rootWorkspaceTemplate.generate({}, context);
+ * await writeFiles(output.files, '.', true);
+ * ```
+ * @internal
+ */
+export declare const _rootWorkspaceTemplate: _Template<_RootWorkspaceParams, _RootWorkspaceOutput>;
+
+/**
+ * Single template manager - no registry lookup needed
+ * For commands that only have one template
+ * @internal
+ */
+export declare class _SingleTemplateManager<TParams, TOutput extends _TemplateOutput = _TemplateOutput> {
+    private readonly template;
+    private readonly fs;
+    /**
+     * Create a new SingleTemplateManager
+     * @param template - The single template to use
+     * @param fs - Filesystem for template file reading
+     */
+    constructor(template: _Template<TParams, TOutput>, fs: _TemplateFS);
+    /**
+     * Generate output from the template
+     * @param params - Template parameters
+     * @returns Template output
+     */
+    generate(params: TParams): Promise<TOutput>;
+}
+
+/**
+ * Template definition
+ * Wraps a generate function with any associated metadata
+ *
+ * @typeParam TParams - Parameters for template generation
+ * @typeParam TOutput - Output type (must extend TemplateOutput)
+ * @internal
+ */
+export declare interface _Template<TParams, TOutput extends _TemplateOutput = _TemplateOutput> {
+    /**
+     * Generate files and other output from the template
+     */
+    generate(params: TParams, context: _TemplateContext): Promise<TOutput> | TOutput;
+}
+
+/**
+ * Context for template generation
+ * Provides optional capabilities like file reading and user prompts
+ * Templates can ignore this parameter if they don't need these features
+ * @internal
+ */
+export declare interface _TemplateContext {
+    /**
+     * Filesystem abstraction for reading template files
+     */
+    fs: _TemplateFS;
+}
+
+/**
+ * Filesystem abstraction for template factories
+ * @internal
+ */
+export declare interface _TemplateFS {
+    /**
+     * Read a text file relative to the templates directory
+     *
+     * Note: Only supports text files. Binary files are not supported by the
+     * current implementation (template content is embedded as strings during
+     * CJS bundling, which doesn't work for binary data).
+     */
+    textFile(...segments: string[]): string;
+    /**
+     * Read a file and process it with Mustache template engine
+     * @param params - Parameters to pass to the template
+     * @param segments - Path segments to the template file
+     */
+    mustache(params: Record<string, unknown>, ...segments: string[]): string;
+    /**
+     * Create a scoped TemplateFS with an implicit path prefix
+     * @param prefix - Path segment to prepend to all operations
+     * @returns New TemplateFS instance with the prefix applied
+     */
+    scope(prefix: string): _TemplateFS;
+}
+
+/**
+ * Generic template manager
+ * Manages template selection and generation with full type safety
+ *
+ * @typeParam TParams - Template parameters type
+ * @typeParam TOutput - Template output type (must extend TemplateOutput)
+ * @typeParam TTemplate - Concrete template type (defaults to Template; specify to preserve extra fields in getTemplateEntries)
+ * @internal
+ */
+export declare class _TemplateManager<TParams, TOutput extends _TemplateOutput = _TemplateOutput, TTemplate extends _Template<TParams, TOutput> = _Template<TParams, TOutput>> {
+    private readonly templates;
+    private readonly fs;
+    /**
+     * Create a new TemplateManager
+     * @param templates - Object mapping string keys to templates
+     * @param fs - Filesystem abstraction for template file reading
+     *
+     * @example
+     * ```typescript
+     * import { fs } from './fs/index.js';
+     *
+     * const manager = new TemplateManager({
+     *   foo: fooTemplate,
+     *   bar: barTemplate,
+     * }, fs)
+     *
+     * await manager.generate('foo', params)
+     * ```
+     */
+    constructor(templates: Record<string, TTemplate>, fs: _TemplateFS);
+    /**
+     * Generate output from a template
+     * @param key - Template key to generate from
+     * @param params - Template-specific parameters
+     * @returns Template output with files and any additional fields
+     * @throws Error if template key is not found
+     */
+    generate(key: string, params: TParams): Promise<TOutput>;
+    /**
+     * Get all template entries as [key, template] pairs
+     */
+    protected getTemplateEntries(): [string, TTemplate][];
+    /**
+     * Get list of all supported template keys
+     */
+    getSupportedKeys(): string[];
+}
+
+/**
+ * ExtensionTemplateManager configured with built-in templates
+ * Automatically selects filesystem or in-memory implementation
+ * @internal
+ */
+export declare const _templateManager: _ExtensionTemplateManager;
+
+/**
+ * Base template output - always includes files array
+ * Extend this interface to add additional output fields
+ * @internal
+ */
+export declare interface _TemplateOutput {
+    /** Files to write to disk. */
+    files: _GeneratedFile[];
+}
+
+/**
+ * Write generated files to disk with configurable write behavior
+ *
+ * Write modes:
+ * - 'overwrite-all': Overwrite all existing files without prompting
+ * - 'abort-if-existing': Refuse to write ANY files if ANY exist (all-or-nothing, sets skipped=true)
+ * - 'if-missing': Write only files that don't exist, skip existing ones individually
+ * - function: Prompt for each existing file (y/n/a/q), allows selective overwriting
+ *
+ * Always creates parent directories as needed (mkdir -p behavior)
+ *
+ * @param files - Files to write
+ * @param options - Write options (cwd, write mode, callbacks)
+ * @returns Result with written files, existing files, and skip status
+ *
+ * @example
+ * ```typescript
+ * // All-or-nothing mode
+ * const result = await _writeGeneratedFiles(files, {
+ *   cwd: process.cwd(),
+ *   write: 'abort-if-existing'
+ * })
+ * if (result.skipped) {
+ *   throw new Error(`Files exist: ${result.existing.join(', ')}`)
+ * }
+ *
+ * // Interactive mode
+ * await _writeGeneratedFiles(files, {
+ *   cwd: process.cwd(),
+ *   write: async (path, newContent) => await _promptOverwrite(path)
+ * })
+ * ```
+ * @internal
+ */
+export declare function _writeGeneratedFiles(files: _GeneratedFile[], options?: _FileWriterOptions): Promise<_FileWriteResult>;
+
+/**
+ * File write behavior modes
+ * - 'overwrite-all': Overwrite all existing files
+ * - 'abort-if-existing': Refuse to write ANY files if ANY already exist (all-or-nothing)
+ * - 'if-missing': Skip individual files that exist, write only missing files
+ * - function: Prompt before overwriting each file (interactive ask mode)
+ * @internal
+ */
+export declare type _WriteMode = _OverwritePromptCallback | 'abort-if-existing' | 'if-missing' | 'overwrite-all';
+
+export { }

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

@@ -0,0 +1,67 @@
+/* Excluded from this release type: _advancedDiffPrompt */
+
+/* Excluded from this release type: _createExtensionEslintConfigFile */
+
+/* Excluded from this release type: _createSimpleSingleFileTemplate */
+
+/* Excluded from this release type: _createSimpleTemplate */
+
+/* Excluded from this release type: _DevNpmDependency */
+
+/* Excluded from this release type: _ExtensionMethodInfo */
+
+/* Excluded from this release type: _ExtensionParams */
+
+/* Excluded from this release type: _ExtensionTemplate */
+
+/* Excluded from this release type: _ExtensionTemplateInfo */
+
+/* Excluded from this release type: _ExtensionTemplateManager */
+
+/* Excluded from this release type: _ExtensionTemplateOutput */
+
+/* Excluded from this release type: _FileWriteResult */
+
+/* Excluded from this release type: _FileWriterOptions */
+
+/* Excluded from this release type: _fs */
+
+/* Excluded from this release type: _GeneratedFile */
+
+/* Excluded from this release type: _NpmDependency */
+
+/* Excluded from this release type: _OverwriteDecision */
+
+/* Excluded from this release type: _OverwritePromptCallback */
+
+/* Excluded from this release type: _PostGenerationHook */
+
+/* Excluded from this release type: _promptOverwrite */
+
+/* Excluded from this release type: _rootTemplateManager */
+
+/* Excluded from this release type: _RootWorkspaceOutput */
+
+/* Excluded from this release type: _RootWorkspaceParams */
+
+/* Excluded from this release type: _rootWorkspaceTemplate */
+
+/* Excluded from this release type: _SingleTemplateManager */
+
+/* Excluded from this release type: _Template */
+
+/* Excluded from this release type: _TemplateContext */
+
+/* Excluded from this release type: _TemplateFS */
+
+/* Excluded from this release type: _TemplateManager */
+
+/* Excluded from this release type: _templateManager */
+
+/* Excluded from this release type: _TemplateOutput */
+
+/* Excluded from this release type: _writeGeneratedFiles */
+
+/* Excluded from this release type: _WriteMode */
+
+export { }

package/dist/extensibility-dev-tools-workspace-alpha.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/* Excluded from this release type: _CliContext */
+
+/* Excluded from this release type: _CliUx */
+
+/* Excluded from this release type: _defaultServices */
+
+/* Excluded from this release type: _EndpointAuth */
+
+/* Excluded from this release type: _EndpointDefinition */
+
+/* Excluded from this release type: _PackageMetadata */
+
+/* Excluded from this release type: _regenAppProjectWorkspace */
+
+/* Excluded from this release type: _RegenWorkspaceOptions */
+
+/* Excluded from this release type: _regenWorkspaceOptionsSchema */
+
+/* Excluded from this release type: _resolvePackageMetadata */
+
+/* Excluded from this release type: _WorkspaceDependency */
+
+/* Excluded from this release type: _WorkspaceDependencyManager */
+
+/* Excluded from this release type: _WorkspaceExtensionConfig */
+
+/* Excluded from this release type: _WorkspaceFileWriteResult */
+
+/* Excluded from this release type: _WorkspaceFileWriterOptions */
+
+/* Excluded from this release type: _WorkspaceGeneratedFile */
+
+/* Excluded from this release type: _WorkspaceGenerateResult */
+
+/* Excluded from this release type: _WorkspaceManifest */
+
+/* Excluded from this release type: _WorkspaceOverwriteDecision */
+
+/* Excluded from this release type: _WorkspaceOverwritePromptCallback */
+
+/* Excluded from this release type: _WorkspacePendingChange */
+
+/* Excluded from this release type: _WorkspacePostGenerationHook */
+
+/* Excluded from this release type: _WorkspaceServices */
+
+/* Excluded from this release type: _WorkspaceWriteMode */
+
+export { }