@stripe/extensibility-tool-utils 0.6.2

package/dist/extensibility-tool-utils-internal.d.ts

@@ -0,0 +1,1866 @@
+/**
+ * `@stripe/extensibility-tool-utils`
+ *
+ * Internal standalone utilities shared across Stripe extensibility tooling.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { MetadataInferenceContext } from '@formspec/core';
+import type { MetadataPolicyInput } from '@formspec/core';
+import pino from 'pino';
+
+/**
+ * Branded string types with validating smart constructors.
+ *
+ * Brands use symbol keys so they do not appear in IDE autocomplete
+ * (per project convention).
+ */
+declare const __semverRangeBrand: unique symbol;
+
+/** A well-formed semver version string (e.g. `"1.2.3"`, `"4.0.0-rc.1"`). */
+declare const __semverVersionBrand: unique symbol;
+
+/**
+ * Structured result returned by an `afterExecute` hook.
+ * @internal
+ */
+export declare interface _AfterExecuteResult {
+    /** Descriptions of side effects that were performed. */
+    readonly sideEffects?: readonly string[];
+}
+
+/** @internal */
+export declare interface _ApiExtractorConfig {
+    readonly projectFolder?: string;
+    readonly mainEntryPointFilePath?: string;
+    readonly apiReport?: {
+        readonly enabled?: boolean;
+        readonly reportFileName?: string;
+        readonly reportFolder?: string;
+    };
+    readonly dtsRollup?: {
+        readonly enabled?: boolean;
+        readonly publicTrimmedFilePath?: string;
+        readonly untrimmedFilePath?: string;
+    };
+}
+
+/** @internal */
+export declare class _ApiExtractorDoc extends _Document<_ApiExtractorConfig> {
+    setMainEntryPoint(path: string, opts?: _MutationOptions<_ApiExtractorConfig>): this;
+    enableApiReport(folder: string, fileName: string, opts?: _MutationOptions<_ApiExtractorConfig>): this;
+    enableDtsRollup(publicPath: string, opts?: _MutationOptions<_ApiExtractorConfig>): this;
+}
+
+/**
+ * Validation result for an inferred or explicit name.
+ * @internal
+ */
+export declare interface _ApiNameValidationResult {
+    /** Whether the name passes all validation rules. */
+    valid: boolean;
+    /** Human-readable messages describing each validation failure. */
+    reasons: string[];
+}
+
+/** A read-only predicate over a document-shaped value. @internal */
+export declare type _Assertion = (ctx: _AssertionContext) => _Diagnostic[];
+
+/** Context handed to each assertion. @internal */
+export declare interface _AssertionContext {
+    readonly path: string;
+    readonly value: unknown;
+}
+
+/** A required value failed an assertion check. */
+/** @internal */
+export declare class _AssertionError extends _FileEditorError {
+    readonly pointer: _JsonPointer;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    constructor(pointer: _JsonPointer, message: string, details?: {
+        actual?: unknown;
+        expected?: unknown;
+    });
+}
+
+/** @internal */
+export declare interface _AssertOpts {
+    readonly severity?: _Severity;
+    readonly message?: string;
+}
+
+/** An assertion that defers to an async validator (e.g. a Standard Schema). @internal */
+export declare type _AsyncAssertion = (ctx: _AssertionContext) => Promise<_Diagnostic[]>;
+
+/**
+ * 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 declare type _BeforeExecuteResult = {
+    readonly proceed: false;
+    readonly reason: string;
+    readonly remediation?: string;
+} | { readonly proceed: true };
+
+/** Begin a new transaction. */
+/** @internal */
+export declare function _beginTransaction(options?: _TransactionOptions): _Transaction;
+
+/**
+ * Produce a canonical, deterministic string form of the document's *semantic*
+ * content. Two documents with identical semantics produce identical canonical
+ * strings regardless of formatting or comments.
+ */
+/** @internal */
+export declare function _canonicalNormalize(text: string, format: _Format): string;
+
+/**
+ * Deterministic stringification of a plain-JSON value.
+ *
+ * Rules:
+ * - Object keys sorted ascending by UTF-16 code unit.
+ * - Strings Unicode NFC-normalized and emitted as JSON strings.
+ * - Numbers: finite → canonical form (JSON.stringify); NaN/Infinity reject.
+ * - Arrays preserve element order (order is semantic).
+ * - `undefined` anywhere in an object drops the key (matches JSON semantics);
+ *   inside an array it serializes as `null`.
+ */
+/** @internal */
+export declare function _canonicalStringify(value: unknown): string;
+
+/**
+ * Read-only predicate factories that produce {@link _Assertion}s and
+ * {@link _AsyncAssertion}s. Compose via {@link _Document.assert}.
+ * @internal
+ */
+export declare const _check: {
+    readonly equals: (pointer: _JsonPointer, expected: unknown, opts?: _AssertOpts) => _Assertion;
+    readonly exists: (pointer: _JsonPointer, opts?: _AssertOpts) => _Assertion;
+    readonly matches: (pointer: _JsonPointer, pattern: RegExp, opts?: _AssertOpts) => _Assertion;
+    readonly matchesSchema: (pointer: _JsonPointer, schema: _StandardSchemaV1, opts?: _AssertOpts) => _AsyncAssertion;
+    readonly oneOf: (pointer: _JsonPointer, allowed: readonly unknown[], opts?: _AssertOpts) => _Assertion;
+    readonly satisfies: (pointer: _JsonPointer, predicate: (v: unknown) => boolean, opts?: _AssertOpts) => _Assertion;
+    readonly semverSatisfies: (pointer: _JsonPointer, range: string, opts?: _AssertOpts) => _Assertion;
+};
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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 supplied at {@link _Transaction.commit} time. */
+/** @internal */
+export declare interface _CommitOptions {
+    readonly defaultPolicy?: _ConflictPolicy;
+}
+
+/** Full report of a (dry-run or actual) commit. */
+/** @internal */
+export declare interface _CommitReport {
+    readonly written: readonly {
+        readonly bytesAfter: number;
+        readonly bytesBefore: number;
+        readonly path: string;
+        readonly unifiedDiff: string;
+    }[];
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly reason: 'conflict-skipped' | 'no-change' | 'schema-invalid' | 'write-skipped';
+    }[];
+    readonly conflicts: readonly _Conflict[];
+    readonly diagnostics: readonly _Diagnostic[];
+}
+
+/** Compile an array of raw (unescaped) tokens into a JSON Pointer string. */
+/** @internal */
+export declare function _compilePointer(segments: readonly (number | string)[]): _JsonPointer;
+
+/**
+ * Key of {@link _CompilerOptions}. Method signatures use
+ * `<K extends _CompilerOptionKey>(name: K, value: _CompilerOptions[K])`
+ * so the value type is narrowed by the key.
+ */
+/** @internal */
+export declare type _CompilerOptionKey = keyof _CompilerOptions;
+
+/** Typed subset of `compilerOptions`. Unknown keys can still be set via the generic API. */
+/** @internal */
+export declare interface _CompilerOptions {
+    readonly target?: _TsTarget;
+    readonly module?: _TsModule;
+    readonly moduleResolution?: _TsModuleResolution;
+    readonly lib?: readonly string[];
+    readonly types?: readonly string[];
+    readonly jsx?: _TsJsx;
+    readonly jsxImportSource?: string;
+    readonly strict?: boolean;
+    readonly noImplicitAny?: boolean;
+    readonly strictNullChecks?: boolean;
+    readonly strictFunctionTypes?: boolean;
+    readonly strictBindCallApply?: boolean;
+    readonly strictPropertyInitialization?: boolean;
+    readonly alwaysStrict?: boolean;
+    readonly noImplicitThis?: boolean;
+    readonly noUncheckedIndexedAccess?: boolean;
+    readonly noImplicitOverride?: boolean;
+    readonly noPropertyAccessFromIndexSignature?: boolean;
+    readonly exactOptionalPropertyTypes?: boolean;
+    readonly noFallthroughCasesInSwitch?: boolean;
+    readonly noImplicitReturns?: boolean;
+    readonly noUnusedLocals?: boolean;
+    readonly noUnusedParameters?: boolean;
+    readonly useUnknownInCatchVariables?: boolean;
+    readonly outDir?: string;
+    readonly rootDir?: string;
+    readonly declaration?: boolean;
+    readonly declarationMap?: boolean;
+    readonly declarationDir?: string;
+    readonly sourceMap?: boolean;
+    readonly inlineSources?: boolean;
+    readonly noEmit?: boolean;
+    readonly noEmitOnError?: boolean;
+    readonly removeComments?: boolean;
+    readonly importHelpers?: boolean;
+    readonly downlevelIteration?: boolean;
+    readonly esModuleInterop?: boolean;
+    readonly allowSyntheticDefaultImports?: boolean;
+    readonly forceConsistentCasingInFileNames?: boolean;
+    readonly isolatedModules?: boolean;
+    readonly verbatimModuleSyntax?: boolean;
+    readonly resolveJsonModule?: boolean;
+    readonly skipLibCheck?: boolean;
+    readonly baseUrl?: string;
+    readonly paths?: Readonly<Record<string, readonly string[]>>;
+    readonly composite?: boolean;
+    readonly incremental?: boolean;
+    readonly tsBuildInfoFile?: string;
+}
+
+/** Defined (non-undefined) value type at a given key. */
+/** @internal */
+export declare type _CompilerOptionValue<K extends _CompilerOptionKey> = NonNullable<_CompilerOptions[K]>;
+
+/**
+ * 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>;
+
+/** When the `confirmWrite` hook should be invoked. */
+/** @internal */
+export declare type _ConfirmationPolicy = 'always' | 'never' | 'on-conflict';
+
+/** Describes a detected drift event. */
+/** @internal */
+export declare interface _Conflict {
+    readonly path: string;
+    /** Text the library intended to write. */
+    readonly ours: string;
+    /** Current on-disk text. */
+    readonly theirs: string;
+    /** Text at last recorded write, if retained. */
+    readonly base: null | string;
+    readonly lastWriteAt: null | string;
+    readonly lastWriteTool: null | string;
+}
+
+/** Resolver or confirmWrite returned "abort". */
+/** @internal */
+export declare class _ConflictAbortedError extends _FileEditorError {
+    readonly path: string;
+    constructor(path: string);
+}
+
+/** Drift detected and policy was "error". */
+/** @internal */
+export declare class _ConflictError extends _FileEditorError {
+    readonly conflict: _Conflict;
+    constructor(conflict: _Conflict);
+}
+
+/** Policy for handling on-disk drift at commit time. */
+/** @internal */
+export declare type _ConflictPolicy = 'ask' | 'error' | 'overwrite' | 'skip';
+
+/** Result of resolving a conflict. */
+/** @internal */
+export declare type _ConflictResolution = 'abort' | 'overwrite' | 'skip';
+
+/** @internal */
+export declare type _ConflictResolver = (c: _Conflict) => Promise<_ConflictResolution>;
+
+/**
+ * Create a `_CliContext` with default or injected collaborators.
+ *
+ * @param options - Optional options. Pass a pre-constructed `_CliUx` to redirect output
+ *   streams (e.g., for testing or RPC transports that must not write to stdout).
+ * @internal
+ */
+export declare function _createCliContext(options?: { ux?: _CliUx }): _CliContext;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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>;
+
+/** Default format metadata used when no source text exists yet. */
+/** @internal */
+export declare function _defaultMeta(): _FormatMeta;
+
+/** @internal */
+export declare type _DepKind = 'dependencies' | 'devDependencies' | 'optionalDependencies' | 'peerDependencies';
+
+/**
+ * Infer a {@link _Format} for a path, optionally using the file's text to
+ * disambiguate. Falls back to a {@link _FormatNotSupportedError} if no
+ * reasonable inference is possible.
+ */
+/** @internal */
+export declare function _detectFormat(path: string, text?: string): _Format;
+
+/** Detect indentation, EOL style, BOM, and final-newline from source text. */
+/** @internal */
+export declare function _detectMeta(text: string): _FormatMeta;
+
+/** A single finding produced by an assertion or commit flow. */
+/** @internal */
+export declare interface _Diagnostic {
+    readonly path: string;
+    readonly pointer: _JsonPointer;
+    readonly code: string;
+    readonly severity: _Severity;
+    readonly message: string;
+    readonly expected?: unknown;
+    readonly actual?: unknown;
+}
+
+/** Structured representation of a unified-diff hunk. */
+/** @internal */
+export declare interface _DiffHunk {
+    readonly oldStart: number;
+    readonly oldLines: number;
+    readonly newStart: number;
+    readonly newLines: number;
+    readonly lines: readonly _DiffLine[];
+}
+
+/** Produce structured diff _hunks (for custom TUI rendering). */
+/** @internal */
+export declare function _diffHunks(a: string, b: string, opts?: _DiffOptions): _DiffHunk[];
+
+/** A single diff line within a hunk. */
+/** @internal */
+export declare interface _DiffLine {
+    readonly kind: 'add' | 'context' | 'del';
+    readonly text: string;
+    readonly oldLineNo: null | number;
+    readonly newLineNo: null | number;
+}
+
+/** @internal */
+export declare interface _DiffOptions {
+    /** Number of context lines to include around each hunk. Default: 3. */
+    readonly context?: number;
+    readonly fileNameA?: string;
+    readonly fileNameB?: string;
+}
+
+/** Produce a _unified-diff string (`--- a / +++ b` headers and `@@` _hunks). */
+/** @internal */
+export declare function _diffUnified(a: string, b: string, opts?: _DiffOptions): string;
+
+/**
+ * A parsed, editable document. Mutations are staged in memory and applied to
+ * the source text on demand (see {@link _Document.preview}).
+ *
+ * `T` is the *expected* shape of the document's root value. When `T` is
+ * `unknown` (the default), mutation signatures collapse to accept any value,
+ * so the class is usable schema-free. When `T` is a concrete interface,
+ * `get`/`set`/`addIfMissing`/etc. narrow both the pointer and the value
+ * type via {@link _ValueAtPointer}.
+ */
+/** @internal */
+export declare class _Document<T = unknown> {
+    readonly absolutePath: string;
+    readonly format: _Format;
+    /** Optional Standard Schema; when set, {@link _Document.validate} runs it. */
+    readonly schema: _StandardSchemaV1<T> | null;
+    /** Original on-disk text (may be `""` for new files). */
+    private readonly originalText;
+    private readonly meta;
+    private readonly edits;
+    private readonly staticDiagnostics;
+    constructor(init: {
+        readonly absolutePath: string;
+        readonly format: _Format;
+        readonly meta: _FormatMeta;
+        readonly originalText: string;
+        readonly schema?: _StandardSchemaV1<T> | null;
+    });
+    /** Get the value at a pointer. Reflects pending edits via `preview()`. */
+    get<P extends _JsonPointer>(pointer: P): _NarrowedValue<T, P> | undefined;
+    /** Like `get` but throws {@link _AssertionError} on miss. */
+    getRequired<P extends _JsonPointer>(pointer: P): _NarrowedValue<T, P>;
+    has(pointer: _JsonPointer): boolean;
+    set<P extends _JsonPointer>(pointer: P, value: _NarrowedValue<T, P>, opts?: _MutationOptions<T>): this;
+    addIfMissing<P extends _JsonPointer>(pointer: P, value: _NarrowedValue<T, P>, opts?: _MutationOptions<T>): this;
+    updateIfPresent<P extends _JsonPointer>(pointer: P, updater: (current: _NarrowedValue<T, P>) => _NarrowedValue<T, P>, opts?: _MutationOptions<T>): this;
+    remove(pointer: _JsonPointer, opts?: _MutationOptions<T>): this;
+    merge<P extends _JsonPointer>(pointer: P, partial: _NarrowedPartial<T, P>, opts?: _MutationOptions<T> & { mergeOptions?: _MergeOptions }): this;
+    arrayAppend<P extends _JsonPointer>(pointer: P, value: _NarrowedElement<T, P>, opts?: _MutationOptions<T>): this;
+    arrayUpsert<P extends _JsonPointer, E = _NarrowedElement<T, P>>(pointer: P, value: E, keyFn: (el: E) => unknown, opts?: _MutationOptions<T>): this;
+    assert(...checks: readonly _Assertion[]): _Diagnostic[];
+    /**
+     * If a schema is configured, validate the current preview against it and
+     * return a diagnostic per issue. Returns `[]` when no schema is set or
+     * validation passes.
+     *
+     * Each call replaces any previously accumulated `SCHEMA_VIOLATION` diagnostics
+     * so that calling `validate()` multiple times does not duplicate findings.
+     */
+    validate(): Promise<_Diagnostic[]>;
+    diagnostics(): readonly _Diagnostic[];
+    pendingEdits(): readonly _PendingEdit[];
+    /** Serialize with all pending edits applied. Pure — no disk I/O. */
+    preview(): string;
+    /** Reset all pending edits. Used by transactions on rollback. */
+    rollback(): void;
+    /** @internal Metadata for transaction serialization. */
+    getMeta(): _FormatMeta;
+    /** @internal Original text, for transaction fingerprinting. */
+    getOriginalText(): string;
+    private parseCurrentValue;
+    private stage;
+    private opts;
+}
+
+/** Escape a raw string into its JSON Pointer reference-token form. */
+/** @internal */
+export declare function _escapeToken(raw: string): string;
+
+/** Base class for all errors raised by this library. */
+/** @internal */
+export declare class _FileEditorError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
+/**
+ * Outcome of writing a single planned file to disk.
+ * @internal
+ */
+export declare interface _FileWriteOutcome {
+    readonly path: string;
+    readonly decision: 'created' | 'identical' | 'overwritten' | 'skipped';
+    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;
+}
+
+/** SHA-256 hex digest of the canonical-normalized form. */
+/** @internal */
+export declare function _fingerprint(text: string, format: _Format): string;
+
+/**
+ * Shared types for the structured config editor.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6901 — JSON Pointer
+ */
+/** Supported document formats. */
+/** @internal */
+export declare type _Format = 'json' | 'jsonc' | 'yaml';
+
+/**
+ * A format adapter knows how to parse a textual document, apply pending edits
+ * to that text while preserving formatting, and compute a canonical form for
+ * fingerprinting.
+ */
+/** @internal */
+export declare interface _FormatAdapter {
+    readonly format: _Format;
+    readonly permitsComments: boolean;
+    /** Parse text; throws {@link _ParseError} on failure. */
+    parse(text: string): {
+        meta: _FormatMeta;
+        value: unknown;
+    };
+    /**
+     * Apply edits to the source text and return the updated text.
+     * Must preserve all formatting (indent/EOL/BOM/comments) except at the
+     * precise locations touched by each edit.
+     */
+    applyEdits(text: string, edits: readonly _PendingEdit[], meta: _FormatMeta): string;
+}
+
+/** Format-specific metadata discovered while parsing. */
+/** @internal */
+export declare interface _FormatMeta {
+    readonly indent: string;
+    readonly eol: '\n' | '\r\n';
+    readonly hasFinalNewline: boolean;
+    readonly hasBom: boolean;
+}
+
+/** Unknown file extension with no format override. */
+/** @internal */
+export declare class _FormatNotSupportedError extends _FileEditorError {
+    readonly path: string;
+    constructor(path: string, message?: string);
+}
+
+/** Filesystem-backed manifest store. Safe for concurrent reads; single-writer. */
+/** @internal */
+export declare function _FsCentralManifestStore(options?: _FsCentralManifestStoreOptions): _StateStore;
+
+/** @internal */
+export declare interface _FsCentralManifestStoreOptions {
+    /** Root directory under which relative keys are computed. Default: `process.cwd()`. */
+    readonly rootDir?: string;
+    /** Manifest filename relative to `rootDir`. Default: `.file-editor/state.json`. */
+    readonly filename?: string;
+    /**
+     * If true, the manifest retains the full text of each managed file as of
+     * its last write, enabling three-way diffing via `_Conflict.base`.
+     * Off by default to limit disk usage.
+     */
+    readonly keepBaseSnapshots?: boolean;
+}
+
+/**
+ * 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 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 declare 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[]>;
+}
+
+/**
+ * Discriminated union of the two generator context shapes.
+ * @internal
+ */
+export declare type _GeneratorContext = _ProjectGeneratorContext | _StandaloneGeneratorContext;
+
+/**
+ * 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);
+}
+
+/**
+ * Discriminated union of the two execute context shapes.
+ * @internal
+ */
+export declare type _GeneratorExecuteContext = _ProjectExecuteContext | _StandaloneExecuteContext;
+
+/**
+ * Result returned by `_GeneratorRunner.execute()`.
+ * @internal
+ */
+export declare 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);
+}
+
+/**
+ * Result of `_GeneratorRunner.plan()`.
+ * @internal
+ */
+export declare 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[];
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Result of writing all planned files to disk.
+ * @internal
+ */
+export declare interface _GeneratorWriteResult {
+    readonly fileOutcomes: readonly _FileWriteOutcome[];
+    readonly aborted: boolean;
+}
+
+/** Look up the adapter for a format. Built-ins always resolve. @internal */
+export declare function _getAdapter(format: _Format): _FormatAdapter;
+
+/** Returns `true` iff a pointer resolves to a value (including `null`) in the given root. */
+/** @internal */
+export declare function _hasPointer(root: unknown, pointer: _JsonPointer): boolean;
+
+/**
+ * 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;
+
+/** Process-local, non-persistent state store. Useful for tests and dry-runs. */
+/** @internal */
+export declare function _InMemoryStateStore(): _StateStore;
+
+/**
+ * Extended TemplateFS with directory scanning helpers
+ * @internal
+ */
+export declare interface _InMemoryTemplateFS extends _TemplateFS {
+    /**
+     * Get all template paths under a given directory prefix
+     * @internal - For future directory scanning support
+     */
+    _getPathsUnder(prefix: string): string[];
+}
+
+/**
+ * Reusable type guards for CLI argument validation.
+ *
+ * @internal
+ */
+/**
+ * Returns `true` if `value` is a non-null, non-array object.
+ * @internal
+ */
+export declare function _isRecord(value: unknown): value is Record<string, unknown>;
+
+/**
+ * Higher-order type guard that checks every value in a record satisfies a
+ * predicate.
+ *
+ * @example
+ * ```ts
+ * const isStringRecord = _isRecordWithValueType(
+ *   (v): v is string => typeof v === 'string'
+ * );
+ * ```
+ * @internal
+ */
+export declare function _isRecordWithValueType<T>(guard: (v: unknown) => v is T): (value: unknown) => value is Record<string, T>;
+
+/** Runtime type guard. */
+/** @internal */
+export declare function _isSemverRange(input: unknown): input is _SemverRange;
+
+/** Runtime type guard. */
+/** @internal */
+export declare function _isSemverVersion(input: unknown): input is _SemverVersion;
+
+/**
+ * `true` iff `T` is exactly `unknown` (not `any`, not `never`).
+ * @internal
+ */
+export declare type _IsUnknown<T> = unknown extends T ? [T] extends [null | undefined] ? false : T extends unknown ? [unknown] extends [T] ? true : false : false : false;
+
+/** @internal */
+export declare const _jsonAdapter: _FormatAdapter;
+
+/** @internal */
+export declare const _jsoncAdapter: _FormatAdapter;
+
+/**
+ * A JSON Pointer string as defined by RFC 6901.
+ *
+ * Examples: `""` (whole doc), `"/dependencies/lodash"`,
+ * `"/compilerOptions/paths/@scope~1pkg/0"`.
+ */
+/** @internal */
+export declare type _JsonPointer = string;
+
+/**
+ * Options for creating a logger instance.
+ *
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Log level type and parsing utilities.
+ *
+ * @internal
+ */
+/**
+ * Valid pino log levels, including 'silent' to suppress all output.
+ *
+ * @internal
+ */
+export declare type _LogLevel = 'debug' | 'error' | 'fatal' | 'info' | 'silent' | 'trace' | 'warn';
+
+/** Returns whether a name appears plural according to the inflector. @internal */
+export declare function _looksPlural(value: string): boolean;
+
+/** Returns whether a name appears singular according to the inflector. @internal */
+export declare function _looksSingular(value: string): boolean;
+
+/** Merge-operation options. */
+/** @internal */
+export declare interface _MergeOptions {
+    /** Array merge strategy. Default: `"replace"`. */
+    readonly arrays?: 'concat' | 'concatUnique' | 'replace';
+    /** Whether to recurse into nested objects. Default: `true`. */
+    readonly deep?: boolean;
+}
+
+/** Per-mutation overrides. */
+/** @internal */
+export declare interface _MutationOptions<T = unknown> {
+    readonly conflictPolicy?: _ConflictPolicy;
+    readonly guard?: (doc: _Document<T>) => boolean;
+}
+
+/** @internal */
+export declare type _NarrowedElement<T, P extends string> = string extends P ? unknown : _ValueAtPointer<T, P> extends readonly (infer E)[] ? E : unknown;
+
+/** @internal */
+export declare type _NarrowedPartial<T, P extends string> = string extends P ? object : object & Partial<_ValueAtPointer<T, P>>;
+
+/**
+ * Narrow `_ValueAtPointer<T, P>` only when `P` is a string literal. When `P`
+ * widens to `string` (e.g. a computed pointer) the type collapses to
+ * `unknown` so callers keep the freedom they had before.
+ * @internal
+ */
+export declare type _NarrowedValue<T, P extends string> = string extends P ? unknown : _ValueAtPointer<T, P>;
+
+/** @internal */
+export declare function _openApiExtractor(absolutePath: string, options?: {
+    format?: 'json' | 'jsonc';
+    schema?: _StandardSchemaV1;
+}): Promise<_ApiExtractorDoc>;
+
+/** One-off open helper. Use a {@link _Transaction} for multi-file work. */
+/** @internal */
+export declare function _openDocument(absolutePath: string, options?: _TransactionOptions): Promise<_Document>;
+
+/**
+ * Open a document from disk. For non-existent files, returns an empty
+ * document whose `format` is inferred from the path (or `options.format`).
+ */
+/** @internal */
+export declare function _openDocumentFromDisk<T = unknown>(absolutePath: string, options?: _OpenDocumentOptions<T>): Promise<_Document<T>>;
+
+/** Options passed when opening a document directly. */
+/** @internal */
+export declare interface _OpenDocumentOptions<T = unknown> {
+    readonly format?: _Format;
+    /** Optional schema for runtime validation (any Standard Schema). */
+    readonly schema?: _StandardSchemaV1<T>;
+}
+
+/**
+ * Open a package.json file and return a typed façade.
+ *
+ * The `schema` option accepts any Standard Schema-compliant validator
+ * (Zod v4, Valibot, ArkType, Effect Schema, …). It is not constrained to
+ * `_StandardSchemaV1<_PackageJson>` because schema libraries typically emit
+ * `string | undefined` for optional fields, which does not match exact
+ * optional-property-typed interfaces structurally.
+ */
+/** @internal */
+export declare function _openPackageJson(absolutePath: string, options?: {
+    format?: 'json';
+    schema?: _StandardSchemaV1;
+}): Promise<_PackageJsonDoc>;
+
+/** @internal */
+export declare function _openStripeAppManifest(absolutePath: string, options?: {
+    format?: 'json' | 'jsonc' | 'yaml';
+    schema?: _StandardSchemaV1;
+}): Promise<_StripeAppManifestDoc>;
+
+/** @internal */
+export declare function _openTsConfig(absolutePath: string, options?: {
+    format?: 'json' | 'jsonc';
+    schema?: _StandardSchemaV1;
+}): Promise<_TsConfigDoc>;
+
+/** @internal */
+export declare interface _PackageJson {
+    readonly name?: string;
+    readonly version?: _SemverVersion | string;
+    readonly scripts?: Readonly<Record<string, string>>;
+    readonly dependencies?: Readonly<Record<string, _SemverRange | string>>;
+    readonly devDependencies?: Readonly<Record<string, _SemverRange | string>>;
+    readonly peerDependencies?: Readonly<Record<string, _SemverRange | string>>;
+    readonly optionalDependencies?: Readonly<Record<string, _SemverRange | string>>;
+    readonly engines?: Readonly<Record<string, _SemverRange | string>>;
+}
+
+/** _Document subclass with typed package.json helpers. */
+/** @internal */
+export declare class _PackageJsonDoc extends _Document<_PackageJson> {
+    setScript(name: string, command: string, opts?: _MutationOptions<_PackageJson>): this;
+    requireScript(name: string, command?: string): this;
+    addDependency(name: string, range: _SemverRange, kind?: _DepKind, opts?: _MutationOptions<_PackageJson>): this;
+    updateDependency(name: string, range: _SemverRange, kind?: _DepKind, opts?: _MutationOptions<_PackageJson>): this;
+    removeDependency(name: string, kind?: _DepKind, opts?: _MutationOptions<_PackageJson>): this;
+    ensureDependency(name: string, range: _SemverRange, kind?: _DepKind, opts?: _MutationOptions<_PackageJson>): this;
+    mustHaveScript(name: string, opts?: {
+        equals?: string;
+        matches?: RegExp;
+    }): _Diagnostic[];
+    mustHaveDependency(name: string, opts?: {
+        kind?: _DepKind;
+        range?: _SemverRange;
+    }): _Diagnostic[];
+}
+
+/**
+ * Parse an array index token per RFC 6901: must be either `"0"` or a sequence
+ * of digits `[1-9][0-9]*`. No leading zeros, no signs, no whitespace.
+ *
+ * Returns `null` for any invalid input (including the past-the-end token `"-"`).
+ */
+/** @internal */
+export declare function _parseArrayIndex(token: string): null | number;
+
+/** Input could not be parsed. */
+/** @internal */
+export declare class _ParseError extends _FileEditorError {
+    readonly format: _Format;
+    readonly offset: null | number;
+    readonly snippet: null | string;
+    constructor(format: _Format, message: string, details?: {
+        offset?: number;
+        snippet?: string;
+    });
+}
+
+/**
+ * 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;
+
+/**
+ * Parse a JSON Pointer string into its decoded reference tokens.
+ *
+ * The empty string `""` refers to the whole document and yields `[]`.
+ * `"/"` refers to the value keyed by the empty string and yields `[""]`.
+ *
+ * @throws {@link _PathError} if the pointer does not start with `/` (and is non-empty).
+     */
+ /** @internal */
+ export declare function _parsePointer(pointer: _JsonPointer): _PointerSegments;
+
+ /** A JSON Pointer is syntactically invalid or cannot be resolved. */
+ /** @internal */
+ export declare class _PathError extends _FileEditorError {
+     readonly pointer: _JsonPointer;
+     constructor(pointer: _JsonPointer, message: string);
+ }
+
+ /** A staged mutation, before it is serialized and written. */
+ /** @internal */
+ export declare interface _PendingEdit {
+     readonly kind: 'addIfMissing' | 'arrayAppend' | 'arrayUpsert' | 'merge' | 'remove' | 'set' | 'updateIfPresent';
+     readonly pointer: _JsonPointer;
+     readonly value?: unknown;
+     readonly updater?: (current: unknown) => unknown;
+     readonly arrayKey?: (element: unknown) => unknown;
+     readonly mergeOptions?: _MergeOptions;
+     readonly conflictPolicy?: _ConflictPolicy;
+     readonly guard?: (docValue: unknown) => boolean;
+ }
+
+ /**
+  * A single file that a generator intends to create.
+  * @internal
+  */
+ export declare 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;
+ }
+
+ /**
+  * Proxy-based typed pointer builder. Every property access records a segment;
+  * the terminal `$` property yields the RFC 6901 string.
+  *
+  * ```ts
+  * const p = _pointer<_PackageJson>().dependencies.lodash.$; // "/dependencies/lodash"
+  * ```
+  */
+ /** @internal */
+ export declare function _pointer<T>(): _PointerBuilder<T>;
+
+ /** @internal */
+ export declare const _POINTER_STRING: "$";
+
+ /** @internal */
+ export declare type _PointerBuilder<T> = T extends readonly (infer U)[] ? {
+     readonly [index: number]: _PointerBuilder<U>;
+     readonly $: _JsonPointer;
+ } : T extends object ? { readonly [K in keyof T & string]-?: _PointerBuilder<NonNullable<T[K]>> } & { readonly $: _JsonPointer } : { readonly $: _JsonPointer };
+
+ /** Decoded form of a JSON Pointer — an array of unescaped reference tokens. */
+ /** @internal */
+ export declare type _PointerSegments = readonly string[];
+
+ /**
+  * Execute context for project-scoped generators.
+  * @internal
+  */
+ export declare type _ProjectExecuteContext = _ProjectGeneratorContext & _WriteCapability;
+
+ /**
+  * Generator context for a project-scoped invocation.
+  * The generator places files relative to `projectRoot`.
+  * @internal
+  */
+ export declare interface _ProjectGeneratorContext {
+     readonly scope: 'project';
+     readonly projectRoot: string;
+ }
+
+ /**
+  * Register or replace a format adapter.
+  * @internal
+  */
+ export declare function _registerFormatAdapter(format: _Format, adapter: _FormatAdapter): void;
+
+ /**
+  * Resolve a pointer against a plain JS value. Returns `undefined` if any segment
+  * of the path is missing.
+  *
+  * Array indices must be decimal digits with no leading zeros (except `"0"` itself).
+  * The special token `"-"` (past-the-end) always resolves to `undefined` here;
+  * mutation operations handle it separately.
+  */
+ /** @internal */
+ export declare function _resolvePointer(root: unknown, pointer: _JsonPointer): unknown;
+
+ /** @internal */
+ export declare function _runAssertions(path: string, value: unknown, assertions: readonly _Assertion[]): _Diagnostic[];
+
+ /** @internal */
+ export declare function _runAsyncAssertions(path: string, value: unknown, assertions: readonly _AsyncAssertion[]): Promise<_Diagnostic[]>;
+
+ /** Error thrown by {@link _validateWithSchema}. */
+ /** @internal */
+ export declare class _SchemaValidationError extends Error {
+     readonly issues: readonly _StandardSchemaV1.Issue[];
+     constructor(message: string, issues: readonly _StandardSchemaV1.Issue[]);
+ }
+
+ /**
+  * A validated npm semver range string (e.g. `"^1.2.3"`, `">=1.0 <2.0"`, `"1.x"`).
+  *
+  * Obtain a {@link _SemverRange} via {@link _semverRange} (throws on invalid
+  * input) or {@link _tryParseSemverRange} (returns `null`).
+  *
+  * @see https://github.com/npm/node-semver#ranges
+  */
+ /** @internal */
+ export declare type _SemverRange = { readonly [__semverRangeBrand]: '_SemverRange' } & string;
+
+ /** Validating factory for {@link _SemverRange}. Throws on invalid input. */
+ /** @internal */
+ export declare function _semverRange(input: string): _SemverRange;
+
+ /** @internal */
+ export declare type _SemverVersion = { readonly [__semverVersionBrand]: '_SemverVersion' } & string;
+
+ /** Validating factory for {@link _SemverVersion}. Throws on invalid input. */
+ /** @internal */
+ export declare function _semverVersion(input: string): _SemverVersion;
+
+ /** Diagnostic severity. */
+ /** @internal */
+ export declare type _Severity = 'error' | 'info' | 'warning';
+
+ /** SHA-256 hex digest of arbitrary bytes (for rawSha256 tracking). */
+ /** @internal */
+ export declare function _sha256Hex(input: string | Uint8Array): string;
+
+ /**
+  * 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>;
+ }
+
+ /** Split a JSON Pointer string into its decoded reference tokens. */
+ /** @internal */
+ export declare type _SplitPointer<P extends string> = P extends '' ? [] : P extends `/${infer Rest}` ? _SplitRest<Rest> : never;
+
+ /** @internal */
+ export declare type _SplitRest<S extends string> = S extends `${infer Head}/${infer Tail}` ? [_UnescapeToken<Head>, ..._SplitRest<Tail>] : [_UnescapeToken<S>];
+
+ /**
+  * Execute context for standalone generators.
+  * @internal
+  */
+ export declare type _StandaloneExecuteContext = _StandaloneGeneratorContext & _WriteCapability;
+
+ /**
+  * 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 declare interface _StandaloneGeneratorContext {
+     readonly scope: 'standalone';
+     readonly targetDir: string;
+ }
+
+ /**
+  * Standard Schema v1 — a library-agnostic validator interface implemented by
+  * Zod v4, Valibot, ArkType, Effect Schema, and others. By accepting this
+  * interface we remain independent of any particular schema library.
+  *
+  * This module reproduces the tiny interface locally (no runtime dep).
+  *
+  * @see https://standardschema.dev
+  * @see https://github.com/standard-schema/standard-schema
+  */
+ /** @internal */
+ export declare namespace _StandardSchemaV1 {
+     /** @internal */
+     export interface Props<Input = unknown, Output = Input> {
+         readonly version: 1;
+         readonly vendor: string;
+         readonly validate: (value: unknown) => Promise<Result<Output>> | Result<Output>;
+         readonly types?: Types<Input, Output> | undefined;
+     }
+     /** @internal */
+     export type Result<Output> = FailureResult | SuccessResult<Output>;
+     /** @internal */
+     export interface SuccessResult<Output> {
+         readonly value: Output;
+         readonly issues?: undefined;
+     }
+     /** @internal */
+     export interface FailureResult {
+         readonly issues: readonly Issue[];
+     }
+     /** @internal */
+     export interface Issue {
+         readonly message: string;
+         readonly path?: readonly (PathSegment | PropertyKey)[] | undefined;
+     }
+     /** @internal */
+     export interface PathSegment {
+         readonly key: PropertyKey;
+     }
+     /** @internal */
+     export interface Types<Input = unknown, Output = Input> {
+         readonly input: Input;
+         readonly output: Output;
+     }
+     /** Extract the inferred input type. */
+     /** @internal */
+     export type InferInput<S extends _StandardSchemaV1> = NonNullable<S['~standard']['types']>['input'];
+     /** Extract the inferred output type. */
+     /** @internal */
+     export type InferOutput<S extends _StandardSchemaV1> = NonNullable<S['~standard']['types']>['output'];
+ }
+
+ /** @internal */
+ export declare interface _StandardSchemaV1<Input = unknown, Output = Input> {
+     readonly '~standard': _StandardSchemaV1.Props<Input, Output>;
+ }
+
+ /** Record kept in the state store for each managed file. */
+ /** @internal */
+ export declare interface _StateRecord {
+     readonly fingerprint: string;
+     readonly rawSha256: string;
+     readonly writtenAt: string;
+     readonly toolId: null | string;
+     readonly toolVersion: null | string;
+     readonly format: _Format;
+     readonly baseText?: string;
+ }
+
+ /**
+  * Persistence contract for drift-detection state: one record per managed file,
+  * keyed by absolute path. Library ships {@link _InMemoryStateStore} and
+  * {@link _FsCentralManifestStore}; callers may implement their own (SQLite,
+  * remote cache, etc.).
+  */
+ /** @internal */
+ export declare interface _StateStore {
+     read(absolutePath: string): Promise<_StateRecord | null>;
+     write(absolutePath: string, record: _StateRecord): Promise<void>;
+     delete(absolutePath: string): Promise<void>;
+     /** Optional enumeration for maintenance/GC tasks. */
+     list?(): Promise<readonly {
+         path: string;
+         record: _StateRecord;
+     }[]>;
+ }
+
+ /** @internal */
+ export declare type _StepInto<T, First extends string, Rest extends readonly string[]> = T extends readonly [unknown, ...unknown[]] ? First extends keyof T ? _ValueAtSegments<NonNullable<T[First]>, Rest> : unknown : T extends readonly (infer E)[] ? First extends `${number}` ? _ValueAtSegments<E, Rest> : unknown : T extends object ? First extends keyof T ? _ValueAtSegments<NonNullable<T[First]>, Rest> : string extends keyof T ? _ValueAtSegments<NonNullable<T[keyof T & string]>, Rest> : unknown : unknown;
+
+ /** @internal */
+ export declare interface _StripeAppManifest {
+     readonly id?: string;
+     readonly name?: string;
+     readonly version?: _SemverVersion | string;
+     readonly permissions?: readonly _StripePermission[];
+     readonly app_backend?: unknown;
+     readonly ui_extension?: unknown;
+     readonly custom_object_definitions?: { readonly definitions?: readonly {
+             readonly id: string;
+             readonly specification: {
+                 readonly content: string;
+                 readonly type: string;
+             };
+         }[] };
+ }
+
+ /** @internal */
+ export declare class _StripeAppManifestDoc extends _Document<_StripeAppManifest> {
+     setName(name: string, opts?: _MutationOptions<_StripeAppManifest>): this;
+     setVersion(version: _SemverVersion, opts?: _MutationOptions<_StripeAppManifest>): this;
+     addPermission(permission: _StripePermission, opts?: _MutationOptions<_StripeAppManifest>): this;
+     removePermission(permission: _StripePermission, opts?: _MutationOptions<_StripeAppManifest>): this;
+     /**
+      * Add a custom object definition. Uses arrayUpsert to avoid duplicates
+      * (keyed on `id`). Creates the `custom_object_definitions.definitions`
+      * array if it doesn't exist.
+      */
+     addCustomObject(id: string, content: string, type?: string, opts?: _MutationOptions<_StripeAppManifest>): this;
+     /**
+      * Check if a custom object definition exists by id.
+      */
+     hasCustomObject(id: string): boolean;
+ }
+
+ /**
+  * 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;
+
+ /**
+  * Stripe app permission strings follow the convention `{verb}_{resource}` —
+  * e.g. `read_customers`, `write_products`. The template literal enforces the
+  * prefix while keeping the resource portion open so the type doesn't go
+  * stale as Stripe adds resources.
+  *
+  * @see https://docs.stripe.com/stripe-apps/reference/permissions
+  */
+ /** @internal */
+ export declare type _StripePermission = `${'read' | 'write'}_${string}`;
+
+ /**
+  * 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;
+ }
+
+ /**
+  * Template entry in the in-memory registry
+  * @internal
+  */
+ export declare interface _TemplateFSImageEntry {
+     path: string;
+     content: string;
+ }
+
+ /**
+  * 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[];
+ }
+
+ /**
+  * 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[];
+ }
+
+ /** Capitalizes the first character of a string, leaving the rest unchanged. @internal */
+ export declare function _toCapitalized(value: string): string;
+
+ /** Tokenizes an identifier into words using Stripe API case heuristics. @internal */
+ export declare function _tokenizeIdentifier(input: string): string[];
+
+ /** Converts a snake_case identifier to PascalCase. @internal */
+ export declare function _toPascalCase(value: string): string;
+
+ /** Pluralizes a name using the `inflected` library. @internal */
+ export declare function _toPlural(value: string): string;
+
+ /** Converts an identifier into a sentence-case display name. @internal */
+ export declare function _toSentenceDisplayName(input: string): string;
+
+ /** Singularizes a name using the `inflected` library. @internal */
+ export declare function _toSingular(value: string): string;
+
+ /** Converts a PascalCase or camelCase identifier to snake_case. @internal */
+ export declare function _toSnakeCase(value: string): string;
+
+ /** Converts an identifier into Stripe API case. @internal */
+ export declare function _toStripeApiCase(input: string): string;
+
+ /** An editing session spanning one or more documents. */
+ /** @internal */
+ export declare class _Transaction {
+     private readonly documents;
+     private readonly options;
+     constructor(options?: _TransactionOptions);
+     /** Open or return the cached document for a path. Memoized per transaction. */
+     open(absolutePath: string): Promise<_Document>;
+     /** @internal — register a document that was opened externally (e.g. via a façade). */
+     adopt(doc: _Document): void;
+     /** Drop all staged edits across every document in the transaction. */
+     rollback(): void;
+     /** Plan without writing. Invokes `onConflict`/`confirmWrite` as a real commit would. */
+     dryRun(options?: _CommitOptions): Promise<_CommitReport>;
+     /** Apply staged edits to disk. */
+     commit(options?: _CommitOptions): Promise<_CommitReport>;
+     private run;
+ }
+
+ /** Options common to opening documents inside a transaction. */
+ /** @internal */
+ export declare interface _TransactionOptions {
+     readonly format?: _Format;
+     readonly stateStore?: _StateStore;
+     readonly onConflict?: _ConflictResolver;
+     readonly confirmWrite?: _WriteConfirm;
+     readonly confirmationPolicy?: _ConfirmationPolicy;
+     readonly toolId?: string;
+     readonly toolVersion?: string;
+ }
+
+ /** Truncates a name to a maximum length without additional normalization. @internal */
+ export declare function _truncateName(value: string, maxLength: number): string;
+
+ /** Non-throwing variant of {@link _semverRange}. */
+ /** @internal */
+ export declare function _tryParseSemverRange(input: string): _SemverRange | null;
+
+ /** Non-throwing variant of {@link _semverVersion}. */
+ /** @internal */
+ export declare function _tryParseSemverVersion(input: string): _SemverVersion | null;
+
+ /** Non-throwing variant returning the Standard Schema result directly. */
+ /** @internal */
+ export declare function _tryValidateWithSchema<S extends _StandardSchemaV1>(schema: S, value: unknown): Promise<_StandardSchemaV1.Result<_StandardSchemaV1.InferOutput<S>>>;
+
+ /** @internal */
+ export declare interface _TsConfig {
+     readonly extends?: readonly string[] | string;
+     readonly compilerOptions?: _CompilerOptions;
+     readonly include?: readonly string[];
+     readonly exclude?: readonly string[];
+     readonly files?: readonly string[];
+     readonly references?: readonly { readonly path: string }[];
+ }
+
+ /** @internal */
+ export declare class _TsConfigDoc extends _Document<_TsConfig> {
+     setCompilerOption<K extends _CompilerOptionKey>(name: K, value: _CompilerOptionValue<K>, opts?: _MutationOptions<_TsConfig>): this;
+     ensureCompilerOption<K extends _CompilerOptionKey>(name: K, value: _CompilerOptionValue<K>, opts?: _MutationOptions<_TsConfig>): this;
+     addInclude(pattern: string, opts?: _MutationOptions<_TsConfig>): this;
+     addExclude(pattern: string, opts?: _MutationOptions<_TsConfig>): this;
+     addReference(path: string, opts?: _MutationOptions<_TsConfig>): this;
+     mustHaveCompilerOption<K extends _CompilerOptionKey>(name: K, opts?: {
+         readonly equals?: _CompilerOptionValue<K>;
+         readonly oneOf?: readonly _CompilerOptionValue<K>[];
+     }): _Diagnostic[];
+ }
+
+ /** @internal */
+ export declare type _TsJsx = 'preserve' | 'react-jsx' | 'react-jsxdev' | 'react-native' | 'react';
+
+ /** @internal */
+ export declare type _TsModule = 'AMD' | 'CommonJS' | 'ES2015' | 'ES2020' | 'ES2022' | 'ES6' | 'ESNext' | 'Node16' | 'NodeNext' | 'None' | 'Preserve' | 'System' | 'UMD';
+
+ /** @internal */
+ export declare type _TsModuleResolution = 'Bundler' | 'Classic' | 'Node' | 'Node10' | 'Node16' | 'NodeNext';
+
+ /**
+  * Typed surface for tsconfig.json `compilerOptions`. Covers the keys most
+  * commonly touched by build tooling; keys outside this set remain editable
+  * through the generic {@link _Document} API as an escape hatch.
+  *
+  * @see https://www.typescriptlang.org/tsconfig
+  */
+ /** Canonical TypeScript language-target values. */
+ /** @internal */
+ export declare type _TsTarget = 'ES2015' | 'ES2016' | 'ES2017' | 'ES2018' | 'ES2019' | 'ES2020' | 'ES2021' | 'ES2022' | 'ES2023' | 'ES2024' | 'ES3' | 'ES5' | 'ES6' | 'ESNext';
+
+ /** A mutation's expected shape doesn't match the current value. */
+ /** @internal */
+ export declare class _TypeMismatchError extends _FileEditorError {
+     readonly pointer: _JsonPointer;
+     constructor(pointer: _JsonPointer, message: string);
+ }
+
+ /**
+  * Type-level arithmetic for resolving the value type at a JSON Pointer,
+  * given a known schema type.
+  *
+  * `_ValueAtPointer<T, P>` walks `T` segment-by-segment along the decoded
+  * _pointer string `P` and yields the value type at that location. For
+  * unknown or structurally impossible paths it falls back to `unknown`,
+  * so a typed `set(_pointer, value)` signature rejects values that couldn't
+  * possibly belong at that location.
+  *
+  * This entire module is *types only* at runtime — zero code is emitted.
+  *
+  * @see https://datatracker.ietf.org/doc/html/rfc6901
+  */
+ /** Unescape a single reference token per RFC 6901 (§4). */
+ /** @internal */
+ export declare type _UnescapeToken<S extends string> = S extends `${infer H}~1${infer T}` ? `${H}/${_UnescapeToken<T>}` : S extends `${infer H}~0${infer T}` ? `${H}~${_UnescapeToken<T>}` : S;
+
+ /** Unescape a single JSON Pointer reference token (RFC 6901 §4). */
+ /** @internal */
+ export declare function _unescapeToken(token: string): string;
+
+ /** 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;
+
+ /**
+  * Validate a value against a Standard Schema. Awaits the validator if it
+  * returns a promise. Returns the parsed value on success, throws on failure
+  * with a formatted message.
+  */
+ /** @internal */
+ export declare function _validateWithSchema<S extends _StandardSchemaV1>(schema: S, value: unknown): Promise<_StandardSchemaV1.InferOutput<S>>;
+
+ /**
+  * Given a schema type `T` and a JSON Pointer string literal `P`, the value
+  * type at the _pointer's location. Empty _pointer yields `T` itself.
+  *
+  * When `T` is `unknown` the arithmetic collapses to `unknown`, so the
+  * generic `_Document<unknown>` transparently accepts any value.
+  * @internal
+  */
+ export declare type _ValueAtPointer<T, P extends string> = _IsUnknown<T> extends true ? unknown : _ValueAtSegments<T, _SplitPointer<P>>;
+
+ /**
+  * Walk a schema type `T` along a sequence of reference tokens `S`,
+  * yielding the value type at that location (or `unknown` for structurally
+  * impossible paths).
+  * @internal
+  */
+ export declare type _ValueAtSegments<T, S extends readonly string[]> = S extends readonly [] ? T : S extends readonly [infer First extends string, ...infer Rest extends string[]] ? _StepInto<T, First, Rest> : unknown;
+
+ /**
+  * Look up the current version for a workspace package.
+  *
+  * Throws if the package is not in the manifest — this catches typos at
+  * build time rather than producing a silent `undefined`.
+  * @internal
+  */
+ export declare function _workspaceVersion(packageName: string): string;
+
+ /** confirmWrite returned "abort". */
+ /** @internal */
+ export declare class _WriteAbortedError extends _FileEditorError {
+     readonly path: string;
+     constructor(path: string);
+ }
+
+ /**
+  * Capability mixin that adds `writeFiles` to an execute context.
+  * @internal
+  */
+ export declare interface _WriteCapability {
+     /** Write generated files to disk. Provided by the caller. */
+     writeFiles(files: readonly _PlannedFile[]): Promise<_GeneratorWriteResult>;
+ }
+
+ /** @internal */
+ export declare type _WriteConfirm = (req: _WriteRequest) => Promise<_WriteDecision>;
+
+ /** Result of a write-confirmation request. */
+ /** @internal */
+ export declare type _WriteDecision = 'abort' | 'skip' | 'write';
+
+ /**
+  * Error detail attached to a file write outcome.
+  * @internal
+  */
+ export declare interface _WriteError {
+     readonly kind: 'conflict' | 'disk' | 'permission' | 'unknown';
+     readonly message: string;
+ }
+
+ /**
+  * Write a JSON result to the given file path, or no-op if no path is provided.
+  *
+  * Used by CLI binaries that support `--output-path <file>` for structured
+  * output. When the flag is omitted the caller handles human-readable output
+  * to stdout instead.
+  *
+  * @internal
+  */
+ export declare function _writeJsonOutput(outputPath: string | undefined, data: unknown): void;
+
+ /** Reason the library is requesting a write. */
+ /** @internal */
+ export declare type _WriteReason = 'conflict' | 'new-file' | 'update';
+
+ /** Payload handed to the caller-supplied `confirmWrite` hook. */
+ /** @internal */
+ export declare interface _WriteRequest {
+     readonly path: string;
+     readonly format: _Format;
+     readonly reason: _WriteReason;
+     readonly currentText: null | string;
+     readonly nextText: string;
+     readonly unifiedDiff: string;
+     readonly hunks: readonly _DiffHunk[];
+     readonly conflict: _Conflict | null;
+ }
+
+ /** @internal */
+ export declare const _yamlAdapter: _FormatAdapter;
+
+ export { }