@dxtmisha/scripts 0.10.8 → 0.10.9

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.10.9] - 2026-08-03
+
+### Changed
+- **DesignTypes**: Updated AI prompt instructions in `DesignTypes.toAiEdit` and `DesignTypes.toAiDescription`:
+  - Enforced strict prompt boundaries forbidding AI agents from analyzing unprovided external files, links, paths, or environment data.
+  - Enhanced JSDoc generation rules to generate English JSDocs for non-obvious entities directly from JS implementation code.
+  - Expanded project description structure in `toAiDescription` to detail all exposed capabilities and triggers for `ai-types.md` analysis, and added optional `code` parameter support.
+
 ## [0.10.8] - 2026-07-28
 
 ### Added / Updated

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/scripts",
   "private": false,
-  "version": "0.10.8",
+  "version": "0.10.9",
   "type": "module",
   "description": "Development scripts and CLI tools for DXT UI projects - automated component generation, library building and project management tools",
   "keywords": [

package/src/classes/Design/DesignTypes.ts

@@ -53,7 +53,7 @@ export class DesignTypes {
     const aiContent = await this.toAiEdit(fullContent, fullJsContent)
     this.save(aiContent)
 
-    const aiDescription = await this.toAiDescription(fullContent)
+    const aiDescription = await this.toAiDescription(fullContent, fullJsContent)
     this.saveDescription(aiDescription)
 
     console.log('DesignTypes: AI types saved.')
@@ -270,25 +270,31 @@ export class DesignTypes {
   protected async toAiEdit(content: string, code: string): Promise<string> {
     const generate = await this.toAi(
       content,
-      'TRANSLATE all non-English comments (including JSDocs and inline comments) to English. '
-      + 'Optimize the provided type definitions, improve and supplement them if necessary. '
-      + 'Carefully study the provided JS code to understand its logic and what the code does. '
-      + 'Remove redundant or self-explanatory JSDoc comments for any entity (types, properties, variables, functions, methods, etc.) if their meaning is obvious from their name or signature and does not require documentation. '
-      + 'Keep or add clear English JSDoc comments for entities that are complex, non-obvious, or require explanation. '
-      + 'CRITICAL: Always keep all JSDoc "@example", "@remarks", "@note", and any other notes or warnings. Their contents must NOT be modified, altered, or rewritten—keep them exactly as written, only translating them to English if they are not in English. '
-      + 'CRITICAL: Remove all imports. Remove all local internal re-exports (e.g., `export * from "./..."`), but strictly KEEP any exports from external libraries or packages. '
-      + '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. '
-      + 'Remove all regular comments and inline comments (lines starting with "//" or "/* ... */"). '
-      + 'Do not include empty lines; keep the output compact and tight without blank lines. '
-      + 'CRITICAL: Do NOT return the provided JS code in your response. '
-      + 'All instructions are mandatory and must be executed perfectly. '
-      + 'Return ONLY the resulting optimized type definitions code. No markdown code blocks, no tags, no explanations, and no additional comments from the AI. NOTHING but the pure code.',
+      'Goal: Optimize and generate clean, highly informative TypeScript type definitions based ONLY on the provided code and types.\n\n'
+      + 'CRITICAL CONTEXT & SCOPE RESTRICTIONS:\n'
+      + '- IMPORTANT: The AI coding agent that will write code for developers using this library will NEVER see or have access to the underlying JS implementation code or external files. It will rely EXCLUSIVELY on the output document generated by you in this session. You MUST ensure that your output provides complete, flawless context, clear JSDoc explanations, and precise type contracts so that the reading AI agent can write accurate code without making assumptions.\n'
+      + '- Analyze ONLY the code, type definitions, and text explicitly provided in this prompt. Do NOT attempt to read, search, infer, or assume any external files, imports, project structure, or unprovided environment data.\n'
+      + '- Do NOT include any references, links, file paths, or pointers to external files or local directories in the final output, as AI agents will have no environment file access.\n'
+      + '- Do NOT return the provided JS code in your response.\n\n'
+      + 'JSDOC & COMMENT RULES:\n'
+      + '- STUDY THE PROVIDED JS CODE: You are explicitly provided with the JS implementation code (`File JS Code`). You MUST study the JS code for every function/method/property to understand its exact logic, behavior, and purpose.\n'
+      + '- GENERATE MISSING JSDOCS FROM JS CODE: If an entity lacks a JSDoc comment in the input declarations, but its provided JS code implementation reveals its behavior or purpose, you MUST generate and add a clear, fluff-free English JSDoc description directly above its declaration.\n'
+      + '- DEFINITION OF OBVIOUS (NO JSDOC): An entity is "obvious" ONLY IF its name uses clear, standard English naming conventions (e.g., `isString`, `capitalize`, `copyObject`) AND its functionality is 100% self-evident from its signature alone. Obvious entities MUST NOT have a JSDoc.\n'
+      + '- MANDATORY JSDOC FOR NON-OBVIOUS ENTITIES: Any entity with an obscure, non-standard, custom, abbreviated, or ambiguous name (e.g., `abutaSudatoho`, `transformation`), or complex logic, MUST have a clear English JSDoc description generated by inspecting its JS implementation code.\n'
+      + '- Write JSDoc comments WITHOUT fluff or filler text, focusing strictly on operational logic and behavior.\n'
+      + '- Place all JSDoc comments STRICTLY directly above the target declaration.\n'
+      + '- Translate all non-English comments and JSDocs to English.\n'
+      + '- Remove regular inline comments (`//` or `/* ... */`).\n'
+      + '- STRICTLY PRESERVE all JSDoc tags like `@example`, `@remarks`, `@note`, and warnings—keep them intact, translating only to English if needed.\n\n'
+      + 'CLEANING & OPTIMIZATION:\n'
+      + '- Remove all `import` statements and local internal re-exports (e.g., `export * from "./..."`). Strictly KEEP exports from external packages.\n'
+      + '- Delete all non-public content (private/protected class members, unexported elements). Keep all public API surfaces.\n'
+      + '- Do NOT delete any `type` definitions; they are strictly required.\n'
+      + '- Remove large Enums or structures that add length without critical context.\n'
+      + '- Exercise extreme caution when removing abstract classes: if there is even a 5% chance it helps understand the API or generate code, keep it.\n'
+      + '- Format output tightly with no blank lines.\n\n'
+      + 'OUTPUT REQUIREMENTS:\n'
+      + 'Return ONLY the resulting optimized TypeScript type definitions code. No markdown formatting, no code blocks (```), no explanations, and no additional AI text. NOTHING but pure code.',
       code
     )
 
@@ -300,20 +306,24 @@ export class DesignTypes {
    *
    * Генерирует описание проекта и рекомендации по использованию с помощью ИИ.
    * @param content cleaned type definitions / очищенные определения типов
+   * @param code JS code for analysis / JS код для анализа
    */
-  protected async toAiDescription(content: string): Promise<string> {
+  protected async toAiDescription(content: string, code?: string): Promise<string> {
     const generate = await this.toAi(
       content,
-      'Analyze the provided code and generate a highly technical, structured, and concise project overview specifically designed for another AI coding assistant. '
-      + 'The description must enable the reading AI to immediately evaluate whether this library contains code, components, classes, or utilities useful for its current task, and when it is mandatory to read and analyze "ai-types.md". '
-      + 'The description must be objective, factual, precise, and free of marketing fluff. '
-      + 'Include: '
-      + '1. Core Purpose: What is the primary technical function of this library? '
-      + '2. Key Expositions: What are the main classes, hooks, utilities, or components exposed by this project, and what specific tasks do they perform? '
-      + '3. Triggers for Studying ai-types.md: Under what specific conditions, keywords, or coding requirements is this library indispensable, making it mandatory for the AI to study its "ai-types.md" file? '
-      + '4. Integration Context: How does it connect with other technologies in the system stack? '
-      + '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.'
+      'Goal: Generate a comprehensive, highly technical, and fluff-free project overview designed for an AI coding assistant to evaluate this library\'s exact contents and capabilities.\n\n'
+      + 'CRITICAL RESTRICTIONS:\n'
+      + '- Analyze ONLY the code, type definitions, and text explicitly provided in this prompt. Do NOT attempt to read, search, infer, or assume any external files, dependencies, or unprovided data.\n'
+      + '- Do NOT include any file paths, relative links, or external URLs, as reading AI agents will not have environment file access.\n\n'
+      + 'STRUCTURE & CONTENT REQUIREMENTS:\n'
+      + 'Provide an objective, dense, and complete technical summary including:\n'
+      + '1. Core Purpose: What is the primary technical function, responsibility, and role of this library?\n'
+      + '2. Key Expositions & Capabilities: Detail ALL main classes, composables/hooks, utilities, components, services, or data structures exposed by this library. Specify the exact functionality and specific tasks each exposed entity or module performs so reading AI agents clearly understand the full capability set.\n'
+      + '3. Triggers for Studying ai-types.md: Under what specific coding requirements, keywords, tasks, or architectural needs is this library indispensable, making it mandatory for the AI to study "ai-types.md"?\n'
+      + '4. Integration Context: How does this library connect with other technologies, frameworks, or packages in the system stack?\n\n'
+      + 'OUTPUT REQUIREMENTS:\n'
+      + 'Return ONLY the resulting description text. No markdown formatting, no code blocks, no labels (like "Description:"), and no conversational explanations. NOTHING but pure, dense content.',
+      code
     )
 
     return generate ?? ''