@secondlayer/cli 3.3.0 → 3.3.2

package/dist/plugins/index.d.ts

@@ -0,0 +1,364 @@
+import { AbiContract as AbiContract2 } from "@secondlayer/stacks/clarity";
+import { AbiContract } from "@secondlayer/stacks/clarity";
+/** Supported Stacks network identifiers for contract resolution. */
+type NetworkName = "mainnet" | "testnet" | "devnet";
+/** Specifies a contract to generate typed interfaces for, either from a deployed address or local Clarity source file. */
+interface ContractSource {
+	/**
+	* Contract identifier (address.name) for deployed contracts
+	*/
+	address?: string | Partial<Record<NetworkName, string>>;
+	/**
+	* Path to local Clarity file
+	*/
+	source?: string;
+	/**
+	* Optional name to use in generated code
+	*/
+	name?: string;
+}
+/** Configuration for the `@secondlayer/cli` code generator. Defines which contracts to process, output paths, network settings, and plugins. */
+interface SecondLayerConfig {
+	/**
+	* Contracts to generate interfaces for (optional - plugins can provide these)
+	*/
+	contracts?: ContractSource[];
+	/**
+	* Output file path
+	*/
+	out: string;
+	/**
+	* Plugins to use for generation
+	*/
+	plugins?: any[];
+	/**
+	* Network to use for fetching contracts
+	*/
+	network?: NetworkName;
+	/**
+	* API key for Stacks API (if required)
+	*/
+	apiKey?: string;
+	/**
+	* Base URL for Stacks API (optional override)
+	*/
+	apiUrl?: string;
+	/**
+	* Default deployer address for local contracts without explicit addresses
+	* Defaults to ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM (devnet default)
+	*/
+	defaultAddress?: string;
+}
+interface ResolvedContract {
+	name: string;
+	address: string;
+	contractName: string;
+	abi: AbiContract;
+	source: "api" | "local";
+}
+/**
+* Core plugin interface that all plugins must implement
+*/
+interface SecondLayerPlugin {
+	/** Plugin name (should be unique) */
+	name: string;
+	/** Plugin version */
+	version: string;
+	/** Called after config is resolved but before generation starts */
+	configResolved?: (config: ResolvedConfig) => void | Promise<void>;
+	/** Called before generation starts */
+	beforeGenerate?: (context: GenerateContext) => void | Promise<void>;
+	/** Called during generation phase - plugins can add their own outputs */
+	generate?: (context: GenerateContext) => void | Promise<void>;
+	/** Called after all generation is complete */
+	afterGenerate?: (context: GenerateContext) => void | Promise<void>;
+	/** Transform user config before resolution */
+	transformConfig?: (config: UserConfig) => UserConfig | Promise<UserConfig>;
+	/** Transform individual contracts during processing */
+	transformContract?: (contract: ContractConfig) => ContractConfig | Promise<ContractConfig>;
+	/** Transform generated output before writing to disk */
+	transformOutput?: (output: string, type: OutputType) => string | Promise<string>;
+}
+/**
+* User configuration (before plugin transformations)
+*/
+type UserConfig = SecondLayerConfig;
+/**
+* Resolved configuration (after plugin transformations)
+*/
+interface ResolvedConfig extends SecondLayerConfig {
+	/** Resolved plugins array */
+	plugins: SecondLayerPlugin[];
+}
+/**
+* Contract configuration that can be transformed by plugins
+*/
+interface ContractConfig {
+	name?: string;
+	address?: string | Partial<Record<NetworkName, string>>;
+	source?: string;
+	abi?: AbiContract2;
+	metadata?: Record<string, any>;
+}
+/**
+* Processed contract with resolved ABI and metadata
+*/
+interface ProcessedContract extends ResolvedContract {
+	/** Additional metadata added by plugins */
+	metadata?: Record<string, any>;
+}
+/**
+* Generated output from plugins
+*/
+interface GeneratedOutput {
+	/** File path where output should be written */
+	path: string;
+	/** Generated content */
+	content: string;
+	/** Output type for transformation hooks */
+	type?: OutputType;
+	/** Whether this output should overwrite existing files */
+	overwrite?: boolean;
+}
+/**
+* Types of outputs that can be generated
+*/
+type OutputType = "contracts" | "hooks" | "actions" | "types" | "utils" | "config" | "other";
+/**
+* Base context available to all plugin hooks
+*/
+interface PluginContext {
+	/** Resolved configuration */
+	config: ResolvedConfig;
+	/** Logger for plugin output */
+	logger: Logger;
+	/** Utility functions for plugins */
+	utils: PluginUtils;
+}
+/**
+* Context available during generation phase
+*/
+interface GenerateContext extends PluginContext {
+	/** Processed contracts ready for generation */
+	contracts: ProcessedContract[];
+	/** Map of output keys to generated content */
+	outputs: Map<string, GeneratedOutput>;
+	/** Function to augment existing outputs */
+	augment: (outputKey: string, contractName: string, content: any) => void;
+	/** Function to add new outputs */
+	addOutput: (key: string, output: GeneratedOutput) => void;
+}
+/**
+* Logger interface for plugin output
+*/
+interface Logger {
+	info: (message: string) => void;
+	warn: (message: string) => void;
+	error: (message: string) => void;
+	debug: (message: string) => void;
+	success: (message: string) => void;
+}
+/**
+* Utility functions available to plugins
+*/
+interface PluginUtils {
+	/** Convert kebab-case to camelCase */
+	toCamelCase: (str: string) => string;
+	/** Convert camelCase to kebab-case */
+	toKebabCase: (str: string) => string;
+	/** Validate Stacks address format */
+	validateAddress: (address: string) => boolean;
+	/** Parse contract identifier (address.contract-name) */
+	parseContractId: (contractId: string) => {
+		address: string
+		contractName: string
+	};
+	/** Format TypeScript code using prettier */
+	formatCode: (code: string) => Promise<string>;
+	/** Resolve file path relative to project root */
+	resolvePath: (relativePath: string) => string;
+	/** Check if file exists */
+	fileExists: (path: string) => Promise<boolean>;
+	/** Read file content */
+	readFile: (path: string) => Promise<string>;
+	/** Write file content */
+	writeFile: (path: string, content: string) => Promise<void>;
+	/** Create directory recursively */
+	ensureDir: (path: string) => Promise<void>;
+}
+/**
+* Plugin factory function type for creating plugins with options
+*/
+type PluginFactory<TOptions = any> = (options?: TOptions) => SecondLayerPlugin;
+/**
+* Plugin options base interface
+*/
+interface PluginOptions {
+	/** Include only specific contracts/functions */
+	include?: string[];
+	/** Exclude specific contracts/functions */
+	exclude?: string[];
+	/** Enable debug output */
+	debug?: boolean;
+}
+/**
+* Hook execution result
+*/
+interface HookResult<T = any> {
+	/** Whether the hook was successful */
+	success: boolean;
+	/** Result data from the hook */
+	data?: T;
+	/** Error if hook failed */
+	error?: Error;
+	/** Plugin that executed the hook */
+	plugin: string;
+}
+/**
+* Core plugin manager that orchestrates plugin execution
+*/
+declare class PluginManager {
+	private plugins;
+	private logger;
+	private utils;
+	private executionContext;
+	constructor();
+	/**
+	* Register a plugin
+	*/
+	register(plugin: SecondLayerPlugin): void;
+	/**
+	* Get all registered plugins
+	*/
+	getPlugins(): SecondLayerPlugin[];
+	/**
+	* Transform user config through all plugins
+	*/
+	transformConfig(config: UserConfig): Promise<ResolvedConfig>;
+	/**
+	* Transform contracts through all plugins
+	*/
+	transformContracts(contracts: ContractConfig[], _config: ResolvedConfig): Promise<ProcessedContract[]>;
+	/**
+	* Execute lifecycle hooks
+	*/
+	executeHook(hookName: keyof SecondLayerPlugin, context: any): Promise<void>;
+	/**
+	* Execute generation phase with full context
+	*/
+	executeGeneration(contracts: ProcessedContract[], config: ResolvedConfig): Promise<Map<string, GeneratedOutput>>;
+	/**
+	* Transform outputs through plugins
+	*/
+	transformOutputs(outputs: Map<string, GeneratedOutput>): Promise<Map<string, GeneratedOutput>>;
+	/**
+	* Write outputs to disk
+	*/
+	writeOutputs(outputs: Map<string, GeneratedOutput>): Promise<void>;
+	/**
+	* Get execution results for debugging
+	*/
+	getExecutionResults(): Map<string, HookResult[]>;
+	/**
+	* Convert a contract config with an ABI into a ProcessedContract
+	*/
+	private contractToProcessed;
+	/**
+	* Augment existing output with additional content
+	*/
+	private augmentOutput;
+	/**
+	* Record hook execution result
+	*/
+	private recordHookResult;
+	/**
+	* Create logger instance
+	*/
+	private createLogger;
+	/**
+	* Create utils instance
+	*/
+	private createUtils;
+}
+interface ClarinetPluginOptions {
+	/** Path to Clarinet.toml file */
+	path?: string;
+	/** Include only specific contracts */
+	include?: string[];
+	/** Exclude specific contracts */
+	exclude?: string[];
+	/** Enable debug output */
+	debug?: boolean;
+}
+/**
+* Clarinet plugin factory
+*/
+declare const clarinet: PluginFactory<ClarinetPluginOptions>;
+/**
+* Utility function to check if a Clarinet project exists
+*/
+declare function hasClarinetProject(path?: string): Promise<boolean>;
+interface ActionsPluginOptions {
+	/** Include only specific contracts */
+	include?: string[];
+	/** Exclude specific contracts */
+	exclude?: string[];
+	/** Include only specific functions */
+	includeFunctions?: string[];
+	/** Exclude specific functions */
+	excludeFunctions?: string[];
+	/** Enable debug output */
+	debug?: boolean;
+	/** Environment variable name for default sender key (default: "STX_SENDER_KEY") */
+	senderKeyEnv?: string;
+}
+/**
+* Actions plugin factory
+*/
+declare const actions: PluginFactory<ActionsPluginOptions>;
+/**
+* React plugin configuration options
+*/
+interface ReactPluginOptions extends PluginOptions {
+	/**
+	* Hooks to exclude from generation (both generic and contract-specific)
+	* By default, all hooks are generated
+	*/
+	exclude?: string[];
+}
+/**
+* React plugin factory
+*/
+declare const react: PluginFactory<ReactPluginOptions>;
+interface TestingPluginOptions {
+	/** Include only specific contracts */
+	include?: string[];
+	/** Exclude specific contracts */
+	exclude?: string[];
+	/** Output path for generated testing helpers (default: ./src/generated/testing.ts) */
+	out?: string;
+	/** Include private function helpers (default: false) */
+	includePrivate?: boolean;
+	/** Enable debug output */
+	debug?: boolean;
+}
+declare const testing: PluginFactory<TestingPluginOptions>;
+interface BasePluginOptions {
+	/** Include only specific contracts/functions */
+	include?: string[];
+	/** Exclude specific contracts/functions */
+	exclude?: string[];
+	/** Enable debug output */
+	debug?: boolean;
+}
+/**
+* Utility function to filter contracts/functions based on include/exclude options
+*/
+declare function filterByOptions<T extends {
+	name: string
+}>(items: T[], options?: BasePluginOptions): T[];
+/**
+* Utility function to create a simple plugin
+*/
+declare function createPlugin(name: string, version: string, implementation: Partial<SecondLayerPlugin>): SecondLayerPlugin;
+export { testing, react, hasClarinetProject, filterByOptions, createPlugin, clarinet, actions, TestingPluginOptions, SecondLayerPlugin, ReactPluginOptions, PluginUtils, PluginOptions, PluginManager, PluginFactory, PluginContext, Logger, GenerateContext, ClarinetPluginOptions, BasePluginOptions, ActionsPluginOptions };