@dxtmisha/scripts 0.7.10 → 0.7.11

package/src/classes/BrowserItem.ts

@@ -0,0 +1,375 @@
+import {
+  type Browser,
+  type EvaluateFunc,
+  type HTTPResponse,
+  launch,
+  type Page,
+  type PuppeteerLifeCycleEvent
+} from 'puppeteer'
+import { sleep } from '@dxtmisha/functional-basic'
+
+import {
+  type ScreenshotMetrics,
+  type ScreenshotOptions,
+  SCREENSHOT_ARGS,
+  SCREENSHOT_FORMAT,
+  SCREENSHOT_HEIGHTS,
+  SCREENSHOT_TIMEOUT,
+  SCREENSHOT_QUALITY,
+  SCREENSHOT_WAIT_UNTIL,
+  SCREENSHOT_WIDTHS
+} from '../types/screenshotTypes'
+
+/**
+ * Class for managing browser instances and taking screenshots using Puppeteer.
+ *
+ * Класс для управления экземплярами браузера и создания скриншотов с помощью Puppeteer.
+ */
+export class BrowserItem {
+  /** Browser instance / Экземпляр браузера */
+  protected browser?: Browser
+
+  /** Page instance / Экземпляр страницы */
+  protected page?: Page
+
+  /** HTTP Response from page loading / HTTP-ответ при загрузке страницы */
+  protected response?: HTTPResponse
+
+  /** Total scrollable width of the loaded page / Полная прокручиваемая ширина загруженной страницы */
+  protected pageWidth: number = -1
+
+  /** Total scrollable height of the loaded page / Полная прокручиваемая высота загруженной страницы */
+  protected pageHeight: number = -1
+
+  /**
+   * Constructor
+   * @param url component path / путь к компоненту
+   * @param options additional options for capture / дополнительные опции захвата
+   */
+  constructor(
+    protected url: string,
+    protected readonly options: ScreenshotOptions = {}
+  ) {
+  }
+
+  /** Additional arguments for browser launch / Дополнительные аргументы для запуска браузера */
+  get args(): string[] {
+    return this.options.args ?? SCREENSHOT_ARGS
+  }
+
+  /** Condition to wait for when navigating to the page / Условие, которое нужно дождаться при переходе на страницу */
+  get waitUntil(): PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[] {
+    return this.options.waitUntil ?? SCREENSHOT_WAIT_UNTIL
+  }
+
+  /** Timeout for navigating to the page / Таймаут для перехода на страницу */
+  get timeout(): number {
+    return this.options.timeout ?? SCREENSHOT_TIMEOUT
+  }
+
+  /** Image format for screenshots / Формат изображения для скриншотов */
+  get format(): ScreenshotOptions['format'] {
+    return this.options.format ?? SCREENSHOT_FORMAT
+  }
+
+  /** Viewport width for the initial capture / Ширина порта просмотра для начального захвата */
+  get width(): number {
+    return this.options.width ?? SCREENSHOT_WIDTHS
+  }
+
+  /** Viewport height for the initial capture and page-by-page slicing / Высота порта просмотра для начального захвата и постраничной нарезки */
+  get height(): number {
+    return this.options.height ?? SCREENSHOT_HEIGHTS
+  }
+
+  /** Quality for JPEG/WebP formats (0-100) / Качество для форматов JPEG/WebP (0-100) */
+  get quality(): number {
+    return this.options.quality ?? SCREENSHOT_QUALITY
+  }
+
+  /** Whether to capture the whole scrollable page at once or in slices / Захватывать ли всю прокручиваемую страницу сразу или по частям */
+  get fullPage(): boolean {
+    return this.options.fullPage ?? false
+  }
+
+  /** File extension based on the selected format / Расширение файла на основе выбранного формата */
+  get extension(): string {
+    const format = this.format
+
+    if (format === 'jpeg') {
+      return '.jpg'
+    }
+
+    return `.${format}`
+  }
+
+  /**
+   * launches or returns the browser instance.
+   *
+   * Запускает или возвращает экземпляр браузера.
+   * @returns browser instance / экземпляр браузера
+   */
+  async getBrowser(): Promise<Browser> {
+    if (!this.browser) {
+      this.browser = await launch({
+        headless: true,
+        args: this.args
+      })
+    }
+
+    return this.browser
+  }
+
+  /**
+   * Creates or returns the page instance.
+   *
+   * Создает или возвращает экземпляр страницы.
+   * @returns page instance / экземпляр страницы
+   */
+  async getPage(): Promise<Page> {
+    if (!this.page) {
+      this.page = await (await this.getBrowser()).newPage()
+
+      await this.page.setViewport({
+        width: this.width,
+        height: this.height
+      })
+
+      this.page.on(
+        'console',
+        msg => this.toConsole(`Log: ${msg.text()}`)
+      )
+
+      this.page.on(
+        'pageerror',
+        err => this.toConsole(`Error: ${(err as any)?.message}`)
+      )
+    }
+
+    return this.page
+  }
+
+  /**
+   * Navigates to the URL and returns the HTTP response.
+   *
+   * Переходит по URL и возвращает HTTP-ответ.
+   * @returns HTTP response or undefined / HTTP-ответ или undefined
+   */
+  async getResponse(): Promise<HTTPResponse | undefined> {
+    if (!this.response) {
+      const response = await (await this.getPage()).goto(this.url, {
+        waitUntil: this.waitUntil,
+        timeout: this.timeout
+      })
+
+      if (
+        response
+        && response.ok()
+      ) {
+        this.response = response
+      } else {
+        this.toConsole(
+          `Failed to load page: ${this.url}. Status: ${response?.status()}`
+        )
+      }
+    }
+
+    return this.response
+  }
+
+  /**
+   * Retrieves the HTML content of the page.
+   *
+   * Извлекает HTML-содержимое страницы.
+   * @returns html content string / HTML-содержимое
+   */
+  async getDom(): Promise<string> {
+    return await (await this.getPage()).content()
+  }
+
+  /**
+   * Extracts scrollable dimensions of the page.
+   *
+   * Извлекает прокручиваемые размеры страницы.
+   * @returns object with width and height / объект с шириной и высотой
+   */
+  async getMetrics(): Promise<ScreenshotMetrics> {
+    if (
+      await this.getResponse()
+      && (
+        this.pageWidth === -1
+        || this.pageHeight === -1
+      )
+    ) {
+      const metrics = await this.evaluate(() => {
+        return {
+          height: document.documentElement.scrollHeight,
+          width: document.documentElement.scrollWidth
+        }
+      })
+
+      if (metrics) {
+        this.pageWidth = metrics.width
+        this.pageHeight = metrics.height
+      }
+    }
+
+    return {
+      height: this.pageHeight,
+      width: this.pageWidth
+    }
+  }
+
+  /**
+   * Evaluates a function in the browser context.
+   *
+   * Выполняет функцию в контексте браузера.
+   * @param pageFunction function to evaluate / функция для выполнения
+   * @param args arguments for the function / аргументы для функции
+   * @returns result of evaluation / результат выполнения
+   */
+  async evaluate<
+    Params extends unknown[],
+    Func extends EvaluateFunc<Params> = EvaluateFunc<Params>
+  >(
+    pageFunction: Func | string,
+    ...args: Params
+  ): Promise<Awaited<ReturnType<Func>> | undefined> {
+    return await (await this.getPage()).evaluate<Params, Func>(
+      pageFunction,
+      ...args
+    )
+  }
+
+  /**
+   * Captures screenshots based on the fullPage option.
+   *
+   * Создает скриншоты в зависимости от опции fullPage.
+   * @param outputPath base path for saving / базовый путь для сохранения
+   * @returns this instance / этот экземпляр
+   */
+  async screenshot(outputPath: string): Promise<this> {
+    if (this.fullPage) {
+      await this.screenshotFull(outputPath)
+    } else {
+      await this.screenshotPages(outputPath)
+    }
+
+    return this
+  }
+
+  /**
+   * Resets internal page and response states.
+   *
+   * Сбрасывает состояние страницы и ответа.
+   * @returns this instance / этот экземпляр
+   */
+  async reset(): Promise<this> {
+    this.page = undefined
+    this.pageWidth = -1
+    this.pageHeight = -1
+
+    this.response = undefined
+
+    return this
+  }
+
+  /**
+   * Formats the final file path based on current state and index.
+   *
+   * Форматирует итоговый путь к файлу на основе состояния и индекса.
+   * @param outputPath original output path / исходный путь сохранения
+   * @param index current page index / текущий индекс страницы
+   * @param max total pages count / общее количество страниц
+   * @returns formatted path string / отформатированная строка пути
+   */
+  protected getOutputPath(
+    outputPath: string,
+    index: number = 1,
+    max: number = 1
+  ): string {
+    if (this.fullPage) {
+      return outputPath + this.extension
+    }
+
+    return outputPath + `-${max}_${index}` + this.extension
+  }
+
+  /**
+   * Internal wrapper for Puppeteer's screenshot method.
+   *
+   * Внутренняя обертка для метода скриншота Puppeteer.
+   * @param path specific file path / путь к конкретному файлу
+   * @returns this instance / этот экземпляр
+   */
+  protected async saveScreenshot(path: string): Promise<this> {
+    const type = this.format
+    const quality = type === 'png' ? undefined : this.quality
+
+    await (await this.getPage()).screenshot({
+      path,
+      type,
+      quality,
+      fullPage: this.fullPage
+    })
+
+    return this
+  }
+
+  /**
+   * Iterates through page slices and saves multiple screenshots.
+   *
+   * Проходит по частям страницы и сохраняет несколько скриншотов.
+   * @param outputPath base output path / базовый путь сохранения
+   * @returns this instance / этот экземпляр
+   */
+  protected async screenshotPages(outputPath: string): Promise<this> {
+    const {
+      height: pageHeight
+    } = await this.getMetrics()
+
+    const viewportHeight = this.height
+    const pages = Math.ceil(pageHeight / viewportHeight)
+
+    this.toConsole(`Page height: ${pageHeight}px, viewport height: ${viewportHeight}px, total pages: ${pages}`)
+
+    for (let i = 0; i < pages; i++) {
+      const currentY = i * viewportHeight
+      const fileOutputPath = this.getOutputPath(outputPath, i + 1, pages)
+
+      await this.evaluate(y => window.scrollTo(0, y), currentY)
+      await sleep(320)
+      await this.saveScreenshot(fileOutputPath)
+
+      this.toConsole(`Saved screenshot page ${i + 1}/${pages} to ${fileOutputPath}`)
+    }
+
+    return this
+  }
+
+  /**
+   * Captures a single full page screenshot.
+   *
+   * Создает один скриншот всей страницы.
+   * @param outputPath output path / путь сохранения
+   * @returns this instance / этот экземпляр
+   */
+  protected async screenshotFull(outputPath: string): Promise<this> {
+    const outputPathFull = this.getOutputPath(outputPath)
+    await this.saveScreenshot(outputPathFull)
+
+    this.toConsole(`Saved full page screenshot to ${outputPathFull}`)
+
+    return this
+  }
+
+  /**
+   * Logs text with a "Browser" prefix.
+   *
+   * Выводит текст в консоль с префиксом "Browser".
+   * @param text text to log / текст для вывода
+   */
+  protected toConsole(text: string): void {
+    console.log('Browser', text)
+  }
+}

package/src/classes/Design/DesignFigma.ts

@@ -0,0 +1,34 @@
+import { FigmaApi } from '../FigmaApi'
+import { PropertiesConfig } from '../Properties/PropertiesConfig.ts'
+
+export class DesignFigma {
+  protected readonly api: FigmaApi
+
+  constructor(
+    protected readonly fileKey: string,
+    protected readonly nodeId?: string,
+    protected readonly token: string = PropertiesConfig.getFigmaToken()
+  ) {
+    this.api = new FigmaApi(token, fileKey, nodeId)
+  }
+
+  async make(): Promise<void> {
+    console.log('Design Figma', await this.initImage())
+  }
+
+  async initImage(): Promise<Record<string, string> | undefined> {
+    const image = await this.api.fileImages({
+      ids: this.nodeId as string,
+      format: 'svg',
+      svg_outline_text: false,
+      svg_include_id: true,
+      svg_include_node_id: true
+    })
+
+    if (image?.err) {
+      return undefined
+    }
+
+    return image?.images
+  }
+}

package/src/classes/Design/DesignScreenshot.ts

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process'
+import { ServerStorage } from '@dxtmisha/functional-basic'
+import { BrowserItem } from '../BrowserItem'
+import { PropertiesFile } from '../Properties/PropertiesFile.ts'
+
+/**
+ * Class for automatic capturing of screenshots by running dev server.
+ *
+ * Класс для автоматического захвата скриншотов путем запуска сервера разработки.
+ */
+export class DesignScreenshot {
+  /** indicates if screenshot process is running / указывает, запущен ли процесс создания скриншота */
+  protected isReading: boolean = false
+
+  /** server url / URL сервера */
+  protected url?: string
+
+  /**
+   * Constructor
+   * @param file output path / путь к файлу
+   */
+  constructor(
+    protected readonly file: string = './ai-screenshot/screenshot'
+  ) {
+    ServerStorage.setErrorStatus(true)
+  }
+
+  /**
+   * starts the screenshot process.
+   *
+   * Запускает процесс создания скриншота.
+   */
+  async make() {
+    console.info('Screenshot')
+
+    PropertiesFile.createDir(PropertiesFile.getPathDir(this.file + '.file'))
+    this.makeServer()
+  }
+
+  /**
+   * screenshot trigger listener.
+   *
+   * Слушатель триггера для создания скриншота.
+   * @returns capture success status / статус успешного захвата
+   */
+  protected readonly listener = async (): Promise<boolean> => {
+    if (
+      this.url
+      && !this.isReading
+    ) {
+      this.isReading = true
+
+      console.info('URL', this.url)
+
+      const browser = new BrowserItem(this.url, { height: 1024 * 12 })
+      await browser.screenshot(this.file)
+
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * spawns development server.
+   *
+   * Запускает сервер разработки.
+   * @returns this instance / этот экземпляр
+   */
+  protected makeServer(): this {
+    const server = spawn(
+      'npm',
+      ['run', 'dev'],
+      {
+        shell: true,
+        stdio: 'pipe'
+      }
+    )
+
+    server.stdout?.on('data', (data) => {
+      console.log('Server', 'start')
+
+      const dataString = data.toString()
+      this.makeUrl(dataString)
+
+      if (this.url) {
+        console.info('Server', 'init')
+
+        this.listener()
+          .then((success: boolean) => {
+            if (success) {
+              server.kill()
+
+              console.info('Server', 'kill')
+            }
+          })
+      }
+    })
+
+    server.stderr?.on('data', (data) => {
+      console.error(`Server Error: ${data.toString()}`)
+    })
+
+    return this
+  }
+
+  /**
+   * extracts server url from console output.
+   *
+   * Извлекает URL сервера из консольного вывода.
+   * @param data command output / вывод команды
+   * @returns this instance / этот экземпляр
+   */
+  makeUrl(data: string): this {
+    const match = data.match(/(https?:\/\/localhost\S+)/)
+
+    if (match) {
+      this.url = match[1]
+    }
+
+    return this
+  }
+}

package/src/classes/Design/DesignTypes.ts

@@ -6,7 +6,7 @@ import { PropertiesFile } from '../Properties/PropertiesFile'
 
 import type { DesignTypesList } from '../../types/designTypes'
 
-import { UI_DIR_CONSTRUCTOR, UI_FILE_AI_TYPES } from '../../config'
+import { UI_DIR_CONSTRUCTOR, UI_FILE_AI_DESCRIPTION, UI_FILE_AI_TYPES } from '../../config'
 
 /**
  * Engine for generating compressed and AI-optimized TypeScript type definitions.
@@ -41,19 +41,19 @@ export class DesignTypes {
    *
    * Основной метод для выполнения процесса генерации типов.
    */
-  make() {
+  async make() {
     console.log('DesignTypes: making AI types...')
 
     const files = this.getListByFilter()
     const fullContent = this.toOneFile(files)
 
-    this.toAiEdit(fullContent).then(
-      (aiContent) => {
-        this.save(aiContent)
+    const aiContent = await this.toAiEdit(fullContent)
+    this.save(aiContent)
 
-        console.log('DesignTypes: AI types saved.')
-      }
-    )
+    const aiDescription = await this.toAiDescription(fullContent)
+    this.saveDescription(aiDescription)
+
+    console.log('DesignTypes: AI types saved.')
   }
 
   /**
@@ -168,6 +168,19 @@ export class DesignTypes {
     }
   }
 
+  /**
+   * Saves the AI-generated project description to a file.
+   *
+   * Сохраняет сгенерированное ИИ описание проекта в файл.
+   * @param content content to save / контент для сохранения
+   */
+  protected saveDescription(content: string) {
+    PropertiesFile.writeByPath(
+      UI_FILE_AI_DESCRIPTION,
+      content
+    )
+  }
+
   /**
    * Combines a list of files into a single string.
    *
@@ -183,31 +196,17 @@ export class DesignTypes {
   }
 
   /**
-   * Sends content to AI for optimization.
+   * Sends content and a prompt to the AI for processing.
    *
-   * Отправляет контент ИИ для оптимизации.
-   * @param content content to optimize / контент для оптимизации
+   * Отправляет контент и промпт ИИ для обработки.
+   * @param content content for processing / контент для обработки
+   * @param prompt instructions for the AI / инструкции для ИИ
    */
-  protected async toAiEdit(content: string): Promise<string> {
+  protected async toAi(content: string, prompt: string): Promise<string | undefined> {
     const ai = useAi()
 
     if (ai) {
-      ai.addPrompt(
-        'Remove all Russian comments from this code. '
-        + 'Simplify and shorten all English comments for AI readability while maintaining a clear balance between brevity and context. Do not delete them even if the code seems obvious. '
-        + 'Always keep All JSDoc "@example", "@remarks", "@note", and any other notes or warnings. '
-        + 'Remove all imports. '
-        + 'Remove all non-public content: delete all private and protected class methods and properties, and any non-exported elements. The final output must contain only the members and entities that are accessible from outside. '
-        + 'Remove any code segments or data that do not provide useful information for an AI assistant. '
-        + 'You may remove abstract classes or other structures that provide no practical value for code generation, but do so with extreme caution. Maintain a strict balance: if there is even a 5% chance the item might be relevant for understanding the API or generating code, keep it. Think carefully before every deletion. '
-        + 'Remove any large Enums that add excessive length without providing critical context. '
-        + 'Your goal is to create a compact, context-rich file that enables any AI coding assistant to generate high-quality code for a developer. '
-        + 'Ensure that no public API surface, essential data types, or required logic is lost. '
-        + 'Do not delete any "type" definitions; they are strictly required. '
-        + 'Do not delete file paths (labels starting with "// File:"). '
-        + 'All instructions are mandatory and must be executed perfectly. '
-        + 'Return ONLY the resulting code. No markdown code blocks, no tags, no explanations, and no additional comments from the AI. NOTHING but the pure code.'
-      )
+      ai.addPrompt(prompt)
       ai.addPrompt(`File Content: ${content}`)
 
       const generate = await ai.generate('go!')
@@ -217,6 +216,57 @@ export class DesignTypes {
       }
     }
 
-    return content
+    return undefined
+  }
+
+  /**
+   * Sends content to AI for optimization.
+   *
+   * Отправляет контент ИИ для оптимизации.
+   * @param content content to optimize / контент для оптимизации
+   */
+  protected async toAiEdit(content: string): Promise<string> {
+    const generate = await this.toAi(
+      content,
+      'Remove all Russian comments from this code. '
+      + 'Simplify and shorten all English comments for AI readability while maintaining a clear balance between brevity and context. Do not delete them even if the code seems obvious. '
+      + 'Always keep All JSDoc "@example", "@remarks", "@note", and any other notes or warnings. '
+      + 'Remove all imports. '
+      + 'Remove all non-public content: delete all private and protected class methods and properties, and any non-exported elements. The final output must contain only the members and entities that are accessible from outside. '
+      + 'Remove any code segments or data that do not provide useful information for an AI assistant. '
+      + 'You may remove abstract classes or other structures that provide no practical value for code generation, but do so with extreme caution. Maintain a strict balance: if there is even a 5% chance the item might be relevant for understanding the API or generating code, keep it. Think carefully before every deletion. '
+      + 'Remove any large Enums that add excessive length without providing critical context. '
+      + 'Your goal is to create a compact, context-rich file that enables any AI coding assistant to generate high-quality code for a developer. '
+      + 'Ensure that no public API surface, essential data types, or required logic is lost. '
+      + 'Do not delete any "type" definitions; they are strictly required. '
+      + 'Do not delete file paths (labels starting with "// File:"). '
+      + 'All instructions are mandatory and must be executed perfectly. '
+      + 'Return ONLY the resulting code. No markdown code blocks, no tags, no explanations, and no additional comments from the AI. NOTHING but the pure code.'
+    )
+
+    return generate ?? content
+  }
+
+  /**
+   * Generates a project description and usage guidelines using AI.
+   *
+   * Генерирует описание проекта и рекомендации по использованию с помощью ИИ.
+   * @param content cleaned type definitions / очищенные определения типов
+   */
+  protected async toAiDescription(content: string): Promise<string> {
+    const generate = await this.toAi(
+      content,
+      'Analyze the provided code and generate a highly technical, concise project overview for another AI coding assistant. '
+      + 'Your goal is to help the AI decide whether it needs to study this library to fulfill a user request. '
+      + 'The description must be objective, factual, and free of marketing fluff. '
+      + 'Include: '
+      + '1. Core Purpose: What is the primary function of this library? (e.g., UI component library, state management, utility for X). '
+      + '2. Usage Scenarios: In what specific cases and scenarios is this library indispensable? When should an AI study its API? '
+      + '3. Integration Context: How does it relate to other technologies in the stack (if evident)? '
+      + 'Ensure the structure is clean and enables immediate context retrieval. '
+      + 'Return ONLY the resulting description text. No markdown, no labels like "Description:", no explanations. NOTHING but the pure content.'
+    )
+
+    return generate ?? ''
   }
 }