@dxtmisha/scripts 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.10.0] - 2026-05-20
+
+### Added
+- **OpenAI Provider**: Implemented `AiOpenAiLite` and `AiOpenAi` classes providing a fully typed OpenAI SDK integration, supporting chat completions with image and text content blocks.
+- **Z.ai Provider**: Implemented `AiZAiLite` and `AiZAi` classes as OpenAI-compatible Zhipu AI integration, automatically routing to the correct endpoint (`api.z.ai` for international access). The `baseURL` is configurable via `aiConfig.baseURL` in `design.config.json`.
+- **Claude Agent Provider**: Added `AiClaudeAgent` and `AiClaudeAgentLite` classes supporting the extended Anthropic agent API workflow.
+- **Build Orchestration**: Introduced `BuildPackages` and `BuildPublishPackages` classes for comprehensive monorepo build and publish orchestration with incremental tracking support.
+- **Package Management**: Added `PackageFile` class for structured package configuration file handling.
+- **`run` utility**: Added a new `run()` utility function for streamlined subprocess execution across scripts.
+
+### Changed
+- **`AiType` config type**: Expanded `AiType` to include all supported providers: `'claude' | 'claude-cli' | 'claude-agent' | 'gemini' | 'gemini-cli' | 'openai' | 'zai'`. Previously only `gemini` and `gemini-cli` were available.
+- **`useAi` composable**: Updated routing switch to instantiate the correct AI class for all providers including `claude`, `claude-agent`, `claude-cli`, `openai`, and `zai`.
+- **Library exports**: Updated `library.ts` and `library-ai.ts` to export all new AI provider classes, agent classes, build orchestration classes and the `run` utility.
+
+### Removed
+- **CLI variants from `library-ai.ts`**: Removed exports of `AiGoogleCli`, `AiGoogleCliLite`, `AiClaudeCli`, and `AiClaudeCliLite` from the lightweight AI-only export surface. These remain accessible via the main `library.ts` entry point.
+
+---
+
+## [0.9.1] - 2026-05-18
+
+### Changed
+- **Component Documentation Prompts**: Overhauled `componentPrompt.en.txt` and `componentPrompt.ru.txt` to enforce `storybookStyle.scss` helper usage in Storybook stories, standardized slot/expose signature formatting, and mandatory `<Source />` code block inclusion.
+- **Architectural Guardrails**: Added strict instructions against code modifications and hallucinations during AI-assisted code and documentation generation.
+- **Wiki Template**: Updated `componentDoc/wiki/run.ts` to dynamically resolve and read prompt instructions from `prompt.txt`.
+- **Template Structure**: Created `componentDoc/materials/` workspace directory with `README.md` and `prompt.txt` templates containing target implementation instructions and monorepo context.
+
+
+
 ## [0.8.2] - 2026-05-13
 
 ### Changed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/scripts",
   "private": false,
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Development scripts and CLI tools for DXT UI projects - automated component generation, library building and project management tools",
   "keywords": [
@@ -78,6 +78,7 @@
     "@dxtmisha/styles": "*",
     "@dxtmisha/wiki": "*",
     "@google/genai": "*",
+    "openai": "*",
     "puppeteer": "*",
     "typescript": "*",
     "vue": "*"

package/src/classes/Ai/AiClaudeAgent.ts

@@ -0,0 +1,16 @@
+import { getConfigAi } from '../../functions/getConfigAi'
+import { AiClaudeAgentLite } from './AiClaudeAgentLite'
+
+/**
+ * Claude AI implementation via Agent SDK.
+ * Uses @anthropic-ai/claude-agent-sdk to interact with Claude as an agent.
+ *
+ * Реализация Claude AI через Agent SDK.
+ */
+export class AiClaudeAgent extends AiClaudeAgentLite {
+  constructor() {
+    super(
+      ...getConfigAi()
+    )
+  }
+}

package/src/classes/Ai/AiClaudeAgentLite.ts

@@ -0,0 +1,86 @@
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import { AiAbstract } from './AiAbstract'
+
+/**
+ * Claude AI implementation via Agent SDK.
+ * Uses @anthropic-ai/claude-agent-sdk to interact with Claude as an agent.
+ *
+ * Реализация Claude AI через Agent SDK.
+ * Использует @anthropic-ai/claude-agent-sdk для взаимодействия с Claude в режиме агента.
+ *
+ * Responsibilities / Ответственности:
+ * - Initialize Agent SDK client / Инициализировать Agent SDK клиент
+ * - Execute query via Agent SDK / Выполнить запрос через Agent SDK
+ * - Extract and return textual result / Извлечь и вернуть текстовый результат
+ */
+export class AiClaudeAgentLite extends AiAbstract<{}> {
+  /**
+   * Initializes the "client".
+   * For Agent SDK, we mark it as initialized.
+   */
+  protected init(): void {
+    this.ai = {}
+  }
+
+  /**
+   * Implementation hook: convert accumulated images to model-specific format.
+   * Agent SDK implementation logic for images can be added if supported by the SDK.
+   */
+  protected toImages(): any {
+    return []
+  }
+
+  /**
+   * Implementation hook: convert accumulated contents to model-specific format.
+   */
+  protected toContents(): any {
+    return this.contents.join('\n\n')
+  }
+
+  /**
+   * Performs content generation request via Agent SDK and returns textual result.
+   *
+   * @param model Model identifier / Идентификатор модели
+   * @param contents Composed contents for generation / Собранный контент для генерации
+   */
+  protected async response(
+    model: string,
+    contents: string
+  ): Promise<string> {
+    const fullPrompt = [
+      this.toContents(),
+      contents
+    ].filter(Boolean).join('\n\n')
+
+    try {
+      const q = query({
+        prompt: fullPrompt,
+        options: {
+          model: model || undefined,
+          env: {
+            ...process.env,
+            ANTHROPIC_API_KEY: this.key
+          },
+          permissionMode: 'acceptEdits', // Auto-accept file changes if any
+          allowDangerouslySkipPermissions: true,
+          ...this.config
+        }
+      })
+
+      let lastResult = ''
+
+      for await (const message of q) {
+        if (message.type === 'result') {
+          if (message.subtype === 'success') {
+            lastResult = message.result
+          }
+        }
+      }
+
+      return lastResult.trim()
+    } catch (error) {
+      console.error('[AiClaudeAgent] Error:', error)
+      return ''
+    }
+  }
+}

package/src/classes/Ai/AiClaudeCliLite.ts

@@ -1,10 +1,8 @@
 import { forEach } from '@dxtmisha/functional-basic'
 import { exec } from 'node:child_process'
 
-import { PropertiesFile } from '../Properties/PropertiesFile'
 import { AiAbstract } from './AiAbstract'
-
-const TEMPORARY_DIR = './ai-tmp'
+import { ApiTmp } from './ApiTmp'
 
 /**
  * Claude AI implementation via CLI.
@@ -19,24 +17,11 @@ const TEMPORARY_DIR = './ai-tmp'
  * - Return stdout as result / Вернуть stdout как результат
  *
  * Notes / Примечания:
- * - Requires 'claude' CLI tool installed (e.g., claude-cli) / Требует установленной утилиты 'claude'
+ * - Requires 'claude' CLI tool installed / Требует установленной утилиты 'claude'
  * - API key is passed via environment variable or config / API ключ передается через переменную окружения или конфиг
  */
 export class AiClaudeCliLite extends AiAbstract<{}> {
-  /**
-   * Counter for generating unique temporary file names/
-   * Счетчик для генерации уникальных имен временных файлов
-   */
-  protected idFile = 1
-
-  /**
-   * Generates a unique file path for the temporary prompt.
-   *
-   * Генерирует уникальный путь к файлу для временного промпта.
-   */
-  protected getFileName(): string {
-    return `${TEMPORARY_DIR}/Prompt-${this.idFile++}.txt`
-  }
+  protected readonly tmp = new ApiTmp()
 
   /**
    * Initializes the "client".
@@ -70,7 +55,7 @@ export class AiClaudeCliLite extends AiAbstract<{}> {
   protected toContents(): any {
     return forEach(
       this.contents,
-      content => this.createFile(content)
+      content => this.tmp.createFile(content)
     )
   }
 
@@ -88,58 +73,37 @@ export class AiClaudeCliLite extends AiAbstract<{}> {
     return new Promise((resolve) => {
       const fullPrompt = [
         ...this.toContents(),
-        this.createFile(contents)
+        this.tmp.createFile(contents)
       ].join('\n\n##################\n\n')
 
       const escapedPrompt = fullPrompt.replace(/"/g, '\\"')
       const modelFlag = model ? ` --model "${model}"` : ''
-      const command = `claude "${escapedPrompt}" Output strictly the code/answer. No preamble, no chatter, no reasoning ${modelFlag}`
+      const command = `claude "${escapedPrompt} -- Output strictly the code/answer. No preamble, no chatter, no reasoning" ${modelFlag}`
 
-      exec(
-        command,
-        {
-          encoding: 'utf8',
-          env: {
-            ...process.env,
-            ANTHROPIC_API_KEY: this.key
-          }
-        },
-        (error, stdout, stderr) => {
-          if (error) {
-            console.error('Error executing Claude CLI:', stderr || error.message)
-            resolve('')
-          } else {
-            resolve(stdout.trim())
-          }
-        }
-      )
+      try {
+        exec(
+          command,
+          {
+            encoding: 'utf8',
+            env: {
+              ...process.env
+            }
+          },
+          (error, stdout, stderr) => {
+            if (error) {
+              console.error('Error executing Claude CLI:', stderr || error.message)
+              resolve('')
+            } else {
+              resolve(stdout.trim())
+            }
 
-      this.removeFile()
+            this.tmp.removeFile()
+          }
+        )
+      } catch (_) {
+        this.tmp.removeFile()
+      }
     })
   }
-
-  /**
-   * Creates a temporary file with the prompt content and returns the path formatted for the CLI.
-   *
-   * Создает временный файл с содержимым промпта и возвращает путь, отформатированный для CLI.
-   * @param content Prompt content / Содержимое промпта
-   * @returns Formatted file path (e.g., @./ai-tmp/Prompt-1.txt) / Отформатированный путь к файлу
-   */
-  protected createFile(content: string): string {
-    const name = this.getFileName()
-
-    PropertiesFile.writeByPath(name, content)
-
-    return `Please read the following file as it contains the prompt instructions: @${name}`
-  }
-
-  /**
-   * Cleans up temporary files and directories.
-   *
-   * Очищает временные файлы и директории.
-   * @protected
-   */
-  protected removeFile(): void {
-    PropertiesFile.removeDir(TEMPORARY_DIR)
-  }
 }
+

package/src/classes/Ai/AiClaudeLite.ts

@@ -1,6 +1,7 @@
+import { Anthropic } from '@anthropic-ai/sdk'
 import { forEach } from '@dxtmisha/functional-basic'
+
 import { AiAbstract } from './AiAbstract'
-import { Anthropic } from '@anthropic-ai/sdk'
 
 /**
  * Claude AI implementation of AiAbstract.
@@ -89,12 +90,23 @@ export class AiClaudeLite extends AiAbstract<Anthropic> {
       ...this.config
     })
 
-    // Extract text from content blocks
-    const textContent = message?.content
-      ?.filter(block => block.type === 'text')
-      .map(block => 'text' in block ? block.text : '')
-      .join('\n')
+    if (message?.content) {
+      return forEach(
+        message.content,
+        (block) => {
+          if (
+            block.type === 'text'
+            && 'text' in block
+          ) {
+            return block.text
+          }
+
+          return undefined
+        }
+      )
+        .join('\n')
+    }
 
-    return textContent ?? ''
+    return ''
   }
 }

package/src/classes/Ai/AiGoogleCliLite.ts

@@ -1,10 +1,8 @@
 import { forEach } from '@dxtmisha/functional-basic'
 import { exec } from 'node:child_process'
 
-import { PropertiesFile } from '../Properties/PropertiesFile'
 import { AiAbstract } from './AiAbstract'
-
-const TEMPORARY_DIR = './ai-tmp'
+import { ApiTmp } from './ApiTmp'
 
 /**
  * Google AI (Gemini) implementation via CLI.
@@ -23,20 +21,7 @@ const TEMPORARY_DIR = './ai-tmp'
  * - API key is passed via environment variable or config / API ключ передается через переменную окружения или конфиг
  */
 export class AiGoogleCliLite extends AiAbstract<{}> {
-  /**
-   * Counter for generating unique temporary file names/
-   * Счетчик для генерации уникальных имен временных файлов
-   */
-  protected idFile = 1
-
-  /**
-   * Generates a unique file path for the temporary prompt.
-   *
-   * Генерирует уникальный путь к файлу для временного промпта.
-   */
-  protected getFileName(): string {
-    return `${TEMPORARY_DIR}/Prompt-${this.idFile++}.txt`
-  }
+  protected readonly tmp = new ApiTmp()
 
   /**
    * Initializes the "client".
@@ -70,7 +55,7 @@ export class AiGoogleCliLite extends AiAbstract<{}> {
   protected toContents(): any {
     return forEach(
       this.contents,
-      content => this.createFile(content)
+      content => this.tmp.createFile(content)
     )
   }
 
@@ -88,58 +73,36 @@ export class AiGoogleCliLite extends AiAbstract<{}> {
     return new Promise((resolve) => {
       const fullPrompt = [
         ...this.toContents(),
-        this.createFile(contents)
+        this.tmp.createFile(contents)
       ].join('\n\n##################\n\n')
 
       const escapedPrompt = fullPrompt.replace(/"/g, '\\"')
       const modelFlag = model ? ` --model "${model}"` : ''
-      const command = `gemini "${escapedPrompt}" Output strictly the code/answer. No preamble, no chatter, no reasoning ${modelFlag} --yolo`
+      const command = `gemini "${escapedPrompt} -- Output strictly the code/answer. No preamble, no chatter, no reasoning" ${modelFlag} --yolo`
 
-      exec(
-        command,
-        {
-          encoding: 'utf8',
-          env: {
-            ...process.env,
-            GEMINI_API_KEY: this.key
-          }
-        },
-        (error, stdout, stderr) => {
-          if (error) {
-            console.error('Error executing Gemini CLI:', stderr || error.message)
-            resolve('')
-          } else {
-            resolve(stdout.trim())
-          }
-        }
-      )
+      try {
+        exec(
+          command,
+          {
+            encoding: 'utf8',
+            env: {
+              ...process.env
+            }
+          },
+          (error, stdout, stderr) => {
+            if (error) {
+              console.error('Error executing Gemini CLI:', stderr || error.message)
+              resolve('')
+            } else {
+              resolve(stdout.trim())
+            }
 
-      this.removeFile()
+            this.tmp.removeFile()
+          }
+        )
+      } catch (_) {
+        this.tmp.removeFile()
+      }
     })
   }
-
-  /**
-   * Creates a temporary file with the prompt content and returns the path formatted for the CLI.
-   *
-   * Создает временный файл с содержимым промпта и возвращает путь, отформатированный для CLI.
-   * @param content Prompt content / Содержимое промпта
-   * @returns Formatted file path (e.g., @./ai-tmp/Prompt-1.txt) / Отформатированный путь к файлу
-   */
-  protected createFile(content: string): string {
-    const name = this.getFileName()
-
-    PropertiesFile.writeByPath(name, content)
-
-    return `Please read the following file as it contains the prompt instructions: @${name}`
-  }
-
-  /**
-   * Cleans up temporary files and directories.
-   *
-   * Очищает временные файлы и директории.
-   * @protected
-   */
-  protected removeFile(): void {
-    PropertiesFile.removeDir(TEMPORARY_DIR)
-  }
 }

package/src/classes/Ai/AiOpenAi.ts

@@ -0,0 +1,26 @@
+import { AiOpenAiLite } from './AiOpenAiLite'
+import { getConfigAi } from '../../functions/getConfigAi'
+
+/**
+ * OpenAI implementation of AiAbstract.
+ * Initializes OpenAI client and performs text generation requests.
+ *
+ * Реализация OpenAI поверх AiAbstract.
+ * Инициализирует клиент OpenAI и выполняет запросы генерации текста.
+ *
+ * Responsibilities / Ответственности:
+ * - Provide API key / Предоставить API ключ
+ * - Initialize low-level client / Инициализировать низкоуровневый клиент
+ * - Call chat.completions.create and extract plain text / Вызвать chat.completions.create и извлечь текст
+ *
+ * Notes / Примечания:
+ * - Model must be set via setModel() before generate() / Модель нужно задать через setModel()
+ * - Returns empty string if response is missing / Возвращает пустую строку при отсутствии результата
+ */
+export class AiOpenAi extends AiOpenAiLite {
+  constructor() {
+    super(
+      ...getConfigAi()
+    )
+  }
+}

package/src/classes/Ai/AiOpenAiLite.ts

@@ -0,0 +1,107 @@
+import { OpenAI } from 'openai'
+import { forEach } from '@dxtmisha/functional-basic'
+
+import { AiAbstract } from './AiAbstract'
+
+/**
+ * OpenAI implementation of AiAbstract.
+ * Initializes OpenAI client and performs text generation requests.
+ *
+ * Реализация OpenAI поверх AiAbstract.
+ * Инициализирует клиент OpenAI и выполняет запросы генерации текста.
+ *
+ * Responsibilities / Ответственности:
+ * - Provide API key / Предоставить API ключ
+ * - Initialize OpenAI client / Инициализировать клиент OpenAI
+ * - Call chat.completions.create and extract text content / Вызвать chat.completions.create и извлечь текст
+ *
+ * Notes / Примечания:
+ * - Model must be set via setModel() before generate() / Модель нужно задать через setModel()
+ * - Returns empty string if response is missing / Возвращает пустую строку при отсутствии результата
+ */
+export class AiOpenAiLite extends AiAbstract<OpenAI> {
+  /**
+   * Initializes OpenAI client instance.
+   *
+   * Инициализирует экземпляр клиента OpenAI.
+   */
+  protected init(): void {
+    this.ai = new OpenAI({
+      apiKey: this.key
+    })
+  }
+
+  /**
+   * Implementation hook: convert accumulated images to model-specific format.
+   * OpenAI expects images as content blocks with type 'image_url'.
+   *
+   * Хук реализации: преобразовать накопленные изображения в формат, специфичный для модели.
+   * OpenAI ожидает изображения как блоки контента с типом 'image_url'.
+   */
+  protected toImages(): any {
+    return forEach(this.images, image => ({
+      type: 'image_url',
+      image_url: {
+        url: `data:${image.mime};base64,${image.base64}`
+      }
+    }))
+  }
+
+  /**
+   * Implementation hook: convert accumulated contents to model-specific format.
+   * OpenAI expects text as content blocks with type 'text'.
+   *
+   * Хук реализации: преобразовать накопленное содержимое в формат, специфичный для модели.
+   * OpenAI ожидает текст как блоки контента с типом 'text'.
+   */
+  protected toContents(): any {
+    return forEach(this.contents, content => ({
+      type: 'text',
+      text: content
+    }))
+  }
+
+  /**
+   * Performs content generation request and returns textual result.
+   *
+   * Выполняет запрос генерации контента и возвращает текстовый результат.
+   * @param model Model identifier (e.g., 'gpt-4o') / Идентификатор модели
+   * @param contents Composed contents for generation / Собранный контент для генерации
+   */
+  protected async response(
+    model: string,
+    contents: string
+  ): Promise<string> {
+    console.log('asd', this.ai?.baseURL, JSON.stringify({
+      model,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            ...this.toImages(),
+            ...this.toContents(),
+            { type: 'text', text: contents }
+          ]
+        }
+      ],
+      ...this.config
+    }))
+
+    const response = await this.ai?.chat.completions.create({
+      model,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            ...this.toImages(),
+            ...this.toContents(),
+            { type: 'text', text: contents }
+          ]
+        }
+      ],
+      ...this.config
+    })
+
+    return response?.choices?.[0]?.message?.content ?? ''
+  }
+}

package/src/classes/Ai/AiZAi.ts

@@ -0,0 +1,17 @@
+import { getConfigAi } from '../../functions/getConfigAi'
+import { AiZAiLite } from './AiZAiLite'
+
+/**
+ * Z.ai (Zhipu AI) implementation extending AiZAiLite.
+ * Automatically configured using project environment settings.
+ *
+ * Реализация Z.ai (Zhipu AI) расширяющая AiZAiLite.
+ * Автоматически настраивается с использованием настроек окружения проекта.
+ */
+export class AiZAi extends AiZAiLite {
+  constructor() {
+    super(
+      ...getConfigAi()
+    )
+  }
+}

package/src/classes/Ai/AiZAiLite.ts

@@ -0,0 +1,26 @@
+import { OpenAI } from 'openai'
+import { AiOpenAiLite } from './AiOpenAiLite'
+
+/**
+ * Z.ai (Zhipu AI) implementation extending AiOpenAiLite.
+ * Performs requests to the OpenAI-compatible Z.ai endpoint.
+ *
+ * Реализация Z.ai (Zhipu AI) расширяющая AiOpenAiLite.
+ * Выполняет запросы к OpenAI-совместимому эндпоинту Z.ai.
+ *
+ * Responsibilities / Ответственности:
+ * - Initialize OpenAI client with Z.ai baseURL / Инициализировать клиент OpenAI с baseURL Z.ai
+ */
+export class AiZAiLite extends AiOpenAiLite {
+  /**
+   * Initializes OpenAI client instance configured for Z.ai.
+   *
+   * Инициализирует экземпляр клиента OpenAI, настроенный для Z.ai.
+   */
+  protected override init(): void {
+    this.ai = new OpenAI({
+      apiKey: this.key,
+      baseURL: 'https://api.z.ai/api/paas/v4'
+    })
+  }
+}

package/src/classes/Ai/ApiTmp.ts

@@ -0,0 +1,43 @@
+import { PropertiesFile } from '../Properties/PropertiesFile'
+
+const TEMPORARY_DIR = './ai-tmp'
+
+/**
+ * ApiTmp
+ */
+export class ApiTmp {
+  protected idFile = 1
+
+  /**
+   * Generates a unique file path for the temporary prompt.
+   *
+   * Генерирует уникальный путь к файлу для временного промпта.
+   */
+  protected getFileName(): string {
+    return `${TEMPORARY_DIR}/Prompt-${this.idFile++}.txt`
+  }
+
+  /**
+   * Creates a temporary file with the prompt content and returns the path formatted for the CLI.
+   *
+   * Создает временный файл с содержимым промпта и возвращает путь, отформатированный для CLI.
+   * @param content Prompt content / Содержимое промпта
+   * @returns Formatted file path (e.g., @./ai-tmp/Prompt-1.txt) / Отформатированный путь к файлу
+   */
+  createFile(content: string): string {
+    const name = this.getFileName()
+
+    PropertiesFile.writeByPath(name, content.trim())
+
+    return `Please read the following file as it contains the prompt instructions: @${name}`
+  }
+
+  /**
+   * Cleans up temporary files and directories.
+   *
+   * Очищает временные файлы и директории.
+   */
+  removeFile(): void {
+    PropertiesFile.removeDir(TEMPORARY_DIR)
+  }
+}