@soda-gql/tools 0.13.0

package/dist/bin.d.cts

@@ -0,0 +1,839 @@
+import * as neverthrow3 from "neverthrow";
+import { Result } from "neverthrow";
+import { ArtifactLoadError, BuilderError, FieldSelectionData, FieldSelectionsMap } from "@soda-gql/builder";
+import { ConfigError, ResolvedSodaGqlConfig, TypeCategory, TypeFilterConfig } from "@soda-gql/config";
+import * as graphql0 from "graphql";
+import { DocumentNode, TypeNode } from "graphql";
+import { AnyGraphqlSchema, DirectiveRecord, EnrichedFragment, EnrichedOperation, EnumRecord, GraphqlAnalysisError as GraphqlCompatError, InferredVariable, InputRecord, ObjectRecord, OperationTypeNames, ParseResultBase as ParseResult, ParsedFragment, ParsedSelection, ScalarRecord, SchemaIndex as SchemaIndex$1, TransformOptions, TransformResult, TypeInfo, UnionRecord, createSchemaIndex } from "@soda-gql/core";
+import { CanonicalId } from "@soda-gql/common";
+
+//#region packages/tools/src/codegen/graphql-compat/types.d.ts
+
+/**
+ * Options for running graphql-compat code generation.
+ */
+type GraphqlCompatOptions = {
+  /** Schema name from config */
+  readonly schemaName: string;
+  /** Resolved paths to .graphql operation files */
+  readonly operationFiles: readonly string[];
+  /** Output directory for generated files */
+  readonly outputDir?: string;
+  /** Import path for graphql-system module (e.g., "@/graphql-system") */
+  readonly graphqlSystemPath: string;
+};
+/**
+ * Generated file output.
+ */
+type GeneratedFile = {
+  readonly path: string;
+  readonly content: string;
+};
+//#endregion
+//#region packages/tools/src/codegen/graphql-compat/emitter.d.ts
+/**
+ * Options for code emission.
+ */
+type EmitOptions = {
+  /** Schema name to use in gql.schemaName() call */
+  readonly schemaName: string;
+  /** Import path for graphql-system module */
+  readonly graphqlSystemPath: string;
+  /** Schema document for type lookups (required for inline fragment support) */
+  readonly schemaDocument?: DocumentNode;
+};
+/**
+ * Emit TypeScript code for an operation.
+ */
+declare const emitOperation: (operation: EnrichedOperation, options: EmitOptions) => Result<string, GraphqlCompatError>;
+/**
+ * Emit TypeScript code for a fragment.
+ */
+declare const emitFragment: (fragment: EnrichedFragment, options: EmitOptions) => Result<string, GraphqlCompatError>;
+//#endregion
+//#region packages/tools/src/codegen/graphql-compat/parser.d.ts
+/**
+ * Parse a single .graphql file and extract operations and fragments.
+ */
+declare const parseGraphqlFile: (filePath: string) => Result<ParseResult, GraphqlCompatError>;
+/**
+ * Parse GraphQL source string directly.
+ */
+declare const parseGraphqlSource: (source: string, sourceFile: string) => Result<ParseResult, GraphqlCompatError>;
+/**
+ * Parse a GraphQL TypeNode into type name and modifier.
+ *
+ * Format: inner nullability + list modifiers
+ * - Inner: `!` (non-null) or `?` (nullable)
+ * - List: `[]!` (non-null list) or `[]?` (nullable list)
+ */
+declare const parseTypeNode: (node: TypeNode) => TypeInfo;
+//#endregion
+//#region packages/tools/src/codegen/defs-generator.d.ts
+/**
+ * Definition file generator for split codegen.
+ * Generates separate files for each definition category (enums, inputs, objects, unions).
+ */
+type DefinitionCategory = "enums" | "inputs" | "objects" | "unions";
+type DefinitionVar = {
+  readonly name: string;
+  readonly code: string;
+};
+/**
+ * Split an array into chunks of the specified size.
+ */
+declare const chunkArray: <T>(array: readonly T[], size: number) => T[][];
+/**
+ * Determine if chunking is needed based on the number of definitions.
+ */
+declare const needsChunking: (vars: readonly DefinitionVar[], chunkSize: number) => boolean;
+type DefinitionFileOptions = {
+  readonly category: DefinitionCategory;
+  readonly schemaName: string;
+  readonly vars: readonly DefinitionVar[];
+  readonly needsDefineEnum: boolean;
+};
+/**
+ * Generate a single definition file content.
+ */
+declare const generateDefinitionFile: (options: DefinitionFileOptions) => string;
+type ChunkFileOptions = {
+  readonly category: DefinitionCategory;
+  readonly schemaName: string;
+  readonly vars: readonly DefinitionVar[];
+  readonly chunkIndex: number;
+  readonly needsDefineEnum: boolean;
+};
+/**
+ * Generate a chunk file content.
+ */
+declare const generateChunkFile: (options: ChunkFileOptions) => string;
+type ChunkIndexOptions = {
+  readonly category: DefinitionCategory;
+  readonly chunkCount: number;
+  readonly varNames: readonly string[];
+};
+/**
+ * Generate the index file that re-exports all chunks.
+ */
+declare const generateChunkIndex: (options: ChunkIndexOptions) => string;
+type ChunkedDefinitionFiles = {
+  readonly indexContent: string;
+  readonly chunks: ReadonlyArray<{
+    readonly chunkIndex: number;
+    readonly content: string;
+    readonly varNames: readonly string[];
+  }>;
+};
+/**
+ * Generate chunked definition files.
+ */
+declare const generateChunkedDefinitionFiles: (category: DefinitionCategory, schemaName: string, vars: readonly DefinitionVar[], chunkSize: number) => ChunkedDefinitionFiles;
+type DefsDirectoryStructure = {
+  readonly files: ReadonlyArray<{
+    readonly relativePath: string;
+    readonly content: string;
+  }>;
+  readonly importPaths: Record<DefinitionCategory, string>;
+};
+type CategoryVars = {
+  readonly enums: readonly DefinitionVar[];
+  readonly inputs: readonly DefinitionVar[];
+  readonly objects: readonly DefinitionVar[];
+  readonly unions: readonly DefinitionVar[];
+};
+/**
+ * Generate the complete _defs directory structure.
+ */
+declare const generateDefsStructure: (schemaName: string, categoryVars: CategoryVars, chunkSize: number) => DefsDirectoryStructure;
+//#endregion
+//#region packages/tools/src/codegen/generator.d.ts
+type DefsFile = {
+  readonly relativePath: string;
+  readonly content: string;
+};
+type GeneratedModule = {
+  readonly code: string;
+  readonly injectsCode?: string;
+  readonly defsFiles?: readonly DefsFile[];
+  readonly categoryVars?: Record<string, CategoryVars>;
+  readonly stats: {
+    readonly objects: number;
+    readonly enums: number;
+    readonly inputs: number;
+    readonly unions: number;
+  };
+};
+type PerSchemaInjection = {
+  readonly scalarImportPath: string;
+  readonly adapterImportPath?: string;
+};
+type RuntimeGenerationOptions = {
+  readonly injection?: Map<string, PerSchemaInjection>;
+  readonly defaultInputDepth?: Map<string, number>;
+  readonly inputDepthOverrides?: Map<string, Readonly<Record<string, number>>>;
+  readonly chunkSize?: number;
+  readonly typeFilters?: Map<string, TypeFilterConfig>;
+};
+declare const generateMultiSchemaModule: (schemas: Map<string, DocumentNode>, options?: RuntimeGenerationOptions) => GeneratedModule;
+/**
+ * Generate a stub `types.prebuilt.ts` file with empty PrebuiltTypes registries.
+ * This stub is only written when `types.prebuilt.ts` does not already exist.
+ * Typegen will later overwrite it with the real type registry.
+ */
+declare const generatePrebuiltStub: (schemaNames: string[]) => string;
+/**
+ * Generate the `index.ts` module that re-exports from `_internal`
+ * and constructs the `gql` object from individual `__gql_*` exports.
+ *
+ * The `gql` object preserves the original inferred types from schema inference.
+ * PrebuiltContext types will be integrated once the type resolution strategy
+ * is redesigned to match the tagged template runtime API.
+ */
+declare const generateIndexModule: (schemaNames: string[], allFieldNames?: ReadonlyMap<string, readonly string[]>) => string;
+//#endregion
+//#region packages/tools/src/codegen/graphql-compat/transformer.d.ts
+/**
+ * Schema index type extracted from generator.
+ */
+type SchemaIndex = ReturnType<typeof createSchemaIndex>;
+/**
+ * Check if source modifier can be assigned to target modifier.
+ * Implements GraphQL List Coercion: depth difference of 0 or 1 is allowed.
+ *
+ * Rules:
+ * - A single value can be coerced into a list (depth diff = 1)
+ * - At each level, non-null can be assigned to nullable (but not vice versa)
+ *
+ * @param source - The modifier of the value being assigned (variable's type)
+ * @param target - The modifier expected by the position (field argument's type)
+ * @returns true if assignment is valid
+ */
+declare const isModifierAssignable: (source: string, target: string) => boolean;
+/**
+ * Merge two modifiers by taking the stricter constraint at each level.
+ * - Non-null (!) is stricter than nullable (?)
+ * - List depths must match
+ *
+ * @param a - First modifier
+ * @param b - Second modifier
+ * @returns Merged modifier or error if incompatible
+ */
+declare const mergeModifiers: (a: string, b: string) => {
+  ok: true;
+  value: string;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Intermediate type for tracking variable usages before merging.
+ */
+type VariableUsage = {
+  readonly name: string;
+  readonly typeName: string;
+  /** The modifier expected by the field/argument position */
+  readonly expectedModifier: string;
+  /** The minimum modifier the variable needs (after applying List Coercion) */
+  readonly minimumModifier: string;
+  readonly typeKind: "scalar" | "enum" | "input";
+};
+/**
+ * Get the expected type for a field argument from the schema.
+ * Returns null if the field or argument is not found.
+ */
+declare const getArgumentType: (schema: SchemaIndex, parentTypeName: string, fieldName: string, argumentName: string) => TypeInfo | null;
+/**
+ * Get the expected type for an input object field from the schema.
+ */
+declare const getInputFieldType: (schema: SchemaIndex, inputTypeName: string, fieldName: string) => TypeInfo | null;
+/**
+ * Recursively collect all variable usages from selections.
+ */
+declare const collectVariableUsages: (selections: readonly ParsedSelection[], parentTypeName: string, schema: SchemaIndex) => Result<VariableUsage[], GraphqlCompatError>;
+/**
+ * Get the return type of a field (unwrapped from modifiers).
+ */
+declare const getFieldReturnType: (schema: SchemaIndex, parentTypeName: string, fieldName: string) => string | null;
+/**
+ * Merge multiple variable usages into a single InferredVariable.
+ * Validates type compatibility and merges modifiers using List Coercion rules.
+ *
+ * The algorithm:
+ * 1. Validate all usages have the same type name
+ * 2. Merge minimumModifiers to find the candidate (shallowest type that could work)
+ * 3. Verify the candidate can satisfy ALL expected modifiers via isModifierAssignable
+ */
+declare const mergeVariableUsages: (variableName: string, usages: readonly VariableUsage[]) => Result<InferredVariable, GraphqlCompatError>;
+/**
+ * Infer variables from collected usages.
+ * Groups by variable name and merges each group.
+ */
+declare const inferVariablesFromUsages: (usages: readonly VariableUsage[]) => Result<InferredVariable[], GraphqlCompatError>;
+/**
+ * Topologically sort fragments so dependencies come before dependents.
+ * Detects circular dependencies.
+ *
+ * Note: Uses the existing collectFragmentDependencies function defined below.
+ */
+declare const sortFragmentsByDependency: (fragments: readonly ParsedFragment[]) => Result<ParsedFragment[], GraphqlCompatError>;
+/**
+ * Transform parsed operations/fragments by enriching them with schema information.
+ *
+ * This resolves variable type kinds (scalar, enum, input), collects
+ * fragment dependencies, and infers variables for fragments.
+ */
+declare const transformParsedGraphql: (parsed: ParseResult, options: TransformOptions) => Result<TransformResult, GraphqlCompatError>;
+//#endregion
+//#region packages/tools/src/codegen/types.d.ts
+type CodegenFormat = "json" | "human";
+type CodegenInjectConfig = {
+  readonly scalars: string;
+  readonly adapter?: string;
+};
+type CodegenSchemaConfig = {
+  readonly schema: readonly string[];
+  readonly inject: CodegenInjectConfig;
+  readonly defaultInputDepth?: number;
+  readonly inputDepthOverrides?: Readonly<Record<string, number>>;
+  readonly typeFilter?: TypeFilterConfig;
+};
+type CodegenOptions = {
+  readonly schemas: Record<string, CodegenSchemaConfig>;
+  readonly outPath: string;
+  readonly format: CodegenFormat;
+  readonly importExtension?: boolean;
+  readonly chunkSize?: number;
+  /** Pre-loaded schema documents. Skips file loading when provided. */
+  readonly preloadedSchemas?: ReadonlyMap<string, graphql0.DocumentNode>;
+};
+type CodegenCliCommand = {
+  readonly kind: "generate";
+  readonly options: CodegenOptions;
+} | {
+  readonly kind: "emitInjectTemplate";
+  readonly outPath: string;
+  readonly format: CodegenFormat;
+};
+type CodegenError = {
+  readonly code: "SCHEMA_NOT_FOUND";
+  readonly message: string;
+  readonly schemaPath: string;
+} | {
+  readonly code: "SCHEMA_INVALID";
+  readonly message: string;
+  readonly schemaPath: string;
+} | {
+  readonly code: "EMIT_FAILED";
+  readonly message: string;
+  readonly outPath: string;
+} | {
+  readonly code: "INJECT_MODULE_REQUIRED";
+  readonly message: string;
+} | {
+  readonly code: "INJECT_MODULE_NOT_FOUND";
+  readonly message: string;
+  readonly injectPath: string;
+} | {
+  readonly code: "INJECT_TEMPLATE_EXISTS";
+  readonly message: string;
+  readonly outPath: string;
+} | {
+  readonly code: "INJECT_TEMPLATE_FAILED";
+  readonly message: string;
+  readonly outPath: string;
+} | {
+  readonly code: "REMOVE_FAILED";
+  readonly message: string;
+  readonly outPath: string;
+} | {
+  readonly code: "READ_FAILED";
+  readonly message: string;
+  readonly outPath: string;
+};
+type CodegenSuccess = {
+  readonly schemas: Record<string, {
+    readonly schemaHash: string;
+    readonly objects: number;
+    readonly enums: number;
+    readonly inputs: number;
+    readonly unions: number;
+  }>;
+  readonly outPath: string;
+  readonly internalPath: string;
+  readonly injectsPath: string;
+  readonly cjsPath: string;
+  readonly defsPaths?: readonly string[];
+};
+type CodegenResult = Result<CodegenSuccess, CodegenError>;
+//#endregion
+//#region packages/tools/src/codegen/inject-template.d.ts
+declare const writeInjectTemplate: (outPath: string) => neverthrow3.Err<void, CodegenError> | neverthrow3.Ok<void, CodegenError>;
+declare const getInjectTemplate: () => string;
+//#endregion
+//#region packages/tools/src/codegen/type-filter.d.ts
+type FilterContext = {
+  readonly name: string;
+  readonly category: TypeCategory;
+};
+type CompiledFilter = (context: FilterContext) => boolean;
+declare const compileTypeFilter: (config: TypeFilterConfig | undefined) => CompiledFilter;
+declare const buildExclusionSet: (filter: CompiledFilter, typeNames: Map<TypeCategory, readonly string[]>) => Set<string>;
+//#endregion
+//#region packages/tools/src/codegen/reachability.d.ts
+type ReachabilityResult = {
+  readonly filter: (context: FilterContext) => boolean;
+  readonly warnings: readonly string[];
+};
+/**
+ * Compute a filter function that includes only types reachable from root types
+ * to the specified target types.
+ *
+ * When targetTypes is empty, returns a pass-all filter (no filtering).
+ * Warns when target types are not found in the schema.
+ *
+ * @param document - The parsed GraphQL schema document
+ * @param targetTypes - Set of type names that fragments target (e.g., from ParsedFragment.onType)
+ * @returns Filter function and any warnings
+ */
+declare const computeReachabilityFilter: (document: DocumentNode, targetTypes: ReadonlySet<string>, usedArgumentTypes?: ReadonlySet<string>) => ReachabilityResult;
+//#endregion
+//#region packages/tools/src/codegen/runner.d.ts
+declare const runCodegen: (options: CodegenOptions) => Promise<CodegenResult>;
+//#endregion
+//#region packages/tools/src/codegen/schema.d.ts
+/**
+ * Load a single schema file.
+ * @internal Use loadSchema for public API.
+ */
+declare const loadSingleSchema: (schemaPath: string) => neverthrow3.Err<DocumentNode, CodegenError> | neverthrow3.Ok<DocumentNode, CodegenError>;
+/**
+ * Load and merge multiple schema files into a single DocumentNode.
+ * Uses GraphQL's concatAST to combine definitions from all files.
+ */
+declare const loadSchema: (schemaPaths: readonly string[]) => neverthrow3.Err<DocumentNode, CodegenError> | neverthrow3.Ok<DocumentNode, CodegenError>;
+declare const hashSchema: (document: DocumentNode) => string;
+//#endregion
+//#region packages/tools/src/typegen/errors.d.ts
+/**
+ * Error codes specific to typegen operations.
+ */
+type TypegenErrorCode = "TYPEGEN_CODEGEN_REQUIRED" | "TYPEGEN_SCHEMA_LOAD_FAILED" | "TYPEGEN_BUILD_FAILED";
+/**
+ * Typegen-specific error type.
+ */
+type TypegenSpecificError = {
+  readonly code: "TYPEGEN_CODEGEN_REQUIRED";
+  readonly message: string;
+  readonly outdir: string;
+} | {
+  readonly code: "TYPEGEN_SCHEMA_LOAD_FAILED";
+  readonly message: string;
+  readonly schemaNames: readonly string[];
+  readonly cause?: unknown;
+} | {
+  readonly code: "TYPEGEN_BUILD_FAILED";
+  readonly message: string;
+  readonly cause?: unknown;
+};
+/**
+ * Union of all typegen errors (specific + builder errors).
+ */
+type TypegenError = TypegenSpecificError | BuilderError;
+/**
+ * Error constructor helpers for concise error creation.
+ */
+declare const typegenErrors: {
+  readonly codegenRequired: (outdir: string) => TypegenSpecificError;
+  readonly schemaLoadFailed: (schemaNames: readonly string[], cause?: unknown) => TypegenSpecificError;
+  readonly buildFailed: (message: string, cause?: unknown) => TypegenSpecificError;
+};
+/**
+ * Format TypegenError for console output (human-readable).
+ */
+declare const formatTypegenError: (error: TypegenError) => string;
+//#endregion
+//#region packages/tools/src/typegen/emitter.d.ts
+/**
+ * Options for emitting prebuilt types.
+ */
+type PrebuiltTypesEmitterOptions = {
+  /**
+   * Schema definitions per schema name.
+   * These come from the codegen output.
+   */
+  readonly schemas: Record<string, AnyGraphqlSchema>;
+  /**
+   * Field selections extracted from the builder.
+   */
+  readonly fieldSelections: FieldSelectionsMap;
+  /**
+   * Output directory (where types.prebuilt.ts should be written).
+   * This should be the same as config.outdir.
+   */
+  readonly outdir: string;
+  /**
+   * Relative import path to _internal-injects.ts from types.prebuilt.ts.
+   * Example: "./_internal-injects"
+   */
+  readonly injectsModulePath: string;
+};
+/**
+ * Result of emitting prebuilt types.
+ */
+type PrebuiltTypesEmitResult = {
+  readonly path: string;
+  readonly warnings: readonly string[];
+  readonly skippedFragmentCount: number;
+};
+/**
+ * Emit prebuilt types to the types.prebuilt.ts file.
+ *
+ * This function uses a partial failure strategy: if type calculation fails for
+ * individual elements (e.g., due to invalid field selections or missing schema
+ * types), those elements are skipped and warnings are collected rather than
+ * failing the entire emission. This allows builds to succeed even when some
+ * elements have issues, while still reporting problems via warnings.
+ *
+ * @param options - Emitter options including schemas, field selections, and output directory
+ * @returns Result containing output path and warnings, or error if a hard failure occurs
+ *
+ * @example
+ * ```typescript
+ * const result = await emitPrebuiltTypes({
+ *   schemas: { mySchema: schema },
+ *   fieldSelections,
+ *   outdir: "./generated",
+ *   injects: { mySchema: { scalars: "./scalars.ts" } },
+ * });
+ *
+ * if (result.isOk()) {
+ *   console.log(`Generated: ${result.value.path}`);
+ *   if (result.value.warnings.length > 0) {
+ *     console.warn("Warnings:", result.value.warnings);
+ *   }
+ * }
+ * ```
+ */
+declare const emitPrebuiltTypes: (options: PrebuiltTypesEmitterOptions) => Promise<Result<PrebuiltTypesEmitResult, BuilderError | TypegenError>>;
+//#endregion
+//#region packages/tools/src/typegen/types.d.ts
+/**
+ * Options for running typegen.
+ */
+type TypegenOptions = {
+  /**
+   * Absolute path to the output directory (usually config.outdir).
+   * This is where the generated graphql-system module resides.
+   */
+  readonly outdir: string;
+  /**
+   * Schema names to process.
+   */
+  readonly schemaNames: readonly string[];
+  /**
+   * Inject configuration per schema.
+   * Maps schema name to inject file paths (absolute paths).
+   */
+  readonly injects: Record<string, {
+    readonly scalars: string;
+  }>;
+  /**
+   * Whether to include import extensions in generated code.
+   */
+  readonly importExtension?: boolean;
+};
+/**
+ * Result of a successful typegen run.
+ */
+type TypegenSuccess = {
+  /**
+   * Path to the generated types.prebuilt.ts file.
+   */
+  readonly prebuiltTypesPath: string;
+  /**
+   * Number of fragments processed.
+   */
+  readonly fragmentCount: number;
+  /**
+   * Number of operations processed.
+   */
+  readonly operationCount: number;
+  /**
+   * Number of fragments skipped due to missing 'key' property.
+   */
+  readonly skippedFragmentCount: number;
+  /**
+   * Warnings encountered during type generation.
+   */
+  readonly warnings: readonly string[];
+};
+/**
+ * Result type for typegen operations.
+ */
+type TypegenResult = Result<TypegenSuccess, TypegenError>;
+//#endregion
+//#region packages/tools/src/typegen/runner.d.ts
+/**
+ * Options for running typegen.
+ */
+type RunTypegenOptions = {
+  /**
+   * Resolved soda-gql configuration.
+   */
+  readonly config: ResolvedSodaGqlConfig;
+};
+/**
+ * Run the typegen process.
+ *
+ * This function:
+ * 1. Loads schemas from the generated CJS bundle
+ * 2. Creates a BuilderService and builds the artifact
+ * 3. Extracts field selections from the artifact
+ * 4. Scans source files for tagged templates and merges selections
+ * 5. Emits types.prebuilt.ts using emitPrebuiltTypes
+ *
+ * @param options - Typegen options including config
+ * @returns Result containing success data or error
+ */
+declare const runTypegen: (options: RunTypegenOptions) => Promise<TypegenResult>;
+/**
+ * Merge builder and template selections into a combined map.
+ *
+ * Builder selections are authoritative — VM evaluation correctly resolves
+ * fragment spreads that static template analysis cannot handle.
+ * Template selections serve as fallback for elements only found by the scanner.
+ *
+ * Deduplication is per-element (file + GraphQL name), not per-file, so that
+ * callback-builder operations in files that also contain tagged templates are preserved.
+ */
+declare const mergeSelections: (builderSelections: ReadonlyMap<CanonicalId, FieldSelectionData>, templateSelections: ReadonlyMap<CanonicalId, FieldSelectionData>, baseDir: string) => Map<CanonicalId, FieldSelectionData>;
+//#endregion
+//#region packages/tools/src/cli/errors.d.ts
+/**
+ * CLI-specific error codes.
+ */
+type CliErrorCode = "CLI_ARGS_INVALID" | "CLI_UNKNOWN_COMMAND" | "CLI_UNKNOWN_SUBCOMMAND" | "CLI_FILE_EXISTS" | "CLI_FILE_NOT_FOUND" | "CLI_WRITE_FAILED" | "CLI_READ_FAILED" | "CLI_NO_PATTERNS" | "CLI_FORMATTER_NOT_INSTALLED" | "CLI_PARSE_ERROR" | "CLI_FORMAT_ERROR" | "CLI_DUPLICATE_FRAGMENT" | "CLI_FRAGMENT_NOT_FOUND" | "CLI_UNEXPECTED";
+/**
+ * Unified CLI error discriminated union.
+ * Wraps external errors (codegen, builder, config, typegen) and defines CLI-specific errors.
+ */
+type CliError = {
+  readonly category: "codegen";
+  readonly error: CodegenError;
+} | {
+  readonly category: "builder";
+  readonly error: BuilderError;
+} | {
+  readonly category: "artifact";
+  readonly error: ArtifactLoadError;
+} | {
+  readonly category: "config";
+  readonly error: ConfigError;
+} | {
+  readonly category: "typegen";
+  readonly error: TypegenError;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_ARGS_INVALID";
+  readonly message: string;
+  readonly command: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_UNKNOWN_COMMAND";
+  readonly message: string;
+  readonly command: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_UNKNOWN_SUBCOMMAND";
+  readonly message: string;
+  readonly parent: string;
+  readonly subcommand: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_FILE_EXISTS";
+  readonly message: string;
+  readonly filePath: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_FILE_NOT_FOUND";
+  readonly message: string;
+  readonly filePath: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_WRITE_FAILED";
+  readonly message: string;
+  readonly filePath: string;
+  readonly cause?: unknown;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_READ_FAILED";
+  readonly message: string;
+  readonly filePath: string;
+  readonly cause?: unknown;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_NO_PATTERNS";
+  readonly message: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_FORMATTER_NOT_INSTALLED";
+  readonly message: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_PARSE_ERROR";
+  readonly message: string;
+  readonly filePath?: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_FORMAT_ERROR";
+  readonly message: string;
+  readonly filePath?: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_DUPLICATE_FRAGMENT";
+  readonly message: string;
+  readonly fragmentName: string;
+  readonly existingFile: string;
+  readonly newFile: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_FRAGMENT_NOT_FOUND";
+  readonly message: string;
+  readonly fragmentName: string;
+  readonly referencedIn: string;
+} | {
+  readonly category: "cli";
+  readonly code: "CLI_UNEXPECTED";
+  readonly message: string;
+  readonly cause?: unknown;
+};
+/**
+ * Result type for CLI operations.
+ */
+type CliResult<T> = Result<T, CliError>;
+type CliArgsInvalidError = Extract<CliError, {
+  code: "CLI_ARGS_INVALID";
+}>;
+type CliUnknownCommandError = Extract<CliError, {
+  code: "CLI_UNKNOWN_COMMAND";
+}>;
+type CliUnknownSubcommandError = Extract<CliError, {
+  code: "CLI_UNKNOWN_SUBCOMMAND";
+}>;
+type CliFileExistsError = Extract<CliError, {
+  code: "CLI_FILE_EXISTS";
+}>;
+type CliFileNotFoundError = Extract<CliError, {
+  code: "CLI_FILE_NOT_FOUND";
+}>;
+type CliWriteFailedError = Extract<CliError, {
+  code: "CLI_WRITE_FAILED";
+}>;
+type CliReadFailedError = Extract<CliError, {
+  code: "CLI_READ_FAILED";
+}>;
+type CliNoPatternsError = Extract<CliError, {
+  code: "CLI_NO_PATTERNS";
+}>;
+type CliFormatterNotInstalledError = Extract<CliError, {
+  code: "CLI_FORMATTER_NOT_INSTALLED";
+}>;
+type CliParseErrorError = Extract<CliError, {
+  code: "CLI_PARSE_ERROR";
+}>;
+type CliFormatErrorError = Extract<CliError, {
+  code: "CLI_FORMAT_ERROR";
+}>;
+type CliDuplicateFragmentError = Extract<CliError, {
+  code: "CLI_DUPLICATE_FRAGMENT";
+}>;
+type CliFragmentNotFoundError = Extract<CliError, {
+  code: "CLI_FRAGMENT_NOT_FOUND";
+}>;
+type CliUnexpectedError = Extract<CliError, {
+  code: "CLI_UNEXPECTED";
+}>;
+type CliCodegenError = Extract<CliError, {
+  category: "codegen";
+}>;
+type CliBuilderError = Extract<CliError, {
+  category: "builder";
+}>;
+type CliArtifactError = Extract<CliError, {
+  category: "artifact";
+}>;
+type CliConfigError = Extract<CliError, {
+  category: "config";
+}>;
+type CliTypegenError = Extract<CliError, {
+  category: "typegen";
+}>;
+/**
+ * Error constructor helpers for concise error creation.
+ * Each function returns a specific error type for better type inference.
+ */
+declare const cliErrors: {
+  readonly argsInvalid: (command: string, message: string) => CliArgsInvalidError;
+  readonly unknownCommand: (command: string) => CliUnknownCommandError;
+  readonly unknownSubcommand: (parent: string, subcommand: string) => CliUnknownSubcommandError;
+  readonly fileExists: (filePath: string, message?: string) => CliFileExistsError;
+  readonly fileNotFound: (filePath: string, message?: string) => CliFileNotFoundError;
+  readonly writeFailed: (filePath: string, message?: string, cause?: unknown) => CliWriteFailedError;
+  readonly readFailed: (filePath: string, message?: string, cause?: unknown) => CliReadFailedError;
+  readonly noPatterns: (message?: string) => CliNoPatternsError;
+  readonly formatterNotInstalled: (message?: string) => CliFormatterNotInstalledError;
+  readonly parseError: (message: string, filePath?: string) => CliParseErrorError;
+  readonly formatError: (message: string, filePath?: string) => CliFormatErrorError;
+  readonly duplicateFragment: (fragmentName: string, existingFile: string, newFile: string) => CliDuplicateFragmentError;
+  readonly fragmentNotFound: (fragmentName: string, referencedIn: string) => CliFragmentNotFoundError;
+  readonly unexpected: (message: string, cause?: unknown) => CliUnexpectedError;
+  readonly fromCodegen: (error: CodegenError) => CliCodegenError;
+  readonly fromBuilder: (error: BuilderError) => CliBuilderError;
+  readonly fromArtifact: (error: ArtifactLoadError) => CliArtifactError;
+  readonly fromConfig: (error: ConfigError) => CliConfigError;
+  readonly fromTypegen: (error: TypegenError) => CliTypegenError;
+};
+/**
+ * Convenience helper to create an err Result from CliError.
+ */
+declare const cliErr: <T = never>(error: CliError) => CliResult<T>;
+/**
+ * Type guard to check if error is a CLI-specific error.
+ */
+declare const isCliError: (error: CliError) => error is CliError & {
+  category: "cli";
+};
+/**
+ * Extract error code from any CliError variant.
+ */
+declare const getErrorCode: (error: CliError) => string;
+/**
+ * Extract error message from any CliError variant.
+ */
+declare const getErrorMessage: (error: CliError) => string;
+//#endregion
+//#region packages/tools/src/cli/types.d.ts
+/**
+ * Result type for all CLI commands.
+ */
+type CommandResult<T = CommandSuccess> = Result<T, CliError>;
+/**
+ * Standard success response for commands.
+ */
+type CommandSuccess = {
+  readonly message: string;
+};
+/**
+ * Output format for CLI responses.
+ */
+type OutputFormat = "human" | "json";
+//#endregion
+//#region packages/tools/src/cli/index.d.ts
+type DispatchResult = CommandResult<CommandSuccess & {
+  exitCode?: number;
+}>;
+declare const dispatch: (argv: readonly string[]) => Promise<DispatchResult>;
+//#endregion
+export { dispatch };
+//# sourceMappingURL=bin.d.cts.map