@pixpilot/scaffoldfy 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,468 @@
+//#region src/types.d.ts
+/**
+ * Task Types and Interfaces for Template Initialization
+ */
+interface InitConfig {
+  repoName: string;
+  repoOwner: string;
+  repoUrl: string;
+  author: string;
+  baseRepoUrl: string;
+  orgName: string;
+  [key: string]: unknown;
+}
+/**
+ * Prompt type definitions for task-embedded prompts
+ */
+type PromptType = 'input' | 'select' | 'confirm' | 'password' | 'number';
+/**
+ * Default value types for prompts
+ * - 'value': Static value
+ * - 'execute': Execute a command to get the value
+ */
+type DefaultValueType = 'value' | 'execute';
+/**
+ * Default value configuration for prompts
+ */
+interface DefaultValueConfig<T = string | number | boolean> {
+  type: DefaultValueType;
+  value: T | string;
+}
+/**
+ * Type for default values that can be either static or executable
+ */
+type DefaultValue<T = string | number | boolean> = T | DefaultValueConfig<T>;
+interface BasePrompt {
+  id: string;
+  type: PromptType;
+  message: string;
+  required?: boolean;
+  global?: boolean;
+}
+interface InputPrompt extends BasePrompt {
+  type: 'input' | 'password';
+  default?: DefaultValue<string>;
+  placeholder?: string;
+}
+interface NumberPrompt extends BasePrompt {
+  type: 'number';
+  default?: DefaultValue<number>;
+  min?: number;
+  max?: number;
+}
+interface SelectPrompt extends BasePrompt {
+  type: 'select';
+  choices: Array<{
+    name: string;
+    value: string | number | boolean;
+  }>;
+  default?: DefaultValue<string | number | boolean>;
+}
+interface ConfirmPrompt extends BasePrompt {
+  type: 'confirm';
+  default?: DefaultValue<boolean>;
+}
+type PromptDefinition = InputPrompt | NumberPrompt | SelectPrompt | ConfirmPrompt;
+type TaskType = 'update-json' | 'template' | 'regex-replace' | 'replace-in-file' | 'delete' | 'rename' | 'git-init' | 'exec';
+interface RollbackConfig {
+  type: TaskType;
+  config: unknown;
+}
+interface TaskDefinition {
+  id: string;
+  name: string;
+  description: string;
+  required: boolean;
+  enabled: boolean;
+  type: TaskType;
+  config: unknown;
+  dependencies?: string[];
+  rollback?: RollbackConfig;
+  prompts?: PromptDefinition[];
+}
+interface UpdateJsonConfig {
+  file: string;
+  updates: Record<string, unknown>;
+  condition?: string;
+}
+interface TemplateConfig {
+  file: string;
+  template?: string;
+  templateFile?: string;
+  condition?: string;
+}
+interface RegexReplaceConfig {
+  file: string;
+  pattern: string;
+  flags?: string;
+  replacement: string;
+  condition?: string;
+}
+interface ReplaceInFileConfig {
+  file: string;
+  replacements: Array<{
+    find: string;
+    replace: string;
+  }>;
+  condition?: string;
+}
+interface DeleteConfig {
+  paths: string[];
+  condition?: string;
+}
+interface RenameConfig {
+  from: string;
+  to: string;
+  condition?: string;
+}
+interface GitInitConfig {
+  removeExisting: boolean;
+  initialCommit: boolean;
+  message?: string;
+  condition?: string;
+}
+interface ExecConfig {
+  command: string;
+  cwd?: string;
+  condition?: string;
+}
+interface InitializationMetadata {
+  initializedAt: string;
+  config: InitConfig;
+  completedTasks: string[];
+  version: string;
+}
+/**
+ * Configuration file structure for template tasks
+ */
+interface TasksConfiguration {
+  extends?: string | string[];
+  tasks: TaskDefinition[];
+}
+/**
+ * Plugin interface for custom task types
+ */
+interface TaskPlugin {
+  name: string;
+  version?: string;
+  taskTypes: string[];
+  execute: (task: TaskDefinition, config: InitConfig, options: {
+    dryRun: boolean;
+  }) => Promise<void>;
+  getDiff?: (task: TaskDefinition, config: InitConfig) => Promise<string>;
+  validate?: (task: TaskDefinition) => string[];
+}
+/**
+ * Plugin lifecycle hooks
+ */
+interface PluginHooks {
+  beforeAll?: (config: InitConfig) => Promise<void>;
+  afterAll?: (config: InitConfig) => Promise<void>;
+  beforeTask?: (task: TaskDefinition, config: InitConfig) => Promise<void>;
+  afterTask?: (task: TaskDefinition, config: InitConfig) => Promise<void>;
+  onError?: (error: Error, task?: TaskDefinition) => Promise<void>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Validate the initialization configuration
+ */
+declare function validateConfig(config: InitConfig): string[];
+/**
+ * Collect configuration from user interactively
+ */
+declare function collectConfig(dryRun?: boolean): Promise<InitConfig>;
+//#endregion
+//#region src/dry-run.d.ts
+/**
+ * Get diff for update-json task
+ */
+declare function getUpdateJsonDiff(config: UpdateJsonConfig, initConfig: InitConfig): Promise<string>;
+/**
+ * Get diff for template task
+ */
+declare function getTemplateDiff(config: TemplateConfig, initConfig: InitConfig): Promise<string>;
+/**
+ * Get diff for regex-replace task
+ */
+declare function getRegexReplaceDiff(config: RegexReplaceConfig, initConfig: InitConfig): Promise<string>;
+/**
+ * Get diff for replace-in-file task
+ */
+declare function getReplaceInFileDiff(config: ReplaceInFileConfig, initConfig: InitConfig): Promise<string>;
+/**
+ * Get diff for delete task
+ */
+declare function getDeleteDiff(config: DeleteConfig, initConfig: InitConfig): string;
+/**
+ * Get diff for rename task
+ */
+declare function getRenameDiff(config: RenameConfig, initConfig: InitConfig): string;
+/**
+ * Get diff for git-init task
+ */
+declare function getGitInitDiff(config: GitInitConfig): string;
+/**
+ * Get diff for exec task
+ */
+declare function getExecDiff(config: ExecConfig, initConfig: InitConfig): string;
+/**
+ * Get diff for any task type
+ */
+declare function getTaskDiff(task: TaskDefinition, initConfig: InitConfig): Promise<string>;
+/**
+ * Display diffs for all tasks
+ */
+declare function displayTasksDiff(tasks: TaskDefinition[], initConfig: InitConfig): Promise<void>;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Register a plugin
+ * @param plugin - The plugin to register
+ */
+declare function registerPlugin(plugin: TaskPlugin): void;
+/**
+ * Unregister a plugin
+ * @param pluginName - Name of the plugin to unregister
+ */
+declare function unregisterPlugin(pluginName: string): void;
+/**
+ * Get a plugin by name
+ * @param pluginName - Name of the plugin
+ * @returns The plugin or undefined if not found
+ */
+declare function getPlugin(pluginName: string): TaskPlugin | undefined;
+/**
+ * Get a plugin for a task type
+ * @param taskType - The task type
+ * @returns The plugin or undefined if not found
+ */
+declare function getPluginForTaskType(taskType: string): TaskPlugin | undefined;
+/**
+ * Check if a task type is handled by a plugin
+ * @param taskType - The task type to check
+ * @returns True if a plugin handles this task type
+ */
+declare function isPluginTaskType(taskType: string): boolean;
+/**
+ * List all registered plugins
+ * @returns Array of plugin names
+ */
+declare function listPlugins(): string[];
+/**
+ * Clear all registered plugins (useful for testing)
+ */
+declare function clearPlugins(): void;
+/**
+ * Register global lifecycle hooks
+ * @param hooks - Hook functions to register
+ */
+declare function registerHooks(hooks: Partial<PluginHooks>): void;
+/**
+ * Call a lifecycle hook
+ * @param hookName - Name of the hook
+ * @param config - Initialization config for beforeAll/afterAll
+ */
+declare function callHook(hookName: 'beforeAll' | 'afterAll', config: InitConfig): Promise<void>;
+/**
+ * Call a lifecycle hook
+ * @param hookName - Name of the hook
+ * @param task - Task definition for beforeTask/afterTask
+ * @param config - Initialization config
+ */
+declare function callHook(hookName: 'beforeTask' | 'afterTask', task: TaskDefinition, config: InitConfig): Promise<void>;
+/**
+ * Call a lifecycle hook
+ * @param hookName - Name of the hook
+ * @param error - Error that occurred
+ * @param task - Optional task definition
+ */
+declare function callHook(hookName: 'onError', error: Error, task?: TaskDefinition): Promise<void>;
+/**
+ * Execute a plugin task
+ * @param task - The task to execute
+ * @param config - The initialization config
+ * @param options - Execution options
+ * @param options.dryRun - Whether to run in dry-run mode
+ * @returns Promise that resolves when the task is complete
+ */
+declare function executePluginTask(task: TaskDefinition, config: InitConfig, options: {
+  dryRun: boolean;
+}): Promise<void>;
+/**
+ * Get diff for a plugin task
+ * @param task - The task to generate diff for
+ * @param config - The initialization config
+ * @returns Diff string or undefined if not supported
+ */
+declare function getPluginTaskDiff(task: TaskDefinition, config: InitConfig): Promise<string | undefined>;
+/**
+ * Validate a plugin task
+ * @param task - The task to validate
+ * @returns Array of validation errors
+ */
+declare function validatePluginTask(task: TaskDefinition): string[];
+/**
+ * Create a simple plugin
+ * @param name - Plugin name
+ * @param taskType - Task type this plugin handles
+ * @param execute - Execute function
+ * @param options - Optional configuration
+ * @param options.version - Plugin version
+ * @param options.getDiff - Function to generate diff preview
+ * @param options.validate - Function to validate task configuration
+ * @returns A TaskPlugin object
+ */
+declare function createPlugin(name: string, taskType: string, execute: (task: TaskDefinition, config: InitConfig, options: {
+  dryRun: boolean;
+}) => Promise<void>, options?: {
+  version?: string;
+  getDiff?: (task: TaskDefinition, config: InitConfig) => Promise<string>;
+  validate?: (task: TaskDefinition) => string[];
+}): TaskPlugin;
+//#endregion
+//#region src/prompts.d.ts
+/**
+ * Resolve a default value that may be static or executable
+ * @param defaultValue - The default value configuration
+ * @param promptId - The prompt ID for error reporting
+ * @returns The resolved default value
+ */
+declare function resolveDefaultValue<T = string | number | boolean>(defaultValue: DefaultValue<T> | undefined, promptId: string): Promise<T | undefined>;
+/**
+ * Pre-resolve all executable default values in parallel
+ * @param prompts - Array of prompt definitions
+ * @returns Map of prompt IDs to their resolved default values
+ */
+declare function resolveAllDefaultValues(prompts: PromptDefinition[]): Promise<Map<string, unknown>>;
+/**
+ * Collect prompt answers from task-defined prompts
+ * @param prompts - Array of prompt definitions from tasks
+ * @param resolvedDefaults - Map of pre-resolved default values
+ * @returns Object mapping prompt IDs to their values
+ */
+declare function collectPrompts(prompts: PromptDefinition[], resolvedDefaults?: Map<string, unknown>): Promise<Record<string, unknown>>;
+/**
+ * Validate prompt definitions
+ * @param prompts - Array of prompt definitions to validate
+ * @returns Array of validation error messages
+ */
+declare function validatePrompts(prompts: PromptDefinition[]): string[];
+//#endregion
+//#region src/state.d.ts
+/**
+ * Load initialization state from file
+ */
+declare function loadInitializationState(): InitializationMetadata | null;
+/**
+ * Save initialization state to file
+ */
+declare function saveInitializationState(config: InitConfig, completedTasks: string[], dryRun?: boolean): void;
+//#endregion
+//#region src/task-executors.d.ts
+/**
+ * Execute a task based on its type
+ */
+declare function executeTask(task: TaskDefinition, config: InitConfig, dryRun?: boolean): Promise<void>;
+/**
+ * Run a single task with error handling
+ */
+declare function runTask(task: TaskDefinition, config: InitConfig, taskNumber: number, totalTasks: number, dryRun?: boolean): Promise<boolean>;
+//#endregion
+//#region src/task-resolver.d.ts
+/**
+ * Sort tasks by dependencies using topological sort
+ */
+declare function topologicalSort(tasks: TaskDefinition[]): TaskDefinition[];
+//#endregion
+//#region src/template-inheritance.d.ts
+/**
+ * Load a template configuration file
+ * @param templatePath - Path to the template file
+ * @param visitedPaths - Set of already visited paths to detect circular dependencies
+ * @returns The loaded template configuration
+ */
+declare function loadTemplate(templatePath: string, visitedPaths?: Set<string>): Promise<TasksConfiguration>;
+/**
+ * Recursively load and merge templates
+ * @param templatePath - Path to the template file
+ * @param baseDir - Base directory for resolving relative paths in extends
+ * @param visitedPaths - Set of already visited paths
+ * @returns Merged template configuration
+ */
+declare function loadAndMergeTemplate(templatePath: string, baseDir?: string, visitedPaths?: Set<string>): Promise<TasksConfiguration>;
+/**
+ * Merge multiple template configurations
+ * Later templates override earlier ones for conflicting task IDs
+ * @param templates - Array of templates to merge (in priority order)
+ * @returns Merged template configuration
+ */
+declare function mergeTemplates(templates: TasksConfiguration[]): TasksConfiguration;
+/**
+ * Clear the template cache (useful for testing)
+ */
+declare function clearTemplateCache(): void;
+/**
+ * Load tasks from a configuration file with template inheritance support
+ * @param tasksFilePath - Path to the tasks configuration file
+ * @returns Array of task definitions
+ */
+declare function loadTasksWithInheritance(tasksFilePath: string): Promise<TaskDefinition[]>;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Get Git repository information from the current directory
+ */
+declare function getGitRepoInfo(): {
+  owner: string;
+  name: string;
+  url: string;
+} | null;
+/**
+ * Prompt user for input with optional default value
+ */
+declare function prompt(question: string, defaultValue?: string): Promise<string>;
+/**
+ * Prompt user for yes/no answer
+ */
+declare function promptYesNo(question: string, defaultValue?: boolean): Promise<boolean>;
+/**
+ * Log message with colored output
+ */
+declare function log(message: string, type?: 'info' | 'success' | 'error' | 'warn'): void;
+/**
+ * Interpolate template variables in a string
+ */
+declare function interpolateTemplate(template: string, config: InitConfig): string;
+/**
+ * Set a nested property in an object using dot notation
+ */
+declare function setNestedProperty(obj: Record<string, unknown>, propertyPath: string, value: unknown): void;
+/**
+ * Evaluate a condition expression with the given config
+ */
+declare function evaluateCondition(condition: string, config: InitConfig): boolean;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Main function for running initialization with default/empty tasks
+ * For most use cases, you should use runWithTasks() with your custom tasks
+ */
+declare function main(customTasks?: TaskDefinition[]): Promise<void>;
+/**
+ * Run initialization with custom tasks
+ * @param customTasks - Array of task definitions to execute
+ * @param options - Optional configuration
+ * @param options.dryRun - Preview changes without applying them
+ * @param options.force - Force re-initialization even if already initialized
+ * @param options.keepTasksFile - Whether to keep the tasks file after initialization
+ * @param options.tasksFilePath - Path to the tasks file
+ */
+declare function runWithTasks(customTasks: TaskDefinition[], options?: {
+  dryRun?: boolean | undefined;
+  force?: boolean | undefined;
+  keepTasksFile?: boolean | undefined;
+  tasksFilePath?: string | undefined;
+}): Promise<void>;
+//#endregion
+export { BasePrompt, ConfirmPrompt, DefaultValue, DefaultValueConfig, DefaultValueType, DeleteConfig, ExecConfig, GitInitConfig, InitConfig, InitializationMetadata, InputPrompt, NumberPrompt, PluginHooks, PromptDefinition, PromptType, RegexReplaceConfig, RenameConfig, ReplaceInFileConfig, RollbackConfig, SelectPrompt, TaskDefinition, TaskPlugin, TaskType, TasksConfiguration, TemplateConfig, UpdateJsonConfig, callHook, clearPlugins, clearTemplateCache, collectConfig, collectPrompts, createPlugin, displayTasksDiff, evaluateCondition, executePluginTask, executeTask, getDeleteDiff, getExecDiff, getGitInitDiff, getGitRepoInfo, getPlugin, getPluginForTaskType, getPluginTaskDiff, getRegexReplaceDiff, getRenameDiff, getReplaceInFileDiff, getTaskDiff, getTemplateDiff, getUpdateJsonDiff, interpolateTemplate, isPluginTaskType, listPlugins, loadAndMergeTemplate, loadInitializationState, loadTasksWithInheritance, loadTemplate, log, main, mergeTemplates, prompt, promptYesNo, registerHooks, registerPlugin, resolveAllDefaultValues, resolveDefaultValue, runTask, runWithTasks, saveInitializationState, setNestedProperty, topologicalSort, unregisterPlugin, validateConfig, validatePluginTask, validatePrompts };