Environment Management

/**
 * Factory function to create Environment instances
 * @param options - Configuration options for the environment
 * @returns Environment instance
 */
function createEnv(options?: EnvironmentOptions): Environment;

import { createEnv } from "yeoman-environment";

// Create with default settings
const env = createEnv();

// Create with custom options
const customEnv = createEnv({
  adapter: myAdapter,
  skipInstall: true,
  logCwd: "/project/logs"
});

/**
 * Main Environment class with full generator lifecycle management
 */
class Environment extends EnvironmentBase {
  constructor(options?: EnvironmentOptions);

  /**
   * Generate help text for available generators
   * @param name - Generator name for specific help
   * @returns Help text string
   */
  help(name?: string): string;

  /**
   * Get all registered generator namespaces
   * @returns Array of namespace strings
   */
  namespaces(): string[];

  /**
   * Get metadata for all registered generators
   * @returns Object mapping namespaces to generator metadata
   */
  getGeneratorsMeta(): Record<string, GeneratorMeta>;

  /**
   * Get names of all registered generators
   * @returns Array of generator names
   */
  getGeneratorNames(): string[];

  /**
   * Get package path for a namespace
   * @param namespace - Generator namespace to look up
   * @returns Package path or undefined if not found
   */
  getPackagePath(namespace: string): string | undefined;

  /**
   * Get all package paths for a namespace
   * @param namespace - Generator namespace to look up
   * @returns Array of package paths
   */
  getPackagePaths(namespace: string): string[];

  /**
   * Execute a generator by namespace with arguments
   * @param generatorNamespace - Namespace of generator to run
   * @param args - Arguments to pass to generator
   */
  execute(generatorNamespace: string, args?: string[]): Promise<void>;

  /**
   * Require and return a generator constructor
   * @param namespace - Generator namespace to require
   * @returns Generator constructor or undefined
   */
  requireGenerator(namespace: string): Promise<BaseGeneratorConstructor | undefined>;

  /**
   * Install local generator packages
   * @param packages - Map of package names to versions
   * @returns True if installation succeeded
   */
  installLocalGenerators(packages: Record<string, string | undefined>): Promise<boolean>;

  /**
   * Lookup and register local packages
   * @param packagesToLookup - Optional array of specific packages to lookup
   */
  lookupLocalPackages(packagesToLookup?: string[]): Promise<void>;

  /**
   * Main run method for executing generators
   * @param args - Arguments for the generator
   * @param options - Options for execution
   */
  run(args?: string[], options?: any): Promise<void>;

  /**
   * Load environment-specific options
   * @param options - Options to load
   * @returns Loaded environment options
   */
  loadEnvironmentOptions(options: EnvironmentOptions): any;

  /**
   * Load options shared with generators
   * @param options - Options to share
   * @returns Loaded shared options
   */
  loadSharedOptions(options: EnvironmentOptions): any;
}

/**
 * Base environment class with core functionality
 */
class EnvironmentBase {
  constructor(options?: EnvironmentOptions);

  /**
   * Find generator metadata by namespace or path
   * @param namespaceOrPath - Generator namespace or path
   * @returns Generator metadata or undefined
   */
  findMeta(namespaceOrPath: string | YeomanNamespace): Promise<GeneratorMeta | undefined>;

  /**
   * Get generator instance by namespace or path
   * @param namespaceOrPath - Generator namespace or path
   * @returns Generator instance or undefined
   */
  get<C>(namespaceOrPath: string | YeomanNamespace): Promise<C | undefined>;

  /**
   * Create generator instance with arguments
   * @param namespaceOrPath - Generator namespace, path, or constructor
   * @param args - Arguments to pass to generator
   * @returns Generator instance
   */
  create<G>(namespaceOrPath: string | GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;

  /**
   * Instantiate generator from constructor
   * @param generator - Generator constructor
   * @param args - Arguments to pass to constructor
   * @returns Generator instance
   */
  instantiate<G>(generator: GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;

  /**
   * Compose with another generator
   * @param generator - Generator to compose with
   * @param args - Arguments for the generator
   * @returns Composed generator instance
   */
  composeWith<G>(generator: string | GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;

  /**
   * Convert filepath to namespace
   * @param filepath - File path to convert
   * @param lookups - Optional lookup paths
   * @returns Generator namespace
   */
  namespace(filepath: string, lookups?: string[]): string;

  /**
   * Get version information for a package
   * @param packageName - Package name (defaults to yeoman-environment)
   * @returns Version string or undefined
   */
  getVersion(packageName?: string): string | undefined;

  /**
   * Queue generator for execution
   * @param generator - Generator to queue
   * @param queueOptions - Queue options
   * @returns Queued generator
   */
  queueGenerator<G>(generator: G, queueOptions?: { schedule?: boolean }): Promise<G>;

  /**
   * Get root generator instance
   * @returns Root generator
   */
  rootGenerator<G>(): G;

  /**
   * Run a generator instance
   * @param generator - Generator to run
   */
  runGenerator(generator: BaseGenerator): Promise<void>;

  /**
   * Register a generator by path or constructor
   * @param pathOrStub - Generator path or constructor
   * @param meta - Optional metadata
   * @returns Generator metadata
   */
  register(pathOrStub: unknown, meta?: Partial<BaseGeneratorMeta>): GeneratorMeta;

  /**
   * Queue a task for execution at specified priority
   * @param priority - Task priority/queue name
   * @param task - Task function to execute
   * @param options - Task options
   */
  queueTask(priority: string, task: () => void | Promise<void>, options?: any): void;

  /**
   * Add custom priority to execution queue
   * @param priority - Priority name
   * @param before - Priority to insert before
   */
  addPriority(priority: string, before?: string): void;

  /**
   * Search for generators
   * @param options - Lookup options
   * @returns Array of found generator metadata
   */
  lookup(options?: EnvironmentLookupOptions): Promise<LookupGeneratorMeta[]>;

  /**
   * Check if package is registered
   * @param packageNamespace - Package namespace to check
   * @returns True if registered
   */
  isPackageRegistered(packageNamespace: string): boolean;

  /**
   * Get all registered package namespaces
   * @returns Array of registered package namespaces
   */
  getRegisteredPackages(): string[];

  /**
   * Get generator metadata by namespace
   * @param namespace - Generator namespace
   * @returns Generator metadata or undefined
   */
  getGeneratorMeta(namespace: string): GeneratorMeta | undefined;

  /**
   * Set or get namespace aliases
   * @param match - String or regex to match
   * @param value - Replacement value (optional for getter)
   * @returns Alias value or this for setter
   */
  alias(match: string | RegExp, value?: string): string | this;

  /**
   * Watch for package manager install operations
   * @param options - Watch options
   */
  watchForPackageManagerInstall(options?: any): void;

  /**
   * Find generators with specific features
   * @param featureName - Feature name to search for
   * @returns Array of generators with the feature
   */
  findFeature(featureName: string): Array<{ generatorId: string; feature: any }>;

  /**
   * Apply transforms to filesystem
   * @param transformStreams - Transform streams to apply
   * @param options - Transform options
   */
  applyTransforms(transformStreams: any[], options?: any): Promise<void>;
}

interface EnvironmentOptions extends BaseEnvironmentOptions {
  /** Custom I/O adapter for input/output operations */
  adapter?: InputOutputAdapter;
  /** Path for logging purposes */
  logCwd?: string;
  /** Command instance for CLI integration */
  command?: YeomanCommand;
  /** Yeoman repository URL */
  yeomanRepository?: string;
  /** Arborist registry URL for npm operations */
  arboristRegistry?: string;
  /** Preferred package manager (npm, yarn, pnpm) */
  nodePackageManager?: string;
  /** Skip dependency installation */
  skipInstall?: boolean;
  /** Force dependency installation */
  forceInstall?: boolean;
  /** Skip prompt answer caching */
  skipCache?: boolean;
  /** Skip local answer caching */
  skipLocalCache?: boolean;
  /** Skip options parsing */
  skipParseOptions?: boolean;
  /** Generate config only locally */
  localConfigOnly?: boolean;
  /** Show prompts for already answered questions */
  askAnswered?: boolean;
}

interface EnvironmentLookupOptions extends LookupOptions {
  /** Add scope to namespace if missing */
  registerToScope?: string;
  /** Customize namespace during registration */
  customizeNamespace?: (ns?: string) => string | undefined;
}