@stripe/extensibility-tool-utils 0.6.2

package/dist/logging/create-logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Logger factory for extensibility tooling.
+ *
+ * @internal
+ */
+import pino from 'pino';
+import type { _LogLevel } from './levels.js';
+/**
+ * Options for creating a logger instance.
+ *
+ * @internal
+ */
+export interface _LoggerOptions {
+    /** Optional name tag included in every log record. */
+    readonly name?: string;
+    /** Log level; defaults to the LOG_LEVEL env var, falling back to 'info'. */
+    readonly level?: _LogLevel;
+}
+/**
+ * Creates a pino logger that writes to stderr with colorized pretty-print output.
+ * Stderr is used so that structured log lines do not pollute stdout-based CLI output.
+ *
+ * @param options - Optional name and level overrides.
+ * @returns A configured pino Logger instance.
+ *
+ * @internal
+ */
+export declare function _createLogger(options?: _LoggerOptions): pino.Logger;
+//# sourceMappingURL=create-logger.d.ts.map

package/dist/logging/create-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-logger.d.ts","sourceRoot":"","sources":["../../src/logging/create-logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC,MAAM,CAWnE"}

package/dist/logging/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Logging utilities for extensibility tooling.
+ *
+ * @internal
+ */
+export type { _LogLevel } from './levels.js';
+export { _parseLogLevel } from './levels.js';
+export type { _LoggerOptions } from './create-logger.js';
+export { _createLogger } from './create-logger.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/logging/levels.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Log level type and parsing utilities.
+ *
+ * @internal
+ */
+/**
+ * Valid pino log levels, including 'silent' to suppress all output.
+ *
+ * @internal
+ */
+export type _LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+/**
+ * Parses a log level string, returning 'info' for missing or unrecognized values.
+ *
+ * @param input - Raw string (e.g. from an env var). Undefined or empty returns 'info'.
+ * @returns A valid _LogLevel.
+ *
+ * @internal
+ */
+export declare function _parseLogLevel(input: string | undefined): _LogLevel;
+//# sourceMappingURL=levels.d.ts.map

package/dist/logging/levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.d.ts","sourceRoot":"","sources":["../../src/logging/levels.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,GACP,QAAQ,CAAC;AAiBb;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAKnE"}

package/dist/naming/inflection.d.ts

@@ -0,0 +1,15 @@
+/** Converts a snake_case identifier to PascalCase. @internal */
+export declare function _toPascalCase(value: string): string;
+/** Converts a PascalCase or camelCase identifier to snake_case. @internal */
+export declare function _toSnakeCase(value: string): string;
+/** Pluralizes a name using the `inflected` library. @internal */
+export declare function _toPlural(value: string): string;
+/** Singularizes a name using the `inflected` library. @internal */
+export declare function _toSingular(value: string): string;
+/** Returns whether a name appears plural according to the inflector. @internal */
+export declare function _looksPlural(value: string): boolean;
+/** Capitalizes the first character of a string, leaving the rest unchanged. @internal */
+export declare function _toCapitalized(value: string): string;
+/** Returns whether a name appears singular according to the inflector. @internal */
+export declare function _looksSingular(value: string): boolean;
+//# sourceMappingURL=inflection.d.ts.map

package/dist/naming/inflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inflection.d.ts","sourceRoot":"","sources":["../../src/naming/inflection.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/naming/metadata-policy.d.ts

@@ -0,0 +1,35 @@
+import type { MetadataInferenceContext, MetadataPluralizationContext, MetadataPolicyInput } from '@formspec/core';
+/**
+ * Infers a Stripe API name from a declaration's logical TypeScript name.
+ *
+ * FormSpec passes the unresolved declaration identifier through
+ * `logicalName`. Stripe naming policy lowers that identifier into Stripe API
+ * case so schema generation, lint rules, and future non-TypeScript
+ * implementations all share the same heuristic.
+ *
+ * @internal
+ */
+export declare function _inferStripeApiName(context: MetadataInferenceContext): string;
+/**
+ * Infers a sentence-case display name from a declaration's logical name.
+ *
+ * @internal
+ */
+export declare function inferStripeDisplayName(context: MetadataInferenceContext): string;
+/**
+ * Derives plural metadata values using the shared `inflected` inflector.
+ *
+ * @internal
+ */
+export declare function pluralizeStripeMetadata(context: MetadataPluralizationContext): string;
+/**
+ * Stripe metadata policy for FormSpec schema generation.
+ *
+ * Singular `apiName` and `displayName` values are inferred whenever they are
+ * absent. Type declarations also get inferred plural forms so custom-object
+ * and extension tooling can share the same resolved metadata contract.
+ *
+ * @internal
+ */
+export declare const _stripeMetadataPolicy: MetadataPolicyInput;
+//# sourceMappingURL=metadata-policy.d.ts.map

package/dist/naming/metadata-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-policy.d.ts","sourceRoot":"","sources":["../../src/naming/metadata-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,4BAA4B,EAC5B,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAErF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAuCnC,CAAC"}

package/dist/naming/stripe-api-case.d.ts

@@ -0,0 +1,9 @@
+/** Tokenizes an identifier into words using Stripe API case heuristics. @internal */
+export declare function _tokenizeIdentifier(input: string): string[];
+/** Converts an identifier into Stripe API case. @internal */
+export declare function _toStripeApiCase(input: string): string;
+/** Converts an identifier into a sentence-case display name. @internal */
+export declare function _toSentenceDisplayName(input: string): string;
+/** Truncates a name to a maximum length without additional normalization. @internal */
+export declare function _truncateName(value: string, maxLength: number): string;
+//# sourceMappingURL=stripe-api-case.d.ts.map

package/dist/naming/stripe-api-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe-api-case.d.ts","sourceRoot":"","sources":["../../src/naming/stripe-api-case.ts"],"names":[],"mappings":"AA4GA,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAO3D;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAuB5D;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE"}

package/dist/naming/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validation result for an inferred or explicit name.
+ * @internal
+ */
+export interface _ApiNameValidationResult {
+    /** Whether the name passes all validation rules. */
+    valid: boolean;
+    /** Human-readable messages describing each validation failure. */
+    reasons: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/naming/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/naming/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB"}

package/dist/naming/validate.d.ts

@@ -0,0 +1,6 @@
+import type { _ApiNameValidationResult } from './types.js';
+/** Validates a Stripe API name. @internal */
+export declare function _validateApiName(value: string): _ApiNameValidationResult;
+/** Validates a display name. @internal */
+export declare function _validateDisplayName(value: string): _ApiNameValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/naming/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/naming/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D,6CAA6C;AAC7C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,wBAAwB,CA6BxE;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,wBAAwB,CAa5E"}

package/dist/templates/filesystem-fs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Filesystem-backed TemplateFS implementation
+ *
+ * Creates a `_TemplateFS` that reads files from the real filesystem at runtime.
+ * Suitable for ESM tooling contexts where the templates directory is available
+ * on disk.
+ */
+import type { _TemplateFS } from './types.js';
+/**
+ * Create a TemplateFS instance rooted at the given directory.
+ *
+ * Each Mustache render call passes a per-call escape config so that no global
+ * Mustache state is mutated. Because we generate source code (not HTML), HTML
+ * escaping is intentionally disabled.
+ *
+ * @param templateDir - Root directory. Defaults to `process.cwd()`.
+ * @internal
+ */
+export declare function _createFilesystemTemplateFS(templateDir?: string): _TemplateFS;
+//# sourceMappingURL=filesystem-fs.d.ts.map

package/dist/templates/filesystem-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-fs.d.ts","sourceRoot":"","sources":["../../src/templates/filesystem-fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,GAAE,MAAsB,GAClC,WAAW,CAiBb"}

package/dist/templates/generator.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Generator abstraction for composable code generation
+ *
+ * A generator combines a `files/` directory tree of Mustache templates,
+ * a `locals()` function that computes template variables, and optional
+ * lifecycle hooks for side effects (manifest updates, config changes).
+ */
+/**
+ * Generator context for a standalone (non-project) invocation.
+ * The generator places files relative to `targetDir`.
+ * @internal
+ */
+export interface _StandaloneGeneratorContext {
+    readonly scope: 'standalone';
+    readonly targetDir: string;
+}
+/**
+ * Generator context for a project-scoped invocation.
+ * The generator places files relative to `projectRoot`.
+ * @internal
+ */
+export interface _ProjectGeneratorContext {
+    readonly scope: 'project';
+    readonly projectRoot: string;
+}
+/**
+ * Discriminated union of the two generator context shapes.
+ * @internal
+ */
+export type _GeneratorContext = _StandaloneGeneratorContext | _ProjectGeneratorContext;
+/**
+ * Capability mixin that adds `writeFiles` to an execute context.
+ * @internal
+ */
+export interface _WriteCapability {
+    /** Write generated files to disk. Provided by the caller. */
+    writeFiles(files: readonly _PlannedFile[]): Promise<_GeneratorWriteResult>;
+}
+/**
+ * Execute context for standalone generators.
+ * @internal
+ */
+export type _StandaloneExecuteContext = _StandaloneGeneratorContext & _WriteCapability;
+/**
+ * Execute context for project-scoped generators.
+ * @internal
+ */
+export type _ProjectExecuteContext = _ProjectGeneratorContext & _WriteCapability;
+/**
+ * Discriminated union of the two execute context shapes.
+ * @internal
+ */
+export type _GeneratorExecuteContext = _StandaloneExecuteContext | _ProjectExecuteContext;
+/**
+ * A single file that a generator intends to create.
+ * @internal
+ */
+export interface _PlannedFile {
+    readonly path: string;
+    readonly content: string;
+    /**
+     * Human-readable explanation of what this file is and why it is being
+     * created. Rendered from the generator's `descriptions` map using Mustache.
+     */
+    readonly description?: string;
+}
+/**
+ * Structured result returned by a `beforeExecute` hook.
+ *
+ * Returning `{ proceed: false, reason: '...', remediation: '...' }` is a
+ * normal rejection — the user should fix their input. Throwing indicates a
+ * generator defect and should be filed as a bug.
+ *
+ * The discriminated union enforces that `reason` is always present when
+ * `proceed` is `false` — `{ proceed: false }` without a reason is a type error.
+ * @internal
+ */
+export type _BeforeExecuteResult = {
+    readonly proceed: true;
+} | {
+    readonly proceed: false;
+    readonly reason: string;
+    readonly remediation?: string;
+};
+/**
+ * Structured result returned by an `afterExecute` hook.
+ * @internal
+ */
+export interface _AfterExecuteResult {
+    /** Descriptions of side effects that were performed. */
+    readonly sideEffects?: readonly string[];
+}
+/**
+ * Error detail attached to a file write outcome.
+ * @internal
+ */
+export interface _WriteError {
+    readonly kind: 'permission' | 'disk' | 'conflict' | 'unknown';
+    readonly message: string;
+}
+/**
+ * Outcome of writing a single planned file to disk.
+ * @internal
+ */
+export interface _FileWriteOutcome {
+    readonly path: string;
+    readonly decision: 'created' | 'overwritten' | 'skipped' | 'identical';
+    readonly proposedContent: string;
+    readonly previousContent?: string;
+    /**
+     * Present only when `decision` is `'skipped'` due to an error (not user choice).
+     * For permission errors, disk errors, etc. Not present on 'created', 'overwritten', or 'identical'.
+     */
+    readonly error?: _WriteError;
+}
+/**
+ * Result of writing all planned files to disk.
+ * @internal
+ */
+export interface _GeneratorWriteResult {
+    readonly fileOutcomes: readonly _FileWriteOutcome[];
+    readonly aborted: boolean;
+}
+/**
+ * Result of `_GeneratorRunner.plan()`.
+ * @internal
+ */
+export interface _GeneratorPlanResult {
+    /** Files that would be generated. */
+    readonly files: readonly _PlannedFile[];
+    /** Preflight results from all `beforeExecute` hooks. */
+    readonly preflightResults: readonly _BeforeExecuteResult[];
+    /** Descriptions of side effects that `afterExecute` hooks would perform. */
+    readonly plannedSideEffects: readonly string[];
+}
+/**
+ * Result returned by `_GeneratorRunner.execute()`.
+ * @internal
+ */
+export interface _GeneratorExecuteResult {
+    /** Files that were planned (same as plan().files). */
+    readonly files: readonly _PlannedFile[];
+    /** Preflight results from all `beforeExecute` hooks. */
+    readonly preflightResults: readonly _BeforeExecuteResult[];
+    /** Descriptions of side effects declared by generators. */
+    readonly plannedSideEffects: readonly string[];
+    /** The write result from the caller's `writeFiles` callback. Absent (undefined)
+     * if a preflight check rejected execution. */
+    readonly writeResult: _GeneratorWriteResult | undefined;
+    /** Results from all `afterExecute` hooks. */
+    readonly afterExecuteResults: readonly _AfterExecuteResult[];
+}
+/**
+ * Thrown when user-provided input is invalid.
+ *
+ * Intended for use by generator hooks (e.g., `beforeExecute` validation)
+ * and consuming code (CLI error handling). The runner itself throws
+ * `_GeneratorDefectError` for structural issues.
+ *
+ * Callers should display the message and `remediation` to the user.
+ * @internal
+ */
+export declare class _GeneratorInputError extends Error {
+    readonly remediation: string | undefined;
+    constructor(message: string, remediation?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the generator itself is malformed.
+ *
+ * This indicates a bug in the generator implementation that should be filed
+ * and fixed by the generator author.
+ * @internal
+ */
+export declare class _GeneratorDefectError extends Error {
+    readonly generatorId: string | undefined;
+    constructor(message: string, generatorId?: string, options?: ErrorOptions);
+}
+/**
+ * A composable unit of code generation.
+ *
+ * A generator combines:
+ * - A `files/` directory tree of Mustache templates that mirrors the output structure
+ * - A `locals()` function that computes template variables from user params
+ * - Optional lifecycle hooks for side effects (manifest updates, config changes)
+ *
+ * @typeParam TParams - User-provided parameters for this generator
+ * @internal
+ */
+export interface _Generator<TParams extends object> {
+    /**
+     * Compute template variables from user-provided params.
+     *
+     * The returned record serves as the variable scope for both:
+     * - `___token___` resolution in file/directory names (structural placement)
+     * - `{{token}}` Mustache rendering in .mustache file content
+     *
+     * Params are the raw user inputs. Locals are the transformed, computed
+     * fields derived from params (e.g., PascalCase, snake_case, pluralized
+     * forms, default values). All template surfaces consume from locals.
+     *
+     * Path tokens (`___token___`) must resolve to strings.
+     * Content tokens (`{{token}}`) may be any Mustache-compatible value.
+     */
+    locals(params: TParams): Record<string, unknown>;
+    /**
+     * Root directory of this generator (parent of the `files/` subdirectory).
+     * The runner will look for templates under `<filesDir>/files/`.
+     */
+    readonly filesDir: string;
+    /**
+     * Map of template-relative file paths to human-readable descriptions.
+     *
+     * Keys are the literal filename in the `files/` tree (with `___token___`
+     * intact, e.g., `'___objectName___.object.ts.mustache'`). Values may use
+     * Mustache `{{token}}` syntax and are rendered with the generator's locals.
+     *
+     * Example:
+     * ```typescript
+     * descriptions: {
+     *   '___objectName___.object.ts.mustache': 'Defines the {{className}} custom object',
+     * }
+     * ```
+     */
+    readonly descriptions?: Readonly<Record<string, string>>;
+    /**
+     * Run before files are generated (e.g., validate preconditions).
+     *
+     * Return `{ proceed: false, reason: '...', remediation: '...' }` to reject
+     * execution with user-actionable guidance.
+     *
+     * **Throwing** indicates a generator defect, not a user input problem.
+     */
+    beforeExecute?(params: TParams, context: _GeneratorContext): Promise<_BeforeExecuteResult>;
+    /**
+     * Run after files are written (e.g., update manifest, install deps).
+     *
+     * Returns a structured description of side effects performed.
+     *
+     * Note: if `afterExecute` throws, files have already been written to disk.
+     * The error propagates to the caller. Callers should handle this as a
+     * partial-completion scenario.
+     */
+    afterExecute?(params: TParams, context: _GeneratorContext, writeResult: _GeneratorWriteResult): Promise<_AfterExecuteResult>;
+    /**
+     * Return descriptions of side effects that `afterExecute` would perform,
+     * parameterized by the current params. Used for dry-run output.
+     *
+     * Returns a promise so future generators can inspect the filesystem to
+     * produce accurate descriptions.
+     */
+    describeSideEffects?(params: TParams): Promise<readonly string[]>;
+}
+/**
+ * Executes a single `_Generator` (or composite of generators), producing file
+ * outputs and running lifecycle hooks.
+ *
+ * Does NOT write files to disk — that responsibility belongs to the caller.
+ *
+ * @typeParam TParams - User-provided parameters type
+ * @internal
+ */
+export declare class _GeneratorRunner<TParams extends object> {
+    #private;
+    constructor(generator: _Generator<TParams> | ReadonlyArray<_Generator<TParams>>);
+    /**
+     * Plan phase — compute all files that would be generated, without writing
+     * anything to disk.
+     *
+     * Also runs `beforeExecute` hooks to collect preflight results, and
+     * `describeSideEffects` to surface planned side effects. Neither of these
+     * write anything or produce observable external effects during plan.
+     *
+     * Use this for dry runs, previews, and testing.
+     *
+     * Validates that all output paths are safe (no `..`, no leading `/`) and
+     * that no two generators produce the same output path.
+     *
+     * @param params - User-provided parameters for the generator
+     * @param context - Generator context (standalone or project). Passed to
+     *   `beforeExecute` hooks. Callers must supply a real context — there is no
+     *   synthetic plan-time sentinel. For dry-run calls outside of a project,
+     *   use a standalone context with an appropriate `targetDir`.
+     */
+    plan(params: TParams, context: _GeneratorContext): Promise<_GeneratorPlanResult>;
+    /**
+     * Execute phase — runs the full lifecycle:
+     * 1. `plan()` to collect preflight results and planned files
+     * 2. If any preflight returned `proceed: false`, return early without writing
+     * 3. `context.writeFiles()` to write files to disk (delegated to caller)
+     * 4. If the write was aborted, return early without calling `afterExecute`
+     * 5. `afterExecute` hooks for all generators with the write result
+     */
+    execute(params: TParams, context: _GeneratorExecuteContext): Promise<_GeneratorExecuteResult>;
+}
+/**
+ * Compose multiple generators with the same params into a single runner.
+ *
+ * The composite runner merges all file outputs and runs all lifecycle hooks
+ * in declaration order.
+ *
+ * @typeParam TParams - Shared user-provided parameters type
+ * @internal
+ */
+export declare function _compositeGenerator<TParams extends object>(...generators: ReadonlyArray<_Generator<TParams>>): _GeneratorRunner<TParams>;
+//# sourceMappingURL=generator.d.ts.map

package/dist/templates/generator.d.ts.map

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

package/dist/templates/in-memory-fs.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-memory TemplateFS implementation
+ *
+ * Provides template access from an in-memory image instead of the filesystem.
+ * This enables bundled contexts (like pkg) to use templates without runtime
+ * filesystem access.
+ */
+import type { _TemplateFS } from './types.js';
+/**
+ * Template entry in the in-memory registry
+ * @internal
+ */
+export interface _TemplateFSImageEntry {
+    path: string;
+    content: string;
+}
+/**
+ * Extended TemplateFS with directory scanning helpers
+ * @internal
+ */
+export interface _InMemoryTemplateFS extends _TemplateFS {
+    /**
+     * Get all template paths under a given directory prefix
+     * @internal - For future directory scanning support
+     */
+    _getPathsUnder(prefix: string): string[];
+}
+/**
+ * Create an in-memory TemplateFS instance
+ *
+ * Caller must provide exact paths including any base path prefix.
+ * For example, to read "extensions/common/tsconfig.json", pass:
+ *   fs.textFile('extensions', 'common', 'tsconfig.json')
+ *
+ * Or use scope() to create a scoped instance:
+ *   fs.scope('extensions').textFile('common', 'tsconfig.json')
+ *
+ * @param image - Array of template entries with path and content
+ * @param pathPrefix - Optional path prefix to prepend to all operations
+ * @returns TemplateFS instance that reads from in-memory image
+ * @internal
+ */
+export declare function _createInMemoryTemplateFS(image: _TemplateFSImageEntry[], pathPrefix?: string): _InMemoryTemplateFS;
+//# sourceMappingURL=in-memory-fs.d.ts.map

package/dist/templates/in-memory-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-fs.d.ts","sourceRoot":"","sources":["../../src/templates/in-memory-fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,qBAAqB,EAAE,EAC9B,UAAU,GAAE,MAAW,GACtB,mBAAmB,CA8CrB"}

package/dist/templates/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Template System Core
+ *
+ * Generic, type-safe template system for code generation.
+ * Provides core types, managers, and in-memory filesystem abstraction.
+ *
+ * Higher-level concerns (file writing, diff viewing, overwrite prompting)
+ * remain in `@stripe/extensibility-dev-tools`.
+ *
+ * @internal
+ */
+/** @internal */
+export type { _GeneratedFile, _TemplateOutput, _TemplateFS, _TemplateContext, _Template, } from './types.js';
+/** @internal */
+export { _TemplateManager } from './template-manager.js';
+/** @internal */
+export { _createSimpleTemplate, _SingleTemplateManager, _createSimpleSingleFileTemplate, } from './simple-templates.js';
+/** @internal */
+export { _createInMemoryTemplateFS } from './in-memory-fs.js';
+/** @internal */
+export type { _TemplateFSImageEntry, _InMemoryTemplateFS } from './in-memory-fs.js';
+/** @internal */
+export { _createFilesystemTemplateFS } from './filesystem-fs.js';
+/** @internal */
+export { _GeneratorRunner, _compositeGenerator, _GeneratorInputError, _GeneratorDefectError, } from './generator.js';
+/** @internal */
+export type { _Generator, _GeneratorContext, _StandaloneGeneratorContext, _ProjectGeneratorContext, _WriteCapability, _StandaloneExecuteContext, _ProjectExecuteContext, _GeneratorExecuteContext, _PlannedFile, _BeforeExecuteResult, _AfterExecuteResult, _WriteError, _FileWriteOutcome, _GeneratorWriteResult, _GeneratorPlanResult, _GeneratorExecuteResult, } from './generator.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,gBAAgB;AAChB,YAAY,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,gBAAgB;AAChB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,gBAAgB;AAChB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,uBAAuB,CAAC;AAG/B,gBAAgB;AAChB,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,gBAAgB;AAChB,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,gBAAgB;AAChB,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAGjE,gBAAgB;AAChB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,gBAAgB;AAChB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,2BAA2B,EAC3B,wBAAwB,EACxB,gBAAgB,EAChB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC"}