@agiflowai/aicode-utils 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -1,23 +1,100 @@
-//#region src/types/index.d.ts
+import pino from "pino";
+
+//#region src/constants/projectType.d.ts
 /**
- * @agiflowai/aicode-utils - Type Definitions
- *
- * DESIGN PATTERNS:
- * - Interface segregation: Keep interfaces focused and minimal
- * - Type composition: Build complex types from simple primitives
- * - Generics: Use type parameters for reusable, type-safe abstractions
- *
- * CODING STANDARDS:
- * - Use PascalCase for type/interface names
- * - Prefix interfaces with 'I' only for abstract contracts
- * - Document complex types with JSDoc comments
- * - Export all public types
+ * Project type constants
+ */
+declare const ProjectType: {
+  readonly MONOLITH: "monolith";
+  readonly MONOREPO: "monorepo";
+};
+type ProjectType = (typeof ProjectType)[keyof typeof ProjectType];
+/**
+ * Config source constants
+ */
+declare const ConfigSource: {
+  readonly PROJECT_JSON: "project.json";
+  readonly TOOLKIT_YAML: "toolkit.yaml";
+};
+type ConfigSource = (typeof ConfigSource)[keyof typeof ConfigSource];
+//#endregion
+//#region src/types/projectConfig.d.ts
+/**
+ * Result of project config resolution
+ */
+interface ProjectConfigResult {
+  type: ProjectType;
+  sourceTemplate: string;
+  configSource: ConfigSource;
+  workspaceRoot?: string;
+}
+/**
+ * Nx project.json configuration
+ */
+interface NxProjectJson {
+  name: string;
+  $schema?: string;
+  sourceRoot?: string;
+  projectType?: 'application' | 'library';
+  sourceTemplate?: string;
+  targets?: Record<string, unknown>;
+  tags?: string[];
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/services/ProjectConfigResolver.d.ts
+/**
+ * ProjectConfigResolver
  *
- * AVOID:
- * - Any type unless absolutely necessary
- * - Overly complex type gymnastics
- * - Coupling types to implementation details
+ * Resolves project configuration from multiple sources with priority:
+ * 1. project.json (monorepo - Nx/Lerna/Turborepo)
+ * 2. toolkit.yaml at workspace root (monolith)
  */
+declare class ProjectConfigResolver {
+  /**
+   * Resolve project configuration with priority fallback
+   *
+   * Priority order:
+   * 1. Check for project.json (monorepo case)
+   * 2. Check for toolkit.yaml at workspace root (monolith case)
+   * 3. Error with helpful message
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param explicitTemplate - Optional explicit template override
+   * @returns Project configuration result
+   * @throws Error if no configuration found
+   */
+  static resolveProjectConfig(projectPath: string, explicitTemplate?: string): Promise<ProjectConfigResult>;
+  /**
+   * Get helpful error message when no configuration is found
+   */
+  private static getHelpfulErrorMessage;
+  /**
+   * Check if project has configuration (without throwing error)
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @returns true if configuration exists, false otherwise
+   * @throws Error if there's a filesystem error (not just missing config)
+   */
+  static hasConfiguration(projectPath: string): Promise<boolean>;
+  /**
+   * Create toolkit.yaml for monolith projects
+   *
+   * @param sourceTemplate - The template identifier
+   * @param workspaceRoot - Optional workspace root path (defaults to current directory)
+   */
+  static createToolkitYaml(sourceTemplate: string, workspaceRoot?: string): Promise<void>;
+  /**
+   * Create or update project.json for monorepo projects
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param projectName - Name of the project
+   * @param sourceTemplate - The template identifier
+   */
+  static createProjectJson(projectPath: string, projectName: string, sourceTemplate: string): Promise<void>;
+}
+//#endregion
+//#region src/types/index.d.ts
 /**
  * Project configuration from project.json
  */
@@ -185,6 +262,12 @@ declare class ScaffoldProcessingService {
  * - Direct coupling to other services (use dependency injection)
  * - Exposing internal implementation details
  */
+interface ToolkitConfig {
+  version?: string;
+  templatesPath?: string;
+  projectType?: 'monolith' | 'monorepo';
+  sourceTemplate?: string;
+}
 declare class TemplatesManagerService {
   private static SCAFFOLD_CONFIG_FILE;
   private static TEMPLATES_FOLDER;
@@ -237,6 +320,173 @@ declare class TemplatesManagerService {
    * Get the templates folder name
    */
   static getTemplatesFolderName(): string;
+  /**
+   * Read toolkit.yaml configuration from workspace root
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The toolkit configuration object or null if not found
+   */
+  static readToolkitConfig(startPath?: string): Promise<ToolkitConfig | null>;
+  /**
+   * Read toolkit.yaml configuration from workspace root (sync)
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The toolkit configuration object or null if not found
+   */
+  static readToolkitConfigSync(startPath?: string): ToolkitConfig | null;
+  /**
+   * Write toolkit.yaml configuration to workspace root
+   *
+   * @param config - The toolkit configuration to write
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   */
+  static writeToolkitConfig(config: ToolkitConfig, startPath?: string): Promise<void>;
+  /**
+   * Get the workspace root directory
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The workspace root directory path
+   */
+  static getWorkspaceRoot(startPath?: string): Promise<string>;
+  /**
+   * Get the workspace root directory (sync)
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The workspace root directory path
+   */
+  static getWorkspaceRootSync(startPath?: string): string;
 }
 //#endregion
-export { GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, ParsedInclude, ProjectConfig, ProjectFinderService, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService };
+//#region src/utils/logger.d.ts
+declare const logger: pino.Logger<never, boolean>;
+declare const log: {
+  debug: (msg: string, ...args: any[]) => void;
+  info: (msg: string, ...args: any[]) => void;
+  warn: (msg: string, ...args: any[]) => void;
+  error: (msg: string, ...args: any[]) => void;
+};
+//#endregion
+//#region src/utils/print.d.ts
+/**
+ * Themed console utilities for consistent CLI output
+ */
+declare const print: {
+  /**
+   * Log info message (cyan)
+   */
+  info: (message: string) => void;
+  /**
+   * Log success message (green)
+   */
+  success: (message: string) => void;
+  /**
+   * Log warning message (yellow)
+   */
+  warning: (message: string) => void;
+  /**
+   * Log error message (red)
+   */
+  error: (message: string, error?: Error | string) => void;
+  /**
+   * Log debug message (gray)
+   */
+  debug: (message: string) => void;
+  /**
+   * Log section header (bold cyan)
+   */
+  header: (message: string) => void;
+  /**
+   * Log item in a list (gray with prefix)
+   */
+  item: (message: string) => void;
+  /**
+   * Log indented text (gray)
+   */
+  indent: (message: string) => void;
+  /**
+   * Log highlighted text (bold green)
+   */
+  highlight: (message: string) => void;
+  /**
+   * Empty line
+   */
+  newline: () => void;
+};
+/**
+ * Emoji icons for consistent visual markers
+ */
+declare const icons: {
+  rocket: string;
+  check: string;
+  cross: string;
+  warning: string;
+  info: string;
+  package: string;
+  folder: string;
+  file: string;
+  config: string;
+  wrench: string;
+  chart: string;
+  bulb: string;
+  download: string;
+  upload: string;
+  gear: string;
+  clipboard: string;
+  skip: string;
+};
+/**
+ * Themed message helpers
+ */
+declare const messages: {
+  /**
+   * Display an info message with icon
+   */
+  info: (message: string) => void;
+  /**
+   * Display a success message with icon
+   */
+  success: (message: string) => void;
+  /**
+   * Display an error message with icon
+   */
+  error: (message: string, error?: Error | string) => void;
+  /**
+   * Display a warning message with icon
+   */
+  warning: (message: string) => void;
+  /**
+   * Display a hint/tip message with icon
+   */
+  hint: (message: string) => void;
+  /**
+   * Display a loading/processing message with icon
+   */
+  loading: (message: string) => void;
+};
+/**
+ * Section formatters
+ */
+declare const sections: {
+  /**
+   * Print a header section
+   */
+  header: (title: string) => void;
+  /**
+   * Print a list section with title
+   */
+  list: (title: string, items: string[]) => void;
+  /**
+   * Print next steps section
+   */
+  nextSteps: (steps: string[]) => void;
+  /**
+   * Print created files section
+   */
+  createdFiles: (files: string[], maxShow?: number) => void;
+  /**
+   * Print warnings section
+   */
+  warnings: (warnings: string[]) => void;
+};
+//#endregion
+export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, icons, log, logger, messages, print, sections };

package/dist/index.d.ts

@@ -1,23 +1,100 @@
-//#region src/types/index.d.ts
+import pino from "pino";
+
+//#region src/constants/projectType.d.ts
 /**
- * @agiflowai/aicode-utils - Type Definitions
- *
- * DESIGN PATTERNS:
- * - Interface segregation: Keep interfaces focused and minimal
- * - Type composition: Build complex types from simple primitives
- * - Generics: Use type parameters for reusable, type-safe abstractions
- *
- * CODING STANDARDS:
- * - Use PascalCase for type/interface names
- * - Prefix interfaces with 'I' only for abstract contracts
- * - Document complex types with JSDoc comments
- * - Export all public types
+ * Project type constants
+ */
+declare const ProjectType: {
+  readonly MONOLITH: "monolith";
+  readonly MONOREPO: "monorepo";
+};
+type ProjectType = (typeof ProjectType)[keyof typeof ProjectType];
+/**
+ * Config source constants
+ */
+declare const ConfigSource: {
+  readonly PROJECT_JSON: "project.json";
+  readonly TOOLKIT_YAML: "toolkit.yaml";
+};
+type ConfigSource = (typeof ConfigSource)[keyof typeof ConfigSource];
+//#endregion
+//#region src/types/projectConfig.d.ts
+/**
+ * Result of project config resolution
+ */
+interface ProjectConfigResult {
+  type: ProjectType;
+  sourceTemplate: string;
+  configSource: ConfigSource;
+  workspaceRoot?: string;
+}
+/**
+ * Nx project.json configuration
+ */
+interface NxProjectJson {
+  name: string;
+  $schema?: string;
+  sourceRoot?: string;
+  projectType?: 'application' | 'library';
+  sourceTemplate?: string;
+  targets?: Record<string, unknown>;
+  tags?: string[];
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/services/ProjectConfigResolver.d.ts
+/**
+ * ProjectConfigResolver
  *
- * AVOID:
- * - Any type unless absolutely necessary
- * - Overly complex type gymnastics
- * - Coupling types to implementation details
+ * Resolves project configuration from multiple sources with priority:
+ * 1. project.json (monorepo - Nx/Lerna/Turborepo)
+ * 2. toolkit.yaml at workspace root (monolith)
  */
+declare class ProjectConfigResolver {
+  /**
+   * Resolve project configuration with priority fallback
+   *
+   * Priority order:
+   * 1. Check for project.json (monorepo case)
+   * 2. Check for toolkit.yaml at workspace root (monolith case)
+   * 3. Error with helpful message
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param explicitTemplate - Optional explicit template override
+   * @returns Project configuration result
+   * @throws Error if no configuration found
+   */
+  static resolveProjectConfig(projectPath: string, explicitTemplate?: string): Promise<ProjectConfigResult>;
+  /**
+   * Get helpful error message when no configuration is found
+   */
+  private static getHelpfulErrorMessage;
+  /**
+   * Check if project has configuration (without throwing error)
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @returns true if configuration exists, false otherwise
+   * @throws Error if there's a filesystem error (not just missing config)
+   */
+  static hasConfiguration(projectPath: string): Promise<boolean>;
+  /**
+   * Create toolkit.yaml for monolith projects
+   *
+   * @param sourceTemplate - The template identifier
+   * @param workspaceRoot - Optional workspace root path (defaults to current directory)
+   */
+  static createToolkitYaml(sourceTemplate: string, workspaceRoot?: string): Promise<void>;
+  /**
+   * Create or update project.json for monorepo projects
+   *
+   * @param projectPath - Absolute path to the project directory
+   * @param projectName - Name of the project
+   * @param sourceTemplate - The template identifier
+   */
+  static createProjectJson(projectPath: string, projectName: string, sourceTemplate: string): Promise<void>;
+}
+//#endregion
+//#region src/types/index.d.ts
 /**
  * Project configuration from project.json
  */
@@ -185,6 +262,12 @@ declare class ScaffoldProcessingService {
  * - Direct coupling to other services (use dependency injection)
  * - Exposing internal implementation details
  */
+interface ToolkitConfig {
+  version?: string;
+  templatesPath?: string;
+  projectType?: 'monolith' | 'monorepo';
+  sourceTemplate?: string;
+}
 declare class TemplatesManagerService {
   private static SCAFFOLD_CONFIG_FILE;
   private static TEMPLATES_FOLDER;
@@ -237,6 +320,173 @@ declare class TemplatesManagerService {
    * Get the templates folder name
    */
   static getTemplatesFolderName(): string;
+  /**
+   * Read toolkit.yaml configuration from workspace root
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The toolkit configuration object or null if not found
+   */
+  static readToolkitConfig(startPath?: string): Promise<ToolkitConfig | null>;
+  /**
+   * Read toolkit.yaml configuration from workspace root (sync)
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The toolkit configuration object or null if not found
+   */
+  static readToolkitConfigSync(startPath?: string): ToolkitConfig | null;
+  /**
+   * Write toolkit.yaml configuration to workspace root
+   *
+   * @param config - The toolkit configuration to write
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   */
+  static writeToolkitConfig(config: ToolkitConfig, startPath?: string): Promise<void>;
+  /**
+   * Get the workspace root directory
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The workspace root directory path
+   */
+  static getWorkspaceRoot(startPath?: string): Promise<string>;
+  /**
+   * Get the workspace root directory (sync)
+   *
+   * @param startPath - The path to start searching from (defaults to process.cwd())
+   * @returns The workspace root directory path
+   */
+  static getWorkspaceRootSync(startPath?: string): string;
 }
 //#endregion
-export { GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, ParsedInclude, ProjectConfig, ProjectFinderService, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService };
+//#region src/utils/logger.d.ts
+declare const logger: pino.Logger<never, boolean>;
+declare const log: {
+  debug: (msg: string, ...args: any[]) => void;
+  info: (msg: string, ...args: any[]) => void;
+  warn: (msg: string, ...args: any[]) => void;
+  error: (msg: string, ...args: any[]) => void;
+};
+//#endregion
+//#region src/utils/print.d.ts
+/**
+ * Themed console utilities for consistent CLI output
+ */
+declare const print: {
+  /**
+   * Log info message (cyan)
+   */
+  info: (message: string) => void;
+  /**
+   * Log success message (green)
+   */
+  success: (message: string) => void;
+  /**
+   * Log warning message (yellow)
+   */
+  warning: (message: string) => void;
+  /**
+   * Log error message (red)
+   */
+  error: (message: string, error?: Error | string) => void;
+  /**
+   * Log debug message (gray)
+   */
+  debug: (message: string) => void;
+  /**
+   * Log section header (bold cyan)
+   */
+  header: (message: string) => void;
+  /**
+   * Log item in a list (gray with prefix)
+   */
+  item: (message: string) => void;
+  /**
+   * Log indented text (gray)
+   */
+  indent: (message: string) => void;
+  /**
+   * Log highlighted text (bold green)
+   */
+  highlight: (message: string) => void;
+  /**
+   * Empty line
+   */
+  newline: () => void;
+};
+/**
+ * Emoji icons for consistent visual markers
+ */
+declare const icons: {
+  rocket: string;
+  check: string;
+  cross: string;
+  warning: string;
+  info: string;
+  package: string;
+  folder: string;
+  file: string;
+  config: string;
+  wrench: string;
+  chart: string;
+  bulb: string;
+  download: string;
+  upload: string;
+  gear: string;
+  clipboard: string;
+  skip: string;
+};
+/**
+ * Themed message helpers
+ */
+declare const messages: {
+  /**
+   * Display an info message with icon
+   */
+  info: (message: string) => void;
+  /**
+   * Display a success message with icon
+   */
+  success: (message: string) => void;
+  /**
+   * Display an error message with icon
+   */
+  error: (message: string, error?: Error | string) => void;
+  /**
+   * Display a warning message with icon
+   */
+  warning: (message: string) => void;
+  /**
+   * Display a hint/tip message with icon
+   */
+  hint: (message: string) => void;
+  /**
+   * Display a loading/processing message with icon
+   */
+  loading: (message: string) => void;
+};
+/**
+ * Section formatters
+ */
+declare const sections: {
+  /**
+   * Print a header section
+   */
+  header: (title: string) => void;
+  /**
+   * Print a list section with title
+   */
+  list: (title: string, items: string[]) => void;
+  /**
+   * Print next steps section
+   */
+  nextSteps: (steps: string[]) => void;
+  /**
+   * Print created files section
+   */
+  createdFiles: (files: string[], maxShow?: number) => void;
+  /**
+   * Print warnings section
+   */
+  warnings: (warnings: string[]) => void;
+};
+//#endregion
+export { ConfigSource, GeneratorContext, GeneratorFunction, IFileSystemService, IVariableReplacementService, NxProjectJson, ParsedInclude, ProjectConfig, ProjectConfigResolver, ProjectConfigResult, ProjectFinderService, ProjectType, ScaffoldProcessingService, ScaffoldResult, TemplatesManagerService, ToolkitConfig, icons, log, logger, messages, print, sections };